Set up SCIM provisioning

Let your identity provider create, deactivate and group people automatically with SCIM 2.0: generate the token, connect Microsoft Entra, and map groups to abilities and Teams.

For: Administrators (the admin ability) · Last updated

SCIM 2.0 lets your identity provider push people and groups to Workforce Intelligence on its own schedule, independent of sign-in. With it connected, your provider can create a person before their first sign-in, deactivate them when they leave, and keep group membership in step with abilities and Teams.

SCIM does not replace single sign-on. People still sign in through the protocol you configured for their domain. You need the admin ability to generate the token.

What you give your identity provider#

Two values, both on the domain's row at Settings > Administration > Single sign-on:

Value Where it comes from
SCIM base URL Shown on the row. It is the address you opened Settings at, followed by /scim/v2, for example https://wi.company.com/scim/v2. Open Settings at your deployment's public address so the value is the one your provider can reach.
SCIM bearer token Select Generate SCIM token on the row.

The token is shown once, with the note "Shown once — copy it now. Generating a new token replaces this one." Only a one-way hash is stored, so it cannot be shown again. If you lose it, select Generate new SCIM token. The old token stops working at that moment, so update your provider straight away.

Each domain has its own token, and a token acts for that domain's configuration only. Every generation is recorded in the audit log as "Generated a SCIM provisioning token".

Your provider sends the token as a standard bearer credential (Authorization: Bearer <token>). Requests without a valid token are refused.

What SCIM does#

Workforce Intelligence serves these resources under the base URL:

  • Users at /Users: list (with a userName eq "…" filter), fetch, create, replace and update.
  • Groups at /Groups: list (with a displayName eq "…" filter), fetch, create, replace and update members.
  • The discovery documents /ServiceProviderConfig, /ResourceTypes and /Schemas, which provider setup wizards read. Bulk operations, sorting, ETags and password changes are not supported.

Only the eq filter on userName (Users) and displayName (Groups) is understood. Any other filter is ignored and returns everything.

Users#

  • Matching. A person is matched by email address within your company. If a person with that email already exists, for example one you invited, SCIM links to them instead of creating a second one, and updates their name.
  • Email. The person's email is the primary entry in emails, otherwise the first entry, otherwise the userName. Make sure it is the same address the person signs in with.
  • New people are created with no abilities beyond membership and no password. They sign in only through your identity provider. The creation is recorded in the audit log as a person provisioned through SCIM.
  • An email already used in a different company is refused with a conflict error.

Deactivation#

When your provider sets a person's active attribute to false, Workforce Intelligence treats it exactly as revoking the person: they are signed out of every session at once and cannot sign in. Setting active back to true restores access. Both are recorded in the audit log as revoked or restored, attributed to SCIM. The person's account and work are not deleted.

Provisioning does not delete anyone: there is no delete request for users or groups.

Groups, abilities and Teams#

A group's name (displayName) is matched against the same mapping you maintain with Edit mapping on the domain, which sign-in role mapping uses. A group name plays the role of the value in a mapping row.

  • Abilities. A group grants an ability only if a mapping row on that domain has the group's name as its value. A group with no row grants nothing. You decide which groups carry abilities, so a group pushed from your provider can never give itself one.
  • Teams. Every group your provider pushes gets a Team with the same name, created the first time the group arrives and kept in step with the group's members. If a Team with that name already exists, the group takes it over. No mapping row is needed. Renaming a group in your provider creates a new Team rather than renaming the old one.
  • Abilities and Teams that SCIM changes are stored the same way as ones you set by hand, on the Team page, and each change is recorded in the audit log, attributed to SCIM.

Two behaviors to plan for:

  • When your provider sends a group in full (create or replace), membership is made to match exactly: everyone in the group gains the group's mapped abilities and Team, and anyone holding a mapped ability who is not in the group loses it, including a person you gave that ability by hand on the Team page. The same applies to Team membership.
  • When your provider sends incremental changes (add or remove members), only the people named change.

A mapped ability granted through SCIM is saved on the person. This differs from sign-in role mapping, where mapped abilities apply for that session only.

Group names and sign-in mapping#

SCIM sends the group's display name. Sign-in role mapping matches whatever your provider puts in the claim or attribute, which for Entra group claims is the group's Object ID by default. A single mapping row can serve both only when the two values are the same text. If they are not, add one row for the name (for SCIM) and one for the ID (for sign-in).

Connect Microsoft Entra#

These steps use the Entra admin center. Screen names can change; the values you enter are the ones above.

  1. In Workforce Intelligence, open Single sign-on, find the domain's row and select Generate SCIM token. Copy the SCIM base URL and the SCIM bearer token.
  2. In Entra, open the enterprise application for Workforce Intelligence, or create one with New application > Create your own application and the option to integrate an application not in the gallery.
  3. Open Provisioning and set Provisioning Mode to Automatic.
  4. Under Admin Credentials, paste the base URL into Tenant URL and the token into Secret Token.
  5. Select Test Connection. The discovery documents are served for exactly this kind of check, and they refuse a wrong token, so a failure here usually means a wrong address or token.
  6. Under Mappings, keep Provision Microsoft Entra ID Users and Provision Microsoft Entra ID Groups enabled. Check that the user mapping sends an address as userName (or as the primary email) that matches the one people sign in with.
  7. Under Settings, set Scope to Sync only assigned users and groups, then assign the people and groups to the application under Users and groups.
  8. Set Provisioning Status to On and save.

Entra runs its first cycle shortly after, then repeats on its own schedule. You can use Provision on demand for a single person or group to see the result sooner.

To give a group an ability, add a mapping row (Edit mapping) whose value is the group's display name, as it appears in Entra, and pick the ability. The next time Entra pushes that group, the members gain the ability.

To remove access, unassign the person from the application, or disable the account. Entra sends the deactivation described above.

Check that it works#

  • The audit log shows people provisioned, revoked or restored through SCIM, and ability and Team changes attributed to SCIM.
  • A Team with the same name exists for each group your provider has pushed.
  • If your provider reports an authentication error, generate a new token and paste it again. An old token is rejected as soon as a new one is generated.

For other identity providers, point their SCIM connector at the same base URL and token. This article describes what Workforce Intelligence accepts; consult your provider's documentation for its connector screens.