Set up single sign-on · Workforce Intelligence docs

Single sign-on lets people from your company domain sign in through your own identity provider instead of a password. Workforce Intelligence supports two protocols: OpenID Connect (OIDC) and SAML 2.0. Use SAML for identity providers that only speak SAML, such as ADFS, or older Okta and Entra applications. You configure each email domain at Settings > Administration > Single sign-on, and you need the admin ability. Others see "Managing single sign-on requires the admin role."

Each domain uses exactly one protocol. Every configured domain shows a chip, OIDC or SAML, next to its name, and a status of Verified or Not verified. A domain can be configured only once in a deployment; otherwise the page shows "That domain is already configured."

Choose a protocol and add a domain#

Open Single sign-on and select Add domain.
In Protocol, choose OpenID Connect (OIDC) or SAML 2.0.
Enter the Domain: the email domain to route through your provider, for example company.com.
For OpenID Connect, fill in the fields described in the next section. For SAML 2.0 the form asks only for the domain; you add the identity provider details from the new domain's row.
Select Add domain. The button stays unavailable until the required fields are filled in.

The new domain's row is scrolled into view, ready for its next step.

The domain appears under Configured domains as Not verified. People on that domain keep signing in with passwords until you verify the domain and the protocol's settings are complete.

Set up OpenID Connect#

In your identity provider, create an OIDC web application (client) that uses the authorization-code flow, and note its client ID and client secret. You also need the provider's issuer URL. The issuer must serve its discovery document at <issuer>/.well-known/openid-configuration, the issuer value inside that document must match what you enter exactly, and the issuer and the endpoints it advertises must use HTTPS and resolve to public addresses.

Field	What to enter
Issuer	The provider's issuer URL, starting with `https://`. 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".
Claim name	Optional. This claim is read first. If it is blank or finds nothing, the standard names listed under Which claims are read are read too. Set it if your provider uses a custom or namespaced claim, such as a custom Auth0 claim.

The client secret is stored encrypted and is never displayed again.

Below the domain list, the OIDC redirect URI field shows the callback address, which ends in /auth/callback, for example https://wi.company.com/auth/callback. The help line below the field reads "Register this exact URL as the identity provider's redirect/callback URI." Select Copy and register this URL as the redirect (callback) URI of your OIDC client. The address is the one you opened Settings at, followed by /auth/callback, so open the Settings page at your deployment's public address (the WI_PUBLIC_BASE_URL setting). A mismatch makes the provider reject sign-in with a redirect error.

To change an OIDC domain later, select Edit, change Issuer, Client ID, Client secret or Claim name, and select Save. Leave Client secret blank to keep the existing secret. The domain name and its verification status do not change when you edit.

Set up SAML 2.0#

SAML setup starts on the Workforce Intelligence side. Your identity provider needs Workforce Intelligence's details (the service provider details) before it can give you its own metadata, so you add the domain first, create the application in your identity provider, and then come back with the provider's metadata URL or metadata.

1. Add the domain#

Select Add domain, choose SAML 2.0 as the Protocol, enter the Domain, and select Add domain. The form has only these two fields and explains: "Add the domain first. Its service provider details then appear here, ready to give to your identity provider."

The identity provider details, Role attribute name and Allow sign-in started from the identity provider are all set from the new domain's row, with Add identity provider details or Edit (step 3 and step 5).

2. Create the application in your identity provider#

When you add a SAML domain, Workforce Intelligence generates a signing key pair for it. The new domain's row shows Identity provider details needed and, under "Give these details to your identity provider, or upload the metadata file to it.", the service provider details:

Field	Notes
Service provider metadata URL	Listed first. Give this URL to your identity provider if it can import metadata from a URL; otherwise download the file and upload it there.
Service provider entity ID	Also called the audience, identifier or relying party trust identifier.
Assertion consumer service (ACS) URL	Also called the reply URL or single sign-on URL. It uses the HTTP-POST binding.
Download SP metadata	A button that downloads the same metadata as a file, to upload to your provider.

Select Copy next to a value to copy it. Use whichever of these your provider accepts:

Give the provider the Service provider metadata URL, if it can import metadata from a URL. Okta and ADFS can do this.
Otherwise select Download SP metadata and upload the file to the provider. Entra's SAML setup accepts an uploaded service provider metadata file.
Or type the Service provider entity ID and Assertion consumer service (ACS) URL into the provider by hand.

The metadata includes the entity ID, the ACS URL and the certificate used to verify signed sign-in requests. In your provider, create a SAML application (an enterprise application in Entra, an app integration in Okta, a relying party trust in ADFS) with these details.

