Single Sign-On (SSO)

Overview

This guide walks you through the Single Sign-On screen in Shift-Left API, from enabling SSO to testing a connection. An SSO connection describes an OIDC or SAML identity provider (Microsoft Entra ID through its preset, Okta, or any standards-compliant IdP): the role a new user receives, the email domains allowed to use it, and how IdP groups map to platform roles.

Current status: SSO configuration is available. Completing a sign-in from the identity provider back into the web app is still being finished, and the login page does not yet show a "Sign in with SSO" button. Use Test login (Step 6) to check the identity-provider side of a connection, and contact support to confirm the end-to-end sign-in on your installation before you roll SSO out to your users.

Explore the capability at single sign-on.

Availability: Trial and Enterprise.

Before you begin

• You must be an administrator with the manage_sso permission. The connection-management endpoints require it; without it the screen won't load.
• Have your IdP details ready: for OIDC, the Issuer URL, Client ID, and Client secret; for SAML, the Entry point (IdP SSO URL) and the IdP certificate (PEM).
• Navigate to Settings → Access & Identity → Single Sign-On.
• Secrets (Client secret, SP private key) are encrypted and shown only once — after you save, the field is replaced with a configured badge. Copy secrets into your IdP/records before saving.

Step 1 — Enable Single Sign-On

1. On the Single Sign-On screen you'll see the subtitle "Configure OIDC and SAML identity providers for your team."
2. Find the Enable Single Sign-On card. When SSO is off, the helper text reads "Turn on to configure OIDC / SAML identity providers for your team."
3. Click the toggle switch on the right of that card. It flips to the active (blue) state and shows the notification "Single Sign-On enabled." The helper text changes to "SSO is active. Add and manage identity providers below."
4. If SSO is disabled you'll see a placeholder card: "Single Sign-On is currently disabled. Use the switch above to enable it, then add an OIDC or SAML connection." The Add Connection button only appears once SSO is enabled.

Step 2 — Add a connection and fill the basics

1. Click Add Connection (top right). The form header reads New Connection.
2. Optionally click Entra / Azure AD preset (top right of the form) to pre-fill common OIDC values — it sets the protocol to OIDC, seeds the display name Entra ID (Azure AD), the Issuer URL template https://login.microsoftonline.com/<tenant>/v2.0, and Groups claim groups.
3. Fill the basics grid:

Step 3a — OIDC configuration

If Protocol is OIDC, the OIDC configuration block appears:

Step 3b — SAML configuration

If Protocol is SAML 2.0, the SAML configuration block appears:

Step 4 — Add group mappings (optional)

Group mappings translate an IdP group into an app role. Under Group mappings, click Add mapping to add a row (the empty state reads "No group mappings. Users get the default role above."). Each row has:

Use the trash icon to remove a mapping row.

Step 5 — Create the connection

1. Click Create Connection at the bottom of the form (the button reads Save Changes when editing an existing connection). While saving it shows Saving….
2. On success you'll see "SSO connection created" (or "SSO connection updated") and the form closes.
3. The new connection appears in the list showing its display name, a protocol badge (OIDC/SAML), an Enabled/Disabled badge, and the line "Default role: … · Mapping: …".

Step 6 — Test login

1. In the connection's list row, click the Test login link — it points at /api/sso/<connectionId>/login and opens in a new tab.
2. You are redirected to your IdP to sign in. This checks the IdP side of the connection: issuer, client, certificate, allowed domains and the groups the IdP sends. The hand-off back into the web app is not complete yet (see Current status above).
3. Manage a connection from its row: Disable/Enable (toggles the connection), the pencil icon (Edit connection), and the trash icon (Delete connection). Deleting prompts "Delete SSO connection "…"? This cannot be undone."

Troubleshooting and notes

• DOMAIN_NOT_ALLOWED (403) — the signing-in user's email domain isn't in Enforced email domains. Add the domain or clear the field.
• CONNECTION_NOT_FOUND (404) — the connection is disabled or was deleted; only enabled connections accept logins.
• INVALID_STATE / STATE_MISMATCH (400) — the OIDC login state expired (10-minute limit) or was tampered with; start the login again.
• SSO_CALLBACK_FAILED / SAML_CALLBACK_FAILED (401) — the IdP response failed validation. Recheck Issuer URL/Entry point, Client ID, Client secret, and the IdP certificate.
• CONNECTION_EXISTS (409) — a connection with that identity already exists.
• Secrets (Client secret, SP private key) are never displayed again — the UI shows a configured badge. Leave a secret field blank when editing to keep the current value.
• All connection changes (create/update/delete) are written to the audit log.
• No SCIM, no automatic deprovisioning. Removing someone at your IdP does not deactivate their account in Shift-Left API, and password sign-in stays available. Deactivate leavers under User Management as well.
• OIDC validation is strict: the ID token is checked against the provider's published keys with an exact key id and a pinned algorithm list, along with audience, issuer and nonce, and the provider must report the email as verified.

Related articles

• Role Permissions
• User Management
• User Policies
• Audit Logs