Configure single sign-on

Identity is one of the few areas where the cost of doing it badly compounds over time. A platform that uses its own local username-and-password database starts simple but ends up with everything an identity team usually wants to avoid: passwords sprinkled across forgotten accounts, no central offboarding signal when an employee leaves, no MFA enforcement, no audit trail tied to the corporate directory, and a separate account-management surface for every operator to remember. Single sign-on (SSO) eliminates that class of problems by delegating authentication to the corporate identity provider: the same one that already handles email, the VPN, the source-control system, and every other internal application.

---

The Admin Dashboard's SSO surface supports both SAML 2.0 and OIDC, which together cover essentially every modern identity provider in the enterprise space. SAML is the older, XML-based federation standard and is still the dominant choice for SaaS-to-IdP integrations in large organisations. OIDC is the OAuth 2.0-based equivalent, slightly simpler to configure and more common in newer deployments. Both have the same goal in this guide: users authenticate at the identity provider, the platform receives a verified assertion of their identity, and the local user record is provisioned automatically on first sign-in. This guide covers configuration, testing, enablement, and the recurring operational concerns that follow, including the SSO-driven role mapping that turns directory groups and app roles into Agent Router roles automatically.

Persona: Platform operator working in the Admin Dashboard, often in coordination with the identity team that owns the upstream provider.

Estimated time: 30--60 minutes for an initial configuration, depending on how quickly metadata can be exchanged with the identity provider.

When this guide applies

This guide is the right starting point in any of these situations:

Situation	What it covers
First-time SSO setup on a new deployment	Protocol choice, configuration, testing, and enablement
Migrating from local accounts to corporate SSO	The configuration and enablement flow, plus the considerations for in-flight users
Switching identity providers	Editing the existing configuration and re-testing before re-enabling
Rotating IdP credentials (client secret, signing certificate)	Updating the relevant fields without disrupting active sessions where possible
Investigating an SSO failure	The testing surface and the audit log are the right starting points

For the related work of mapping IdP claims to Agent Router roles, the most common follow-up to enabling SSO, see the SSO role mapping guide. The two guides are designed to be read together for any deployment that uses claim-driven role assignment.

Outcomes

By the end of this guide:

• A protocol has been chosen (SAML or OIDC) and configured against the corporate identity provider.
• The Test Connection flow has succeeded, exercising the full sign-in path before enablement.
• SSO is enabled, and all subsequent user sign-ins are routed through the identity provider.
• An out-of-band administrator account is in place so that an IdP outage does not lock the platform down entirely.
• The relationship between this configuration and the SSO role mapping mechanism is clear.

Prerequisites

• Administrator access to the Admin Dashboard, typically the super_admin role.
• Cooperation from whoever owns the corporate identity provider. Most of the values required by the configuration come from that provider, and the SP metadata produced by the platform has to be registered on the provider side.
• For SAML: the IdP's Entity ID, SSO URL, and the X.509 signing certificate.
• For OIDC: the issuer URL, a client ID, and a client secret registered on the IdP for the platform.
• An out-of-band administrator account, typically the local administrator account used during initial installation, that can sign in without SSO. This is the break-glass account for the case where the IdP itself becomes unreachable.

Step 1: choose the protocol

SAML and OIDC are not equivalent in practice, even though they do the same job. The right choice is usually dictated by what the identity provider supports best and by what the rest of the organisation already uses.

Protocol	Strengths	Common providers
SAML 2.0	Mature, widely deployed in enterprise environments, strong claim-mapping options	Okta, Azure AD, OneLogin, PingFederate, ADFS
OIDC	Simpler configuration, better support for modern web flows, JSON instead of XML	Okta, Azure AD, Google Workspace, Auth0, Keycloak

Most identity providers support both. Where the organisation already has a default (a tenant policy that requires OIDC, or an established SAML integration template for SaaS applications) following that default is almost always the lower-friction path.

The SSO role mapping mechanism documented separately is built on OIDC claims. If claim-driven role assignment is part of the rollout plan, OIDC is the right choice; SAML deployments use the same role-mapping concepts but route through the SAML assertion mechanism instead.

Step 2: configure SAML

For deployments that have chosen SAML, the configuration is a structured value exchange between the platform (acting as the Service Provider) and the IdP.

1. Sign in to the Admin Dashboard.

2. Open Settings → SSO from the sidebar.

3. Select SAML as the protocol.

4. Enter the IdP-provided values:

   Field	What it carries
   Entity ID	The unique identifier for the IdP, often a URL such as https://idp.example.com/metadata
   SSO URL	The IdP's single sign-on endpoint where users are redirected to authenticate
   Certificate	The X.509 certificate used to verify SAML assertions, pasted as PEM-encoded text

5. Click Save.

6. Copy the SP Metadata displayed on the page.

7. Provide the SP Metadata to the IdP administrator so that the trust relationship can be established on the IdP side. This step is typically a one-time configuration in the IdP's management surface.

