Skip to main content
This page tells a BYOC operator what to configure before an administrator enables single sign-on.
This page applies to BYOC deployments only. On Lerian Cloud, Lerian operates this configuration for you.

​
Set one callback URL

Set PLUGIN_AUTH_SSO_CALLBACK_URL on both the Auth and Identity services. Use the exact public Console callback URL:
Auth sends this URL to the identity provider. Identity includes it in the allowed redirect configuration.
Use the same absolute URL in Auth, Identity, the Console, and the identity-provider application. A scheme, host, or path mismatch makes the authorization-code exchange fail.

​
Configure Console routes

The Console needs these routes: Set PLUGIN_AUTH_PUBLIC_BASE_PATH to an HTTPS address that the user’s browser can reach. The browser follows the redirect from the SSO start operation directly. To set these variables with the Product Console chart, see the Product Console chart README. The public and server-to-server Auth URLs can point to the same address. Use an internal address for server-to-server calls and the public address for browser redirects.

​
Configure tenant resolution

Before SSO starts, Auth must know which Caradhras organization the user belongs to. Each tenant is one organization. Choose one of the two setups below. Set PLUGIN_AUTH_SSO_STATIC_ORGANIZATION in Auth to the name of the Caradhras organization your users belong to. This is normally the value of AUTHORIZER_ORGANIZATION_NAME, which defaults to lerian. Auth then uses that organization for every SSO request and does not compare the email domain with the organization. This setup needs no change to Caradhras data and works for users of any email domain.

​
Without a fixed organization

If you do not set PLUGIN_AUTH_SSO_STATIC_ORGANIZATION, SSO uses the organization fields:
  • Set domain on the organization to your users’ email domain, such as example.com. Without it, Auth refuses every SSO login.
  • Set domainHome to true if people without an account must be able to sign in with SSO for the first time. Without it, the Console offers these people password login only.
An organization holds one domain, so only users of that email domain can sign in with SSO. If your users have more than one email domain, use the fixed organization instead.

​
Set the organization fields

You can set domain and domainHome on the organization’s edit page in the Caradhras web UI, or with the Caradhras API operation POST /api/update-organization. The Console has no input for them. To use the API, send the request from a host that can reach Caradhras at the address in AUTHORIZER_ADDRESS, the address that Auth and Identity use. Authenticate with HTTP Basic and the client ID and secret that Access Manager uses for Caradhras, AUTHORIZER_CLIENT_ID and AUTHORIZER_CLIENT_SECRET. A Caradhras global administrator can also make the call. By default, a tenant administrator cannot. This example makes the acme organization the home of the example.com domain:
Keys that you leave out of the body keep their stored values. A key that you send replaces the stored value, even when it is empty or false. Send owner and name with the organization’s current values, because a different name renames the organization. Leave out domainHome for an organization that is not the home of its domain. To check the result, list the organizations of a domain:

​
Refuse users from other domains (optional)

Caradhras can also compare the email domain with the organization’s domain when it creates a user, including a first-time SSO user, and when an administrator changes a user’s email. The emailDomainPolicy setting controls this check: The check applies only to organizations that have a domain. To set it with the Access Manager chart, see the Access Manager chart README.

​
Expose Auth to the browser

The browser must reach the Auth SSO start route over HTTPS. Expose Auth at a public address and allow the Console origin according to your deployment’s cross-origin policy. Identity can remain on a server-to-server route when administrators manage it only through the Console.

​
Configure the identity provider

In the provider application:
  1. Register the exact Console callback URL.
  2. Allow the OpenID Connect scopes required to return the user’s identity and email.
  3. Issue a client ID and client secret for the tenant.
  4. Make the issuer and endpoints reachable from the Access Manager services.
For a Custom OpenID Connect provider, use an issuer that publishes valid discovery metadata. API integrations can instead supply the complete authorization, token, and user-info endpoint set.

​
Validate the deployment

1

Open the Single Sign-On tab

Make sure the Console can read the current provider state from Identity.
2

Run provider preflight

Test the candidate configuration without saving it. Fix every required failure.
3

Register the callback URL

Compare the provider registration with PLUGIN_AUTH_SSO_CALLBACK_URL character by character.
4

Save the provider

Keep password login available during the first test.
5

Test from a private browser session

Enter a tenant email, complete provider sign-in, and make sure the browser returns to the Console.
6

Test tenant isolation

Try an email that does not belong to the tenant. Make sure Auth does not complete the login or reveal tenant details.
7

Test MFA continuation

Sign in with an MFA-enabled user and make sure the Console opens the MFA verification step after SSO.

Configure SSO in the Console

Test and save the provider configuration.