SSO with your identity provider

Sign-in per deployment

Set up sign-in

Air-Gapped chart values

client-auth:
  env:
    APP_URL: https://<app-host>        # the UI origin, no trailing slash; it forms the redirect_uri
ui:
  authProviders: [sso]                 # renders the SSO button

client-auth is published as client-auth.<domain> and also serves skill OAuth redirects. Google and GitHub social buttons are a separate path (GoTrue providers, supabase.auth.extraEnv in the chart).

How a sign-in works

1. The user clicks SSO and types their work email under Sign in with SSO. The email only picks the organization and is never sent to the IdP.
2. client-auth redirects the browser to your IdP with scopes openid profile email plus any you add. The client is confidential (client_id and client_secret, no PKCE).
3. The IdP redirects back to https://<app-host>/oidc/<organization-id>/callback with a code.
4. client-auth exchanges the code and reads the user from the IdP’s userinfo endpoint, from inside the cluster.
5. xpander finds or creates the user by email in GoTrue and starts the session.

Keycloak and preferred_username

Keycloak sends the account username, so user creation fails with Unable to validate email address: invalid format. Map the email onto it:

1. Client scopes, the client’s dedicated scope, Add mapper, By configuration, User Property.
2. Name preferred_username, Property email, Token Claim Name preferred_username, type String, “Add to userinfo” on.
3. Retry the SSO sign-in.

Or set “Email as username” under Realm settings, Login. Releases with the September 2026 edge-functions image or later read email first, but add the mapper anyway: it works on every release.

Running Keycloak yourself

Setting	Why
--hostname=https://<keycloak host>/auth	A pathless hostname advertises endpoints the server then refuses
--hostname-backchannel-dynamic=true	Pods use an internal name, browsers the public one
--proxy-headers=xforwarded	Needed behind a load balancer

Give the pod at least 2 GiB when you use kcadm.sh (each call starts a second JVM). Install Keycloak after its database, role and admin secret exist, or the release deadlocks.

Group sync with Keycloak

1. Create a groups client scope. Client scopes, Create client scope, name groups, type Optional. Add a Group Membership mapper: name groups, Token Claim Name groups, Full group path off, Add to userinfo on. Then add groups to your xpander client as Optional. A mapper on the dedicated scope alone is not enough: Keycloak answers error=invalid_scope.
2. Request the scope. Under Additional sign-in scopes, Add groups, then Save configuration. xpander records claim groups from userinfo.
3. Sign in once, so xpander sees the group values.
4. Link a group. Platform > Organization > Members & groups, the group’s menu, Link SSO groups. Pick a seen value or Add a group by name or ID with Add to list, then Save links. The row shows an SSO badge.

Agent pre-authentication

When it fails

Next steps