Single Sign-On (SSO)
Single sign-on lets your team sign in to ANTS Platform with your corporate identity provider, so access follows your existing joiner and leaver processes.
SSO is configured for the whole deployment with environment variables, not in the product UI. On a deployment managed by ANTS Platform, send the details below to your ANTS Platform team. On a self-hosted deployment, your operator sets them. Every organization on the deployment uses the same sign-in options.
Supported identity providers
ANTS Platform supports OAuth 2.0 and OpenID Connect (OIDC). SAML is not supported; if your identity provider only speaks SAML, use an OIDC application or broker in front of it.
| Provider | Required settings |
|---|---|
| Okta | AUTH_OKTA_CLIENT_ID, AUTH_OKTA_CLIENT_SECRET, AUTH_OKTA_ISSUER |
| Microsoft Entra ID (Azure AD) | AUTH_AZURE_AD_CLIENT_ID, AUTH_AZURE_AD_CLIENT_SECRET, AUTH_AZURE_AD_TENANT_ID |
AUTH_GOOGLE_CLIENT_ID, AUTH_GOOGLE_CLIENT_SECRET. Optional AUTH_GOOGLE_ALLOWED_DOMAINS limits sign-in to your Google Workspace domains. | |
| GitHub | AUTH_GITHUB_CLIENT_ID, AUTH_GITHUB_CLIENT_SECRET |
| GitHub Enterprise | AUTH_GITHUB_ENTERPRISE_CLIENT_ID, AUTH_GITHUB_ENTERPRISE_CLIENT_SECRET, AUTH_GITHUB_ENTERPRISE_BASE_URL |
| GitLab | AUTH_GITLAB_CLIENT_ID, AUTH_GITLAB_CLIENT_SECRET. Optional AUTH_GITLAB_URL and AUTH_GITLAB_ISSUER for self-managed GitLab. |
| Auth0 | AUTH_AUTH0_CLIENT_ID, AUTH_AUTH0_CLIENT_SECRET, AUTH_AUTH0_ISSUER |
| Amazon Cognito | AUTH_COGNITO_CLIENT_ID, AUTH_COGNITO_CLIENT_SECRET, AUTH_COGNITO_ISSUER |
| Keycloak | AUTH_KEYCLOAK_CLIENT_ID, AUTH_KEYCLOAK_CLIENT_SECRET, AUTH_KEYCLOAK_ISSUER |
| WorkOS | AUTH_WORKOS_CLIENT_ID, AUTH_WORKOS_CLIENT_SECRET. Optional AUTH_WORKOS_ORGANIZATION_ID or AUTH_WORKOS_CONNECTION_ID. |
| Any OIDC provider | AUTH_CUSTOM_CLIENT_ID, AUTH_CUSTOM_CLIENT_SECRET, AUTH_CUSTOM_ISSUER, AUTH_CUSTOM_NAME (the button label). Optional AUTH_CUSTOM_SCOPE (default openid email profile). The issuer must publish /.well-known/openid-configuration. |
A sign-in button appears for each provider whose required settings are present. Every provider also accepts AUTH_<PROVIDER>_ALLOW_ACCOUNT_LINKING, AUTH_<PROVIDER>_CLIENT_AUTH_METHOD and AUTH_<PROVIDER>_CHECKS.
Set up SSO
Register an application
In your identity provider, create an OIDC (or OAuth) web application for ANTS Platform. Set the redirect URI to https://<your-host>/api/auth/callback/<provider>, for example .../api/auth/callback/okta or .../api/auth/callback/azure-ad. Note the client ID, client secret and issuer URL.
Configure the deployment
Set the provider's variables from the table above, plus any of the sign-in controls below.
Test with a pilot user
Assign one user to the application and sign in with the new button. Check that they land in the right organization with the role you expect.
Roll out
Assign the rest of your users. Add SCIM provisioning if you want your identity provider to manage organization membership.
Sign-in controls
| Setting | Effect |
|---|---|
AUTH_DOMAINS_WITH_SSO_ENFORCEMENT | Comma-separated email domains. People with these domains cannot sign in, sign up or reset a password with email and password. They see "Sign in with email and password is disabled for this domain. Please use SSO." |
AUTH_DISABLE_USERNAME_PASSWORD=true | Hides the email and password form and blocks password sign-in, sign-up and reset for everyone. |
AUTH_DISABLE_SIGNUP=true | Invite only. No one can create an account, through SSO or a password, unless they have a pending invitation. They see "Sign up is disabled. Ask an organization administrator to invite you." |
AUTH_<PROVIDER>_ALLOW_ACCOUNT_LINKING=true | Lets an SSO sign-in attach to an existing account with the same email address, for example a user created by SCIM or by email invitation. Without it, that sign-in fails. |
What happens at first sign-in
- The first SSO sign-in creates the user account, unless sign-up is disabled and there is no invitation.
- Every pending invitation for the email address is accepted, with the roles in the invitation.
- If the deployment has a default organization and project, the user joins them with the default role, End User unless configured otherwise. See Members & Roles.
- No organization is created automatically. Roles come from group role mappings when the user's groups match one, and otherwise are assigned in the product or set with SCIM.
- Users who first sign in with Google or GitHub are offered an optional Add a password? step. Users of a company identity provider such as Okta or Entra ID cannot set a local password; their account shows Managed by your identity provider.
Group role mappings
Group role mappings assign roles from identity provider group membership, so access in ANTS Platform follows the groups you already manage. For example, the Okta group AI-Security can map to Security & Compliance, and Finance-Analysts to Cost Analyst. A mapping can point to a built-in role or a custom role, at organization scope or for one project, so you can grant custom least-privilege roles from Okta.
Mappings are applied:
- At every SSO sign-in, from the
groupsclaim in the sign-in token. - On every SCIM group change, when your identity provider pushes groups and their members.
Someone added to AI-Security in Okta therefore becomes Security & Compliance in ANTS Platform at their next sign-in, or straight away when Okta pushes the group, without anyone editing roles in ANTS Platform.
Send groups in the sign-in token
ANTS Platform requests the groups scope from Okta. In the Okta app for ANTS Platform, add a groups claim to the ID token and set its filter to the groups you want to map, for example names that start with AI-. Other OIDC providers, such as Microsoft Entra ID, must also include a groups claim in the token. Mappings match the values exactly as the provider sends them.
Create mappings
Open the mappings
Go to Organization Settings → Group Role Mappings and select Add mapping.
Choose the group and the role
Enter the group name as it appears in the groups claim and as the SCIM group's displayName. Choose the Scope (the organization, or one project) and the Role (a built-in role or a custom role).
Preview and save
The preview lists the members the mapping would change and the role each would get. Check it, then save. Step-up verification is required.
How mappings are applied
- Priority. Mappings are listed in priority order. When a member's groups match more than one mapping for the same scope, the mapping highest in the list wins. Drag mappings to reorder them.
- Organization and project scope. An organization-scope mapping sets the organization role. A project-scope mapping sets the project role in that project, which replaces the organization role there, as described in Members & Roles.
- Mapped roles stay in step. A role set by a mapping is replaced at the next sign-in or SCIM group change if the member's groups change. When none of their groups match any more, that role becomes None. A change made by hand to a mapped role is replaced the same way.
- Unmapped members are not touched. Members whose groups match no mapping keep the roles assigned in the product.
- The last Owner is protected. A mapping never removes or demotes the last Owner of an organization.
Managing mappings needs the Owner role. Project-scope mappings need the rbac-project-roles entitlement and mappings to custom roles need the rbac-custom-roles entitlement. Creating, changing and deleting mappings, and every role a mapping applies, are recorded in Audit Logs.
Multi-factor authentication
SSO sign-ins are not asked for an ANTS Platform sign-in code. Enforce MFA in your identity provider. The emailed Two-step sign-in code applies to email and password sign-in only. See Authentication & Security.
Next steps
- SCIM Provisioning: create and remove members and push groups from your identity provider.
- Authentication & Security: sessions, MFA and step-up verification.
- Audit Logs: sign-in and sign-out events.