These values are built from your deployment's public base URL (the WI_PUBLIC_BASE_URL setting), so open the Settings page at that address. The metadata URL must be reachable by your identity provider from where it runs, because the provider fetches it directly.

In your provider, send the person's email address as the NameID (email address format). If the NameID is not an email address, an email or mail attribute is used instead. The email must belong to the configured domain. Send roles or groups as an attribute if you want role mapping.

3. Add the identity provider's details#

Copy the details from your identity provider's finished application and give them to Workforce Intelligence. On the domain's row, select Add identity provider details (or Edit). The form reads: "Enter your identity provider's metadata URL, add its metadata, or fill in its entity ID, sign-on URL and signing certificate." Provide the details in one of three ways:

Enter the provider's metadata URL in Identity provider metadata URL. Entra calls it the App Federation Metadata URL. The URL must start with https://, otherwise the field shows "Metadata URL must start with https://" and Save stays unavailable. Workforce Intelligence reads the metadata from the URL once, at the moment you select Save, and fills in the entity ID, sign-on URL and every signing certificate it lists; the URL itself is not kept. While it reads, the button shows Reading metadata….
Paste the provider's metadata XML into Identity provider metadata, or select Upload metadata file…. ADFS calls this federation metadata; Okta and Entra offer a metadata XML download.

Leave both blank and fill in all three fields yourself:

Field	What to enter
Identity provider entity ID	The provider's entity ID (its issuer), for example `http://adfs.company.com/adfs/services/trust`.
Sign-on URL	The provider's single sign-on URL. It must start with `https://`.
Signing certificate	The certificate the provider uses to sign assertions, in PEM form (starting `-----BEGIN CERTIFICATE-----`) or plain base64. Paste it or select Upload certificate…. The field's help reads "Paste one or more signing certificates. If your identity provider lists several, paste them all." See Signing certificates.

Use either the metadata URL or the metadata XML, not both: with both filled in, the page shows "Use either the metadata URL or the metadata XML, not both." and Save stays unavailable. If you give metadata (from the URL or as XML) and the three fields, anything you enter in the three fields takes precedence over the metadata. Metadata must be under 1 MB and must not contain a DOCTYPE or ENTITY declaration, whichever way you provide it.

The metadata URL must be reachable from the Workforce Intelligence server over HTTPS at the moment you save. If it cannot be read, nothing is saved and the reason appears under the form:

Message	What to do
"The metadata URL must start with https://"	Use the `https://` address. Plain `http://` addresses are refused.
"The metadata URL is not a valid web address."	Check the URL for typos, such as a missing host name or a malformed port.
"The metadata URL must be a public internet address."	The address must be reachable from the internet. An internal host, or a name that resolves to a private network address, is refused. Download the metadata XML and paste or upload it instead.
"Could not reach the metadata URL."	The server could not connect to the address, or its name does not resolve. Check the address and that your provider's metadata endpoint is publicly available.
"The metadata URL took too long to respond."	The provider did not answer in time. Try again, or paste or upload the metadata XML.
"The metadata URL redirected; use its final address."	Open the URL in your browser and copy the address it ends up at. Enter that address.
"The metadata URL returned an error (HTTP 404)."	The code varies, for example 403 or 500. Check that the URL is correct and the metadata is published.
"The metadata at that URL is larger than 1 MB."	Metadata must be under 1 MB. Use a smaller metadata document.
"The metadata at that URL is not valid XML."	The URL returned something that is not a metadata document. Check that it is your provider's federation metadata address.

After a successful fetch the same checks apply as for pasted XML, and they show their own messages: "IdP metadata is not valid XML", "IdP metadata is larger than 1 MB", "IdP metadata must not contain a DOCTYPE or ENTITY declaration", "IdP metadata has no identity provider (IDPSSODescriptor) entry", and "The metadata has no signing certificate (only an encryption certificate, or none). Paste the identity provider's signing certificate into the certificate field." If the server sends both the URL and the XML, it answers "Use either the identity provider metadata URL or the metadata XML, not both."

If the URL cannot be read from the server, download the metadata XML from your provider and paste or upload it instead.

If you fill in only some of the three fields, the page shows "Add the identity provider metadata, or fill in the entity ID, sign-on URL and signing certificate." and the button stays unavailable; the server rejects a partial set with "Provide the identity provider metadata, or all of: entity ID, sign-on URL and signing certificate."

Select Save. The domain row then shows the provider's entity ID and sign-on host instead of Identity provider details needed.

Signing certificates#

