Skip to main content

​
Sign-in per deployment

Roles are Admin and Team member (Settings > Team); groups under Settings > User groups can follow the identity provider’s groups. See Govern every agent.

​
The OIDC client

Create a confidential OIDC client for xpander at the identity provider: Settings > OIDC in xpander holds the issuer URL, exactly as it appears in the discovery document, including any context path. A Keycloak instance under /auth uses https://idp.example.com/auth/realms/<realm>. It also holds the client ID and secret, and optional extra scopes. An optional API service app card adds a second client’s ID and secret, plus a generated Directory key. Directory reads and agent token exchange use this second app; Okta needs key-pair authentication on it. The page also has the agent pre-authentication switch. The token and userinfo calls run from inside the cluster, so the IdP must be reachable from the pods, not only from the browser; an IP-restricted public entry point refuses them.
OIDC identity provider fields

Settings > OIDC: issuer, client, scopes and the API service app card. Shown with sample data.

OIDC settings showing Sign-in, Sign-out and Initiate login redirect URIs, then an Agent pre-authentication card with the Enable agent pre-authentication switch on, one audience, two token exchange scopes and a Save configuration button

Settings > OIDC: the three redirect URIs and the Agent pre-authentication card with its switch, Audiences and Token exchange scopes. Shown with sample data.

​
Group sync

Group membership from the IdP maps to xpander user groups through a groups claim. The recipe, for Keycloak:
  1. At the IdP, a client scope named groups with a Group Membership mapper (claim groups, full path off, in userinfo), assigned to the xpander client as an optional scope. A mapper on the client alone is not enough: xpander requests scope=groups, and Keycloak answers error=invalid_scope when no client scope of that name exists.
  2. Settings > OIDC > Additional sign-in scopes: Add, type groups, Save configuration.
  3. After the next sign-in the values the IdP sent are known to xpander. Under Settings > User groups, open the group row’s menu (three dots) and choose Link SSO groups. The dialog lists the observed values, takes a value typed by hand, and saves with Save links. The row then shows an SSO badge.
  4. Members of the linked identity-provider groups join the xpander group at their next sign-in.
Link SSO groups to Ops dialog reading 'Members of the linked identity-provider groups join this group at their next sign-in', with a search box, one observed group value, a manual entry field and a Save links button

Link SSO groups: the observed identity-provider values, a manual entry field and Save links. Shown with sample data.

User groups list with a Default group and an Ops group carrying an SSO badge and the line 'Linked to the Keycloak acme-ops group', with a toast reading SSO group links saved

Settings > User groups after Save links: the group carries an SSO badge and names the linked identity-provider group. Shown with sample data.

When the IdP answers the callback with an error, the browser lands on / signed out with no message; the error= parameter is on the callback request in the browser’s network log. The Keycloak screens, the preferred_username mapper and the failure table are on SSO with your identity provider.

​
Agent pre-authentication

Agent pre-authentication uses OIDC token exchange. At the moment of a call, xpander exchanges the asking person’s sign-in token for one scoped to the target system, so the agent acts with that person’s permissions where the outside system allows it. The IdP client needs token exchange enabled (Keycloak 26: the client attribute standard.token.exchange.enabled=true), direct access grants, an audience client for the target system, and a client scope with an audience mapper. In xpander, Settings > OIDC > Agent pre-authentication holds the Enable agent pre-authentication switch, Audiences (one per target system) and Token exchange scopes. Save configuration applies them. Leave it off to start.

​
Self-hosted chart values

The Keycloak preferred_username mapper, the failure table and the pods to read logs from are on SSO with your identity provider.