Set up single sign-on

Connect your identity provider with OpenID Connect, verify your domain, and register the redirect URI.

For: Administrators (the admin ability) · Last updated

Single sign-on lets people from your company domain sign in through your own identity provider instead of a password. Workforce Intelligence supports OpenID Connect (OIDC). You configure it per email domain at Settings → Administration → Single sign-on, and you need the admin ability. Others see "Managing single sign-on requires the admin role."

Before you start#

In your identity provider, create an OIDC web application (client) for Workforce Intelligence that uses the authorization-code flow, and note its client ID and client secret. You also need the provider's issuer URL, and you need to be able to add a DNS TXT record for your domain.

The issuer must serve its OIDC discovery document at <issuer>/.well-known/openid-configuration, and the issuer value inside that document must match what you enter exactly. The issuer and the endpoints it advertises must use HTTPS and resolve to public addresses.

Add a domain#

  1. Open Single sign-on and select + Add domain….

  2. Fill in the form:

    Field What to enter
    Domain The email domain to route through your provider, for example company.com.
    Issuer (?) The provider's issuer URL. It is one fixed value for the whole identity provider, not per application. For Google it is always https://accounts.google.com.
    Client ID The client ID from your identity provider.
    Client secret The client secret. The field reads "never shown again after save".

  3. Select Add domain. The button stays unavailable until all four fields are filled in.

The domain appears under Configured domains with the status Not verified. A domain can be configured only once in a deployment; otherwise the page shows "An SSO config for domain 'company.com' already exists" (with the domain you entered). The client secret is stored encrypted and is never displayed again.

Register the redirect URI#

Under the list, the Redirect URI (?) field shows the callback address, which ends in /auth/callback, for example https://wi.company.com/auth/callback. Select Copy and register this exact URL as the redirect (callback) URI of your OIDC client in your identity provider.

The address is your deployment's public base URL (the WI_PUBLIC_BASE_URL setting) followed by /auth/callback. Open the Settings page at your deployment's public address so that the field shows the same value the application sends to your provider. A mismatch makes the provider reject sign-in with a redirect error.

Verify the domain#

SSO is used for a domain only after you prove you control it. Until then, people on that domain keep signing in with passwords.

  1. On the Not verified domain, copy the record shown under "To verify you control this domain, add a DNS TXT record:". It has the form _wi-verify.company.com TXT "<verification token>".
  2. Add that TXT record in your DNS, with the token as its value.
  3. Once DNS has propagated, select Verify.

When the lookup finds the token, the status changes to Verified. If it does not, the page shows "No _wi-verify.<domain> TXT record matching the expected verification token was found — add it and try again". Wait for DNS to update and select Verify again.

Edit a domain#

Select Edit on a domain to change its Issuer, Client ID or Client secret, then Save. Leave Client secret blank to keep the existing one ("leave blank to keep the existing secret"). The domain name and its verification status do not change when you edit.

What happens when someone signs in#

After the person signs in at your provider, the provider must return a verified email address that belongs to the configured domain. Otherwise sign-in fails with a generic "Sign-in failed".

  • If the email matches a person in your company, they sign in as that person with the abilities you assigned on the Team page. People you invited in advance keep those abilities.
  • If no one has that email, a person is created automatically with no abilities beyond membership. Assign abilities afterwards on Settings → Administration → Team. People who sign in only through SSO show as pending there because they have no password.
  • A revoked person cannot sign in.

How the sign-in page decides between SSO and a password is covered in How sign-in chooses a method.