Skip to main content
Single sign-on (SSO) lets an external identity provider authenticate users for a Lerian workspace. Access Manager resolves the user’s tenant, redirects the browser to the provider, and exchanges the provider’s authorization code for Lerian access tokens. SSO applies to user sign-in. Machine-to-machine applications continue to use client credentials.

​
Supported providers

Access Manager supports one active SSO provider per tenant. Configuring another provider replaces the current configuration.
This SSO contract uses OAuth 2.0 and OpenID Connect. It does not configure a SAML provider.

​
How sign-in works

  1. The Console asks for the user’s email address.
  2. Auth resolves the tenant from the email address, as described in Tenant resolution. It then returns the available sign-in method.
  3. The Console creates an S256 PKCE challenge.
  4. Auth redirects the browser to the configured identity provider.
  5. The provider authenticates the user and returns an authorization code to the Console callback URL.
  6. The Console sends the code, state, and PKCE verifier to Auth.
  7. Auth verifies the flow and the returned email identity.
  8. Auth returns Lerian access tokens or continues to MFA verification.
Auth verifies that the email returned by the provider belongs to the same tenant that started the flow. It refuses the login when the email is missing or resolves to another tenant.

​
Tenant resolution

Each tenant is a Caradhras organization. SSO uses two fields of that organization:
  • domain is the email domain of the tenant’s users, such as example.com. Auth refuses the SSO login when the user’s email domain differs from the tenant’s domain.
  • domainHome marks the one organization where people of that domain get their account when they sign in with SSO for the first time. Each domain has at most one home organization.
On Lerian Cloud, Lerian sets these fields for you. In a BYOC deployment, set them as described in SSO deployment requirements. A BYOC deployment can use one fixed organization instead, set with PLUGIN_AUTH_SSO_STATIC_ORGANIZATION. Auth then does not compare the email domain with the organization. Discovery does not reveal tenant identifiers. An unknown email receives the same general response as a tenant without SSO.

​
Password login policy

A tenant can allow or disable local password login through the Identity API. The Console does not expose a separate password-policy control. When you configure the first SSO provider in the Console, password login remains available until the first successful SSO login. Auth then disables local password login for that tenant. API integrations can set the password policy explicitly when they need a different transition:
  • Disable password login immediately after the provider is configured.
  • Keep password login available alongside SSO.
Test SSO before you disable local password login. An invalid client secret, issuer, domain, or callback URL can prevent every user from signing in.

​
Configuration validation

Run preflight validation before saving a provider. Preflight does not change the tenant configuration. It checks:
  • required fields.
  • OpenID Connect discovery when the provider uses an issuer URL.
  • explicit endpoint validation when the API supplies authorization, token, and user-info URLs.
  • client credentials.
  • the callback URL.
  • the resolved authorization, token, and user-info endpoints.
Okta cannot always confirm the callback registration through preflight. Register the callback URL in Okta before you enable the provider.

​
Next steps

Configure SSO in the Console

Test, save, review, and remove the tenant’s provider.

SSO deployment requirements

Configure callback URLs, public Auth routing, and tenant resolution.

Multi-factor authentication

Add a second verification step after SSO.