A SAML domain trusts every signing certificate you give it, one or several, and accepts an assertion signed with any of them. Identity providers often publish more than one at a time, for example during a key rollover.

Importing metadata, whether from a URL, pasted XML or an uploaded file, stores all the signing certificates the metadata lists. The imported set replaces the previous one, which is how a certificate rotation is picked up: open Edit and import the metadata or URL again.
Entering certificates by hand overrides the ones in the metadata.
Metadata that lists only encryption certificates is rejected unless you also paste a signing certificate.
A domain holds up to 20 certificates.
A certificate that has expired is ignored, as long as at least one valid certificate remains. If every certificate has expired, the save is rejected.
A certificate that starts later is kept, so you can publish the next key ahead of a rollover.
When you paste certificates by hand, use PEM blocks or plain base64, one after another. Paste only the certificate blocks: text around a certificate, such as the lines openssl prints, makes the whole paste be rejected.

The same field and rules apply when you edit the domain.

Entra tip: the App Federation Metadata URL of an enterprise application lists only that application's certificate, while the tenant-wide federation metadata lists many certificates. Either works, because every signing certificate the metadata lists is trusted.

What people see before the setup is complete#

While the identity provider details are missing, the domain row says Identity provider details needed, with the note "Create the application in your identity provider with the details below, then add its metadata here. Until then this domain signs in with a password." People on that domain keep signing in with a password. Nobody is sent to single sign-on until the identity provider details are complete and the domain is Verified.

4. Verify the domain#

Follow Verify the domain. You can add the DNS record at any point, before or after the other steps. SAML sign-in is offered only for Verified domains whose identity provider details are complete.

5. Optional settings#

Set these with Add identity provider details or Edit on the domain's row:

Role attribute name: optional. This attribute is read first. If it is blank or finds nothing, the standard names listed under Which claims are read are read too. Set it if your provider sends groups under another attribute name. Then use Edit mapping to map the values to abilities or Teams.
Allow sign-in started from the identity provider: off by default. See Sign-in started from the identity provider.

Edit a SAML domain#

Select Edit to change a SAML domain. Once the identity provider details are in, you can change:

Identity provider entity ID and Sign-on URL.
The signing certificates: Current signing certificate (Current signing certificates when the domain holds several) is shown read-only. Paste one or more in Replace signing certificate (or Upload certificate…) to replace the whole set, and leave it blank to keep the current ones. See Signing certificates.
Identity provider metadata URL: enter the provider's metadata URL to refresh the details from it. It is read once when you select Save (the button shows Reading metadata…), and is not kept, so to pick up a later change, such as a rotated signing certificate, enter the URL again and save. The new set of signing certificates replaces the previous one.
Replace from metadata: paste updated metadata XML (or Upload metadata…).
New metadata, from the URL or as XML, replaces the entity ID, sign-on URL and signing certificates with the values it contains, and any of those fields you change in the same edit take precedence. Use either the URL or the XML in one edit, not both. The same rules and errors apply as when you first add the details.
Role attribute name and Allow sign-in started from the identity provider.

Select Save to apply, or Cancel. When your provider rotates its signing certificate, update it here: enter the metadata URL again, paste new metadata, or replace the certificate.

Regenerate the service provider certificate#

Each SAML domain has its own signing key pair. While editing a SAML domain, select Regenerate service provider certificate to replace it. A confirmation reads "This replaces the certificate this domain uses to sign its sign-in requests. Sign-in through your identity provider may fail until you give it the new service provider metadata (or certificate) — download it from this domain after regenerating." Select Regenerate to continue.

After regenerating:

Select Download SP metadata on the domain (or copy the Service provider metadata URL).
Give the new metadata, or the new certificate from it, to your identity provider. The entity ID and ACS URL do not change.

If your provider checks the signature on sign-in requests, sign-in fails until it has the new certificate.

By default people start at the Workforce Intelligence sign-in page, which sends them to your provider and brings them back. Each of those sign-ins is tied to the browser that started it.

Select Allow sign-in started from the identity provider to also accept sign-ins that begin at your provider, for example when someone clicks the app's tile in the Okta or Microsoft My Apps portal. Those sign-ins cannot be confirmed to have started in the person's own browser, so leave this off unless your people need it. With it off, such a sign-in fails with "Sign-in failed. Please try again or contact your administrator."

Verify the domain#

SSO is used for a domain only after you prove you control it. This is the same for both protocols.

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>".
Add that TXT record in your DNS, with the token as its value.
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.

Map provider roles to abilities and Teams#

