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 in v3. Configuration flows through environment variables on the API deployment and changes take effect on restart. 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 (default groups), 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

The API reads its OIDC configuration from environment variables with the AS_API_OIDC_ prefix. Set these on the API deployment and restart.

Register an application in your IdP

Create an OIDC application with authorization_code grant. Set the redirect URI to the platform's callback URL. The scopes the platform requests are openid profile email by default and can be extended for group claims.

Collect the issuer, client ID, client secret, and redirect URI

The issuer is the URL the discovery doc lives under. The platform appends /.well-known/openid-configuration to it.

Set the environment variables on the API deployment

The required variables are AS_API_OIDC_SERVER (issuer), AS_API_OIDC_CLIENT_ID, AS_API_OIDC_CLIENT_SECRET, and AS_API_OIDC_REDIRECT_URI. Optional variables include AS_API_OIDC_SCOPES, AS_API_OIDC_GROUPS_CLAIM_NAME (default groups), and AS_API_OIDC_GROUP_ROLE_MAP (default admin=admin,member=member). Set AS_API_AUTH_MODE=oidc to make OIDC the only sign-in path.

Restart the API and verify

Restart the deployment and open the sign-in page in a private window. The IdP discovery doc and JWKS are fetched lazily on first use.

Map groups to roles

Set AS_API_OIDC_GROUP_ROLE_MAP to declare which groups grant which workspace role. The expected form is a JSON object or a comma-separated list of group=role pairs. Only admin and member are accepted as roles. Groups not listed do not grant any role, and a user with no mapped group still receives member on first sign-in.

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

Update the map and restart the API to apply the 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 AS_API_OIDC_GROUPS_CLAIM_NAME matches the actual claim name, and confirm the group is listed in AS_API_OIDC_GROUP_ROLE_MAP.

Workspace, teams, and users Connections