Single sign-on and identity

Connect your identity provider so users sign in with their existing credentials, then use its groups to assign roles in your workspace, teams, and projects. Identity provider group management is available from version 3.2.3.

Audience: IT (the enabler) and risk and compliance

The platform supports OpenID Connect (OIDC). Register the sign-in connection at deployment time, then configure Scopes, Groups claim, and group role assignments in Users → Sign-in (/users?tab=sign-in). Adding a provider or changing its server, client ID, or client secret still requires a deployment change. Credentials for integrations such as SharePoint and Gmail are separate; see How connections get set up.

Configure OIDC

For an existing working SSO connection, continue to Configure groups in the UI. For a new self-hosted deployment:

Register the application in your IdP

Follow Identity providers (OIDC) to register the callback URLs and obtain the discovery URL, client ID, and client secret.

Configure the connection in your deployment

Set the connection under api.config.auth.oidc in your Helm values:

api:
  config:
    auth:
      oidc:
        server: https://your-idp.example.com
        clientId: REPLACE_ME
        clientSecret: REPLACE_ME
        tokenEndpointAuthMethod: client_secret_post

Set tokenEndpointAuthMethod to the method registered for your IdP application. client_secret_post sends the client secret in the request body; client_secret_basic sends it in an HTTP Basic Authorization header.

Configure scopes, the groups claim name, and group role assignments in Users → Sign-in after deployment. A new connection starts with scopes openid profile email and the claim name groups. UI changes persist across restarts.

Deploy and verify sign-in

Apply your deployment configuration and sign in as an administrator. Confirm that your user appears in Users → People with the expected email and role.

Before changing group access

Keep a record of the working scopes and claim name, and ensure your deployment operator can restore them without signing in to the application. Keep your administrator session open and use a separate test account in a private browser window to verify changes.

On a self-hosted deployment with locally managed roles, keep at least one workspace Admin assigned manually through Users → People → Change role, independent of group membership. Confirm that this person's admin access does not come only from a group. A manually assigned role survives group changes, but the person still needs working SSO to sign in.

A shared provider's scopes and claim name affect sign-ins in every workspace on the deployment. If the deployment configures an instance administrator group, changing these fields requires both workspace admin and instance administrator access. Changing the claim name ends existing sessions' instance administrator access until they sign in again with the new claim, including the session making the change. Keep the deployment recovery procedure available before saving.

Configure groups in the UI

Configure your IdP to send groups

Configure the IdP application to include the user's groups in the ID token as a list of strings. Record the exact claim name and any scopes your provider requires to include it. For example:

{
  "groups": ["platform-admins", "finance-builders"]
}

Use the identifiers the token actually contains when assigning roles. For Microsoft Entra ID, use group Object IDs, not display names, and limit the groups emitted for the application to avoid group overage. See Microsoft's group claim configuration (opens in a new tab). The platform does not expand overage pointers through Microsoft Graph.

For Okta, configure the groups claim and the scopes required by your authorization server; the usual groups scope is groups. See Okta's groups claim guide (opens in a new tab). Okta group names must match the token; if you rename a group, recreate its role assignments using the new name.

Set scopes and the claim name

Under Identity providers, find the provider marked Signs people in and select Details → Change scopes and groups claim.

Scopes: enter a space-separated list, including openid and the scopes required by your IdP. Keep profile email for profile information; for a provider configured to use a groups scope, enter openid profile email groups.
Groups claim: enter the exact ID-token claim name, such as groups or your provider's custom claim name.

Select Save. These settings apply at the next sign-in; no application restart is needed.

If a field says Set in the environment, so it can't be changed here, ask your deployment operator to remove the corresponding deployment override and roll out the change. Removing an override preserves the current value and makes it editable here. This also applies to installations upgraded from versions that configured the claim name at deployment time.

Verify what the provider sends

Have your test user sign in again. In Users → People, open the groups indicator on their row to view Groups at last sign-in. Check the received group identifiers and Claims in this sign-in against the claim name you configured. This view reflects the last sign-in, not a live directory lookup.

Map groups to roles

In Users → Sign-in, confirm that Roles from groups is On. This is the default and uses additive access: group roles combine with existing manual roles, and the highest applicable role wins.