Select Edit mapping on a domain to grant abilities, or add people to Teams, from the roles or groups your identity provider sends. Each row pairs a value (for example idp-admins) with any number of abilities and Teams. Enter the exact group or role value your provider sends, as shown in your provider's admin console (for example Entra app roles or Okta group names).

Which claims are read#

The name you set (Claim name on an OIDC domain, Role attribute name on a SAML domain) is read first. If it is blank, or the sign-in carries nothing under it, Workforce Intelligence reads all of these standard names and combines their values:

groups
roles
group
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
http://schemas.microsoft.com/ws/2008/06/identity/claims/role
http://schemas.xmlsoap.org/claims/Group

So a misspelled name does not stop mapping when the provider sends one of the standard names. SCIM does not use these names: a group your provider pushes is matched by its display name.

Select Add row.
Enter the role or group value your provider sends under Group name.
Under Abilities mapped to this group, open the list and choose each ability the value grants: Admin, Manage Coworkers, Manage Knowledge Bases, Manage Apps, People Manager, Manage Compensation, Executive (view-only), Auditor or Member. Type to filter. Each choice appears as a chip in the field; select the x on a chip to remove it.
Under Teams mapped to this group, choose the Teams the value adds people to, the same way. Every row needs at least one ability or Team.
Select Remove on a row to delete it.
Select Save to apply the rows, or Cancel.

Mappings are evaluated at every sign-in. A value that matches several rows grants all of their abilities, so two rows with the same value work the same as one row with several choices. Mapped abilities apply for that session. They are not added to the Team page.

If your identity provider removes someone from a group, the ability ends at their next sign-in. Sessions last up to 14 days, so until then the person keeps what their last sign-in granted. Revoking the person ends their session immediately.
Abilities you assigned on the Team page are applied live and are never removed by mapping. Removing one on the Team page takes effect immediately, but it cannot remove an ability the mapping grants; that ends at the person's next sign-in after the mapping stops matching.

See Abilities.

Team membership from mapping#

At every sign-in, the person is added to each Team their values map to. A value that matches several rows adds them to all of those Teams. This works the same on OpenID Connect, SAML and when your provider also pushes groups through SCIM.

A membership created by a mapping is kept apart from one you added yourself on the Team page.
If the person no longer has a value, their next sign-in removes only the memberships that a mapping created, and only for Teams their remaining values no longer map to. Members you added by hand are never removed by sign-in. If you add someone to a Team on the Team page after mapping put them there, the membership becomes yours and stays.
Removing a row from the mapping has the same effect: at each person's next sign-in, the memberships it created are removed.
Each membership a sign-in adds or removes is recorded in the audit log as a Team member change made through single sign-on.

Auditor gives access to the audit log, which no other ability includes, so map it only to a group of people who should read it.

Entra tip: send groups#

To send groups from Entra, open your enterprise application, then Attributes & Claims, and add a group claim. Choose Security groups. With the source attribute Group ID, Entra sends each group's object ID. Set Role attribute name in Workforce Intelligence to the claim name shown in that Entra screen. For the default group claim it is http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. In the mapping, enter the group's Object ID as the value. Microsoft limits how many groups a SAML token carries, so a person in a very large number of groups may not receive the claim; in that case their groups do not map.

If you signed in but your abilities did not change, sign out and back in after changing a mapping. Then check that the attribute name matches the one your provider sends and that each value matches exactly.

What validation covers#

For SAML, Workforce Intelligence accepts a sign-in only when all of the following hold:

The assertion is signed with one of the signing certificates you configured, using SHA-256 or stronger. Unsigned assertions and SHA-1 signatures are rejected. The signature may use only the standard SAML transforms, enveloped signature and exclusive canonicalization; a response that asks for any other transform (for example XSLT, XPath or inclusive canonicalization) is rejected before it is processed. Current identity providers sign this way by default.
The assertion is addressed to this domain's Service provider entity ID and Assertion consumer service (ACS) URL.
The assertion is within its validity window. A tolerance of 60 seconds covers small clock differences between your provider and the server.
The assertion has not been used before. Each one works once.
For sign-ins started at the Workforce Intelligence sign-in page, the response answers the request that this same browser sent.
The email address in the assertion belongs to the configured domain.

For OIDC, the provider must return a verified email address that belongs to the configured domain.

What happens when someone signs in#

People use the same sign-in page for every method. They type their email and select Continue; if their domain is verified they are sent to your provider, whichever protocol it uses. See How sign-in chooses a method and Signing in.

