Platform SSO
Configure single sign-on (SSO) for platform administrators. Platform SSO is separate from any organization-level SSO and is used only to authenticate users who hold platform roles (Platform Admin, Platform Support, Platform Billing).
Overview
The Platform SSO page lets you:
- Add OAuth / OpenID Connect identity providers for platform sign-in.
- Choose from four provider types: Microsoft Entra ID, Google Workspace, Authentik, and a generic OIDC provider.
- Store the provider's client ID and client secret (the secret is encrypted before storage).
- Copy the callback (redirect) URL to paste into your identity provider's configuration.
- Enable or disable each provider without deleting it.
- Edit or remove existing providers.
- Optionally disable password authentication so platform admins can sign in only through SSO.
Open the SSO configuration page
This page lives in the Platform Admin area (the /platform/* shell, separate from the org app). It is not a top-level sidebar item — open it from the Platform Users page by clicking Configure SSO in the top-right actions. The page is restricted to users with the Platform Admin role; everyone else sees an Access Denied message.
Authentication Settings
A Password Authentication toggle controls whether platform administrators may sign in with a password.
- When enabled (the default), platform admins can use either a password or an enabled SSO provider.
- When disabled, platform admins can sign in only via SSO.
- You cannot disable password authentication until at least one SSO provider is added and enabled. The toggle is locked until that condition is met.
Provider types
| Provider type | Label | Description |
|---|---|---|
MICROSOFT | Microsoft Entra ID | Azure AD / Microsoft 365 |
GOOGLE | Google Workspace | Google OAuth 2.0 |
AUTHENTIK | Authentik | Self-hosted identity provider |
OIDC | Generic OIDC | OpenID Connect compatible provider |
Only one provider of each type can be configured for the platform. Attempting to add a second provider of a type that already exists returns an error.
Provider fields
| Field | Applies to | Notes |
|---|---|---|
| Provider Type | All (set at creation only) | Cannot be changed after the provider is created. |
| Display Name (optional) | All | Custom text shown on the login button. |
| Client ID | All | The OAuth client ID from your identity provider. Required. |
| Client Secret | All | The OAuth client secret. Required when creating; leave blank when editing to keep the existing secret. The secret is encrypted before being stored. |
| Tenant ID | Microsoft Entra ID only | The Azure AD tenant ID or domain. Leave blank for multi-tenant or use common. |
| Issuer URL | Generic OIDC and Authentik only | The OIDC issuer URL. Must support .well-known/openid-configuration. |
| Enable Provider | All | Toggles whether users can sign in with this provider. |
Callback URL
The create/edit dialog shows a Callback URL (Redirect URI) at the top with a copy button. Paste this URL into your identity provider's app registration as an allowed redirect URI. The callback URL is specific to the selected provider type — it takes the form <your-deployment-host>/api/auth/platform/<provider>/callback (for example, .../api/auth/platform/microsoft/callback). Because the host is derived from your deployment, always copy the value shown in the dialog rather than typing it by hand.
Add an SSO provider
- Click Add Provider (top right) or Add SSO Provider from the empty state.
- Copy the Callback URL shown at the top of the dialog and register it as a redirect URI in your identity provider.
- Choose the Provider Type.
- Optionally set a Display Name for the login button.
- Enter the Client ID and Client Secret from your identity provider.
- For Microsoft Entra ID, enter the Tenant ID (or leave blank / use
common). For Generic OIDC or Authentik, enter the Issuer URL. - Leave Enable Provider on to make it available immediately, or turn it off to add it without enabling sign-in.
- Click Add Provider.
Edit or delete a provider
The SSO Providers table lists each configured provider with its display name and description, a truncated Client ID, an Enabled or Disabled status badge, and the Created date.
- To edit, click the pencil icon. You can update the client ID, secret, tenant ID, issuer URL, display name, and enabled state. The provider type itself cannot be changed. Leave the Client Secret field blank to keep the current secret.
- To delete, click the trash icon and confirm in the Delete SSO Provider? dialog. Users will no longer be able to sign in using that provider, and the action cannot be undone.
How platform SSO sign-in works
When a platform admin signs in through an SSO provider, Ascent requests the openid, profile, and email scopes and matches the returned email address against an existing platform user.
- SSO is only available for existing platform users — it does not create new accounts. Platform users are provisioned separately (manually on the Platform Users page or pushed via SCIM). If no matching platform user exists, sign-in fails.
- The matched user must be active and have a platform role; deactivated accounts or users without platform-level access are denied.
- If the platform user has MFA enabled, they are prompted to complete it after the SSO step.
Tips
- Add and enable at least one SSO provider before turning off Password Authentication, so you don't lock yourself out.
- Use the Display Name to make the login button clearer for your team (for example, "Corporate SSO").
- Keep the Callback URL in your identity provider in sync with the value shown in the dialog if your deployment URL changes.