Single sign-on and identity

Connect your identity provider so users sign in with the credentials they already use, and map identity provider groups to workspace roles.

Audience: IT (the enabler) and risk and compliance

The platform supports OpenID Connect (OIDC) as the identity layer. Any OIDC-compliant identity provider works: Okta, Microsoft Entra ID, Google Workspace, Auth0, and others. Discovery is handled by the standard /.well-known/openid-configuration document on the issuer, and JWKS rotation takes effect without a restart.

SSO is configured at deployment time, not in the product UI. There is no in-product surface for adding an identity provider, rotating a client secret, or editing the group-to-role map. On a self-hosted deployment you set these in your Helm values and upgrade; the chart renders them into the API's environment. Changes take effect on restart, and the platform reads the discovery doc on first use.

What SSO covers

Sign-in. Every user authenticates through your IdP. The session cookie issued after a successful exchange is the only credential the web app trusts.
Identity claims. The platform reads sub, email, email_verified, name, given_name, family_name, and picture from the ID token. Profile attributes are mapped to the workspace user record on first sign-in and refreshed on each session.
Group-to-role mapping. Groups on the ID token, read from the claim you configure, can grant the admin or member role. Unmapped groups are ignored, so users with no mapped group land as members.

What SSO does not cover

Per-Project permissions. Project membership and team membership are managed inside the platform, not by your IdP. SSO authenticates the user; the workspace decides what they can reach. See Workspace, teams, and users.
Owner promotion. The Owner role is never granted by a group claim. Owners are managed through the API.
Per-integration credentials. OAuth credentials for SharePoint, Gmail, GitHub, and the other connectors are separate from SSO. See How connections get set up.

Configure OIDC

On a self-hosted deployment, OIDC is configured in your Helm values. The chart renders them into the API's environment as AS_API_OIDC_*, which is where they surface if you are reading a running pod.

Register the application in your IdP

Identity providers (OIDC) covers this: the URLs to register, and step-by-step guides for Microsoft Entra ID, Auth0, and Okta. Come back with the discovery URL, client ID, and client secret.

Set them in your values file

The OIDC settings live under api.config.auth.oidc in the values you install with:

api:
  config:
    auth:
      oidc:
        server: https://your-idp.example.com       # discovery URL, or the issuer it is served under
        clientId: REPLACE_ME
        clientSecret: REPLACE_ME
        redirectUri: ""                            # empty derives <applicationUrl>/api/v1/auth/callback
        groupsClaimName: groups
        groupRoleMap: "admin=admin,member=member"

groupsClaimName and groupRoleMap are the two worth reviewing. The chart ships groups and admin=admin,member=member; whether those match your IdP is the usual reason an SSO rollout lands everyone as a member.

Upgrade and verify

Run the upgrade and open the sign-in page in a private window. The discovery doc and JWKS are fetched lazily on first use, so the first sign-in is what proves the configuration.

Map groups to roles

groupRoleMap declares which groups grant which workspace role. It accepts a JSON object or a comma-separated list of group=role pairs, and only admin and member are valid roles. Groups not listed grant nothing, and a user with no mapped group still lands as member on first sign-in.

groupRoleMap: '{"platform-admins":"admin","platform-users":"member"}'

Upgrade to apply a change. Existing sessions keep their current role until the next sign-in.

Verify the SSO connection

After deployment, sign in once and confirm three things in the platform:

The new user appears on /users with the email and display name from the ID token.
The role on the row matches the group your IdP returned.
The audit ledger records a session.signed_in entry for the user.

Common errors

AADSTS900023 on Microsoft Entra ID. The OIDC issuer URL uses the tenant GUID, common, organizations, or consumers. Do not paste the SingleTenant or MultiTenant discriminator. The same trap applies to SharePoint, Teams, and Outlook integrations.
Discovery doc unreachable. The platform fetches {issuer}/.well-known/openid-configuration on first use. A firewall or egress rule that blocks outbound calls from the API pods will manifest as sign-in failures with no readable error. Confirm outbound HTTPS to the issuer from the deployment network.
User signs in but lands as a member when admin is expected. Confirm the groups claim is present on the ID token (decode the token at the IdP's debugger), confirm groupsClaimName matches the actual claim name, and confirm the group is listed in groupRoleMap.

Workspace, teams, and users Connections