Select Add group on the identity provider's card.
Choose a previously received group or type its exact identifier in Group. You can add a group before anyone in it has signed in.
Optionally set Name shown here to a readable label; this does not change the identifier used for matching.
Under Where the role applies, choose Whole organization (the workspace), Team, or Project. Select the target team or project when applicable.
Choose Admin, Builder, or Member, then add the group.
Have a group member sign in again and verify their role and access to the intended workspace, team, or project.

A project assignment also gives the person Member access to the project's team. Groups without an assignment grant no additional access. Group mapping does not restrict who can authenticate; control application sign-in eligibility in your IdP.

When access changes

Change	When it takes effect
Add a group role assignment, or change a person's membership in the IdP	At that person's next sign-in
Change an existing assignment's role	Immediately for people already holding that assignment
Remove an assignment	Immediately removes the roles it granted
Turn Roles from groups off	Immediately removes all group-derived roles in the workspace, including team and project roles
Turn Roles from groups on again	Existing assignments apply at each person's next sign-in

Manual roles remain in place. Lowering a person's manual role does not remove a higher role granted by a group. Open a group row on the Sign-in tab to change its role or display name, or remove it. To change the group identifier or target, remove the assignment and add a new one.

Turning group roles off preserves the assignments for later use and is refused if it would leave no active workspace admin. However, removing an assignment or losing a group at sign-in can remove the last group-derived admin role. Keep independent admin access before making those changes.

If you previously used the deployment's groupRoleMap, manage the resulting assignments here. That setting only seeds assignments once per workspace and provider; changing it does not repair or update assignments already initialized.

Recover from a broken configuration

An administrator can still use the UI

Restore the working Scopes and Groups claim in Users → Sign-in → Details, then test a fresh sign-in in a private window. If group assignments are the problem, correct them on the Sign-in tab. You can temporarily turn Roles from groups off if an independent admin will remain; review the dialog's impact on other users before confirming. Turning this off removes group-derived access immediately and does not fix a bad OIDC scope or connection.

Recover through values.yaml when sign-in is blocked

If incorrect scopes or a groups claim name prevent sign-in, temporarily set known-good values in your deployment's values.yaml:

api:
  config:
    auth:
      oidc:
        scopes: "openid profile email groups"
        groupsClaimName: "groups"

Replace these example values with those required by your IdP. The scopes must include openid.

Upgrade your existing Helm release with the updated values.
Test a fresh sign-in and confirm the administrator's groups and access.
Once access is restored, remove the temporary scopes and groupsClaimName entries and deploy again without retaining those overrides. The restored settings stay saved and can be managed in Users → Sign-in → Details again.

For Replicated, use OIDC Scopes and OIDC Groups Claim Name for the same recovery, then clear them once access is restored. If you cannot change the deployment or still cannot regain admin access, contact your deployment operator or Sema4.ai support.

Common errors

A user signs in without the expected role. Check Groups at last sign-in, the provider's Groups claim, the exact group identifier in the assignment, its target, and whether Roles from groups is on. Have the user sign in again after correcting the configuration.
A missing or empty groups claim. With group roles on, the user's next sign-in removes roles previously granted by that provider's groups; manual roles remain. Check the IdP's claim configuration and requested scopes before testing with an administrator who depends on groups.
Malformed groups or Entra group overage. When group mapping is configured, sign-in is rejected without changing existing group roles. Send a list of strings in the ID token and reduce the groups emitted for the application.
Scopes or claim name cannot be edited. Read the explanation in Details: a deployment override makes the field read-only, and a shared provider may require instance administrator access.
AADSTS900023 on Microsoft Entra ID. Use the tenant GUID, common, organizations, or consumers in the issuer URL, not SingleTenant or MultiTenant.
Discovery document unreachable. Confirm outbound HTTPS from the deployment network to the IdP's discovery URL.
Sign-in fails just after the IdP redirects back. Check that the configured scopes are valid and that tokenEndpointAuthMethod matches the method registered for the IdP application. On a self-hosted deployment, open https://<YOUR_HOSTNAME>/diag and enter your Replicated license ID to inspect the identity provider check and advertised authentication methods.

Workspace, teams, and users Connections