If the email matches a person in your company, they sign in as that person with the abilities you assigned on the Team page, plus any abilities mapped from their roles. People you invited in advance keep those abilities.
If no one has that email, a person is created automatically with no abilities beyond membership, plus any mapped abilities. Assign abilities afterwards on Settings > Administration > Team. A person created this way has no password: they sign in only through your identity provider.
A revoked person cannot sign in.

Every sign-in through your identity provider, and every failed attempt, is recorded in the audit log, with the abilities your role mapping granted. A person created automatically on their first sign-in is recorded as created through single sign-on, and each ability a sign-in adds or removes through role mapping is recorded as granted or removed, and each Team membership it adds or removes is recorded as a Team member change. Adding, changing, verifying and deleting a domain is recorded there too, with the number of mapping rows and the abilities they grant, not the group values.

For SAML, the name comes from the assertion's display name, or its given name and surname.

Delete a domain#

Select Delete on a domain's row to remove its single sign-on configuration. A confirmation titled "Delete company.com?" (with the domain's name) asks you to confirm; select Delete to remove it, or Cancel. The domain disappears from Configured domains. If the deletion fails, the reason appears above the list.

For a domain that is Verified and fully set up, the confirmation reads: "People with an address on this domain will no longer be offered single sign-on and will be asked for a password instead. Their accounts and the work they've done are not deleted, but anyone whose account was created by signing in through single sign-on has no password, so they won't be able to sign in."

After you delete it:

The sign-in page asks people on that domain for a password, as it does for any address without single sign-on. See How sign-in chooses a method.
People you invited, who set a password, keep signing in with it.
People created automatically by signing in through single sign-on keep their accounts, their abilities and their work, but have no password and cannot sign in. Sign-in through the identity provider works again for them once you add and verify the domain again.
Anyone already signed in stays signed in until their session ends.
The domain's role mapping, its identity provider details and (for SAML) its service provider signing key pair are removed. If you add the domain again, it needs a new DNS verification, and a SAML domain gets new service provider details to give to your identity provider.

For a domain that is Not verified, or a SAML domain that still shows Identity provider details needed, nobody signs in through it, and the confirmation reads: "No one signs in through this domain's single sign-on, so deleting it doesn't change how anyone signs in."

Troubleshooting#

When SSO sign-in fails, the person returns to the sign-in page with one of these messages:

Message	Meaning
"Sign-in through your organization's identity provider isn't available right now. Try again later or contact your administrator."	The domain's configuration is not usable: the domain is not Verified, or its settings are incomplete.
"Your identity provider didn't share an email address with us. Contact your administrator."	The provider returned no email. For SAML, send the email as the NameID (email address format).
"Your email address hasn't been verified with your identity provider. Verify it, then try signing in again."	OIDC only. The provider reported the email as unverified.
"Your sign-in attempt expired or was invalid. Please try again."	OIDC only. The sign-in took too long or was started in a different browser session.
"Sign-in failed. Please try again or contact your administrator."	Any other failure. The page deliberately gives no detail.

For SAML, the "Sign-in failed" message covers every validation failure above: a wrong certificate, a mismatched entity ID or ACS URL, an expired or reused assertion, an email outside the configured domain, a sign-in started at the provider while Allow sign-in started from the identity provider is off, a sign-in that took more than ten minutes, or a revoked person. The reason is recorded in the server log. Check these first:

One of the Signing certificate entries matches the certificate your provider currently signs with. If your provider rotated it, import its metadata again in Edit.
The provider has the Service provider entity ID and Assertion consumer service (ACS) URL exactly as shown, or the current SP metadata.
The provider signs the assertion (signing the whole response alone is not enough).
The email in the assertion is on the configured domain.
The clocks on your provider and on the server agree to within a minute.

When you save certificates, the page can show one of these messages:

Message	What to do
"The identity provider certificate could not be read — paste the X.509 signing certificate (PEM or base64)"	The text is not a certificate. Paste the provider's X.509 signing certificate as a PEM block or plain base64.
"One of the identity provider certificates could not be read — paste only X.509 signing certificates (PEM or base64), one after another"	At least one part of the paste is not a certificate, or there is other text mixed in. Paste only the certificate blocks, one after another.
"The identity provider certificate text is too long"	Paste fewer certificates, or only the signing certificates.
"The identity provider lists more than 20 signing certificates — at most 20 are accepted"	Paste only the certificates your provider currently signs with.
"The identity provider certificate expired on YYYY-MM-DD — use its current signing certificate"	The certificate you gave has expired. Get the provider's current signing certificate, or import its metadata again.
"Every identity provider certificate has expired (the most recent on YYYY-MM-DD) — use its current signing certificate"	All the certificates have expired. Import the provider's current metadata, or paste its current signing certificate.