The platform is now configured to expect SAML assertions from the IdP, and the IdP is configured to send them. The next step is the test connection flow that confirms the configuration is correct end-to-end.

Step 3: configure OIDC

For deployments that have chosen OIDC, the configuration is a smaller and faster exchange.

1. Open Settings → SSO from the sidebar.

2. Select OIDC as the protocol.

3. Enter the IdP-provided values:

   Field	What it carries
   Issuer URL	The OIDC issuer identifier, often the IdP's base URL: https://accounts.google.com, https://your-org.okta.com, or similar
   Client ID	The client identifier issued by the IdP when the platform was registered as an application
   Client Secret	The client secret issued by the IdP, stored encrypted at rest in the platform

4. Click Save.

The platform automatically discovers the remaining endpoints (authorization, token, userinfo, JWKS) by reading the IdP's well-known OIDC discovery document at <Issuer URL>/.well-known/openid-configuration. No further URLs need to be entered manually unless the IdP omits the discovery document, in which case it has to provide them out of band.

Worked example: Okta

Okta is one of the most common identity providers (IdPs) encountered on this surface, and it supports both protocols, so it serves as a concrete illustration of where the generic fields above come from. Whichever protocol is chosen, the work on the Okta side is the creation of an application that represents the platform; the platform then consumes the values that application exposes. The application is created and owned by the identity team that administers the Okta org, and the protocol-level fields below are the only values the platform requires.

Okta as an OIDC identity provider

For an OIDC deployment, the identity team registers the platform as an OIDC application in Okta and supplies the three values the OIDC form in Step 3 expects:

Field	Where it comes from in Okta
Issuer URL	The issuer of the Okta authorization server, typically the org URL such as https://your-org.okta.com or, for a custom authorization server, a path beneath it. The platform reads this org's discovery document to find the remaining endpoints.
Client ID	The client identifier Okta issues when the platform is registered as an OIDC application.
Client Secret	The client secret Okta issues for that same application, stored encrypted at rest in the platform.

The redirect URI that the platform expects, the same one referenced in Step 4 when a test fails on a missing registration, has to be registered on the Okta application, so that Okta accepts the redirect back to the platform after authentication.

Okta as a SAML identity provider

For a SAML deployment, the identity team creates a SAML app integration in Okta and supplies the three values the SAML form in Step 2 expects:

Field	Where it comes from in Okta
Entity ID	The unique identifier for the Okta IdP, often expressed as a URL.
SSO URL	The single sign-on endpoint of the Okta app integration, where users are redirected to authenticate.
Certificate	The X.509 signing certificate Okta provides for the app integration, pasted as PEM-encoded text and used to verify SAML assertions.

As with any SAML deployment, the SP metadata the platform generates after Save is handed back to the identity team and registered on the Okta app integration, so that the trust relationship exists on both sides.

Okta group claims and role mapping

Okta can emit a group claim in the assertion or token, exactly as Microsoft Entra ID can. When it does, those Okta groups feed the same group-to-business-function mapping that drives role assignment, rate limits, and budgets. The platform does not distinguish between the two providers at the mapping layer; it reads the group values it receives and matches them against the configured rules. The end-to-end treatment of that mapping, written against Entra ID but applicable to Okta groups in the same way, is in Map Entra ID groups to business functions. The protocol-level claim mechanics, the same OIDC-claim and SAML-assertion paths described in the SSO role mapping guide, apply to Okta unchanged.

Step 4: test the connection before enabling

Misconfigured SSO is one of the most reliable ways to lock everyone, including the operator currently making the change, out of the platform. The Test Connection button exists specifically to prevent that.

1. After saving either SAML or OIDC configuration, click Test Connection.
2. A new browser window opens and redirects to the IdP's sign-in page.
3. Authenticate with corporate credentials.
4. On success, the window redirects back to the platform and a success message is displayed.

If the test fails, the platform surfaces the error from the IdP. Common causes:

• For SAML: a mismatch between the SP metadata registered on the IdP and what the platform expects.
• For OIDC: an incorrect client secret, a typo in the issuer URL, or a missing redirect URI registration on the IdP.
• For both: the IdP not yet trusting the platform's identifier, often because the configuration on the IdP side has not been saved.

Resolve every failure here before continuing. Enabling SSO that has not passed the test risks locking users out.

Step 5: enable SSO

Enablement is the moment at which all sign-in attempts start being routed through the identity provider. After this, users no longer use platform-managed credentials.

1. With a successful Test Connection confirmed, toggle the Enable SSO switch to ON.
2. Confirm when prompted.

Every subsequent sign-in attempt is redirected to the IdP, the user authenticates there, and the platform receives the assertion or token, provisions a local user record on first sign-in if one does not exist, and proceeds with the authenticated session. On first-time provisioning, the user's name and email are populated from the IdP assertion or token claims. The email/password sign-in path is either disabled outright or reduced to a fallback role, depending on the deployment configuration.

important

Keep at least one local administrator account that can sign in without SSO. If the identity provider becomes unreachable, an outage in the IdP becomes a platform outage, unless there is a way to recover access without the IdP. The break-glass account is the contingency for that case.

Step 6: manage the SSO configuration over time

SSO is not a write-once configuration. Client secrets rotate, certificates expire, IdP migrations happen, and identity-team policy changes ripple into the platform. The same surface handles all of these recurring tasks.

Edit the existing configuration

1. Open Settings → SSO.
2. Update the fields that need to change. Common edits include a new client secret on OIDC after a scheduled rotation, or a new signing certificate on SAML when the IdP rotates theirs.
3. Re-run the Test Connection flow. The configuration may save successfully but fail to authenticate against the new values; the test surfaces this immediately rather than at the next user sign-in.
4. Save and continue.

Disable SSO

If SSO needs to be disabled (for an emergency, a migration window, or any other reason):

1. Toggle the Enable SSO switch to OFF.
2. Confirm.

Users revert to platform-managed email/password authentication. The SSO configuration is preserved, so re-enablement does not require re-entering values; only the toggle has to be flipped back to ON.

Switch identity providers

Switching identity providers is the most disruptive operation on this surface. The pattern that works best:

1. Configure the new IdP in a separate test environment if one exists, and run Test Connection there first.
2. In production, edit the existing configuration to point at the new IdP. The configuration itself supports replacement rather than coexistence; there is no parallel-run mode where both old and new IdPs are accepted.
3. Coordinate the cutover with the identity team so that the platform-side change and the IdP-side change happen close together.
4. Communicate the change through an announcement at least one business day in advance for any deployment with non-trivial user counts.

How SSO interacts with role mapping

SSO authentication answers the question who is signing in. SSO role mapping answers a separate question: what role should the platform assign to that user. The two are configured together but conceptually independent.

In a deployment without role mapping, every SSO user lands with the default user role, and operators manually assign elevated roles in Users. This is fine for small deployments but does not scale and creates a synchronisation problem: a directory change has no effect on the platform's role assignment until someone notices.

In a deployment with role mapping, the IdP's claims (group memberships in SAML, app roles or groups in OIDC) are translated into Agent Router roles on every login. The directory becomes the source of truth for who is what, and platform-side role assignment becomes redundant. The complete walkthrough of this setup is in the SSO role mapping guide, and it is the right next read after this one.

How SSO interacts with the audit log

Every change on the SSO surface generates an entry in Audit Logs:

Event	When it appears
sso.configured	A protocol is configured for the first time, or the configuration is materially changed
sso.enabled	The Enable SSO toggle is switched ON
sso.disabled	The Enable SSO toggle is switched OFF

These events are the recovery trail when SSO behaviour starts surprising people. A sudden "all SSO sign-ins are failing" is almost always preceded by either a recent sso.configured event (a configuration change has just happened) or by an IdP-side change that no audit log on the platform can capture. The Admin-side log narrows the search dramatically.

Field reference

The SSO surface in the Admin Dashboard (Settings → SSO) exposes a single protocol selector backed by two configuration forms and a set of lifecycle controls.

Supported protocols

Protocol	Description	Common identity providers
SAML 2.0	XML-based federation standard	Okta, Azure AD, OneLogin, PingFederate, ADFS
OIDC	OAuth 2.0-based identity layer	Okta, Azure AD, Google Workspace, Auth0, Keycloak

Controls

Control	Effect
Protocol selector (SAML / OIDC)	Chooses which configuration form is shown; only one protocol is active at a time
Save	Stores the entered configuration for the selected protocol
SP Metadata	Read-only Service Provider metadata generated for SAML, copied and handed to the IdP administrator for trust configuration
Test Connection	Runs the full sign-in flow against the IdP and reports success or the surfaced error, without enabling SSO
Enable SSO toggle	Switches enforcement ON or OFF; ON routes all sign-ins through the IdP, OFF reverts to email/password while preserving the saved configuration
Edit	Re-opens the saved fields for changes such as a rotated client secret or signing certificate, followed by a re-test
Switch provider	Replaces the existing configuration with a new IdP; the surface supports replacement rather than parallel operation

What to do next

• Audit platform activity: the audit log generated by SSO setup is part of the operator-facing observability surface. See Audit Platform Activity.
• SSO role mapping: map IdP claims to Agent Router roles so directory changes propagate without manual intervention. See the SSO role mapping guide.
• Run multiple platform instances: SSO is configured per instance; the multi-instance considerations are non-trivial. See Run Multiple Platform Instances.

---

Where to go next

Map Entra ID groups to business functions

Translate IdP group claims into roles, rate limits, and budgets.

Audit platform activity

The audit log generated by SSO setup is part of the operator observability surface.