Set up SCIM provisioning

Let your identity provider create, update, and deactivate workspace users through SCIM 2.0, with a default role and a group-to-role mapping.

Written for
admin
Roles
owner, admin
Requires
Owner or Admin (only an owner can map to Owner); Business plan or higher (not the trial); A verified domain; Browser session with a recent re-authentication
Feature
authentication

SCIM provisioning lets the identity provider manage workspace users: create them when they are assigned to the application, keep their names current, and deactivate them when they leave. It is configured on the SCIM provisioning card under Settings → People → Authentication, which links to this page under "Read the SCIM provisioning guide". SCIM manages workspace users only; client users are managed under Clients. The endpoint reference for integrators is on SCIM.

Before you start

  • You need the Owner or Admin role and the Business plan or higher. The trial shows the card disabled.
  • Verify your domain first. SCIM provisions only addresses on a verified domain; a push for any other address is refused.
  • Mapping a group, or the default role, to Owner is an owner-only change.

Steps

  1. Under SCIM provisioning, turn on Enable SCIM provisioning.
  2. Choose the Default role for users no group mapping covers.
  3. Under Group → role mapping, select Add mapping for each group and the role it grants. Group names must match the provider's displayName; matching ignores case. Up to 200 mappings.
  4. Select Create bearer token and confirm your identity. The token is shown once; copy it.
  5. In the identity provider, configure provisioning with the Base URL shown on the card, https://saq.no/scim/v2, and the token, as described under Configure the identity provider.

The card shows the time of the last push, the last error if any, and the number of provisioned users and groups. Revoke stops a token immediately.

Configure the identity provider

The identity provider does the pushing; it needs the card's Base URL and a bearer token, and nothing else from SAQ. Two things to know before you start:

  • SAQ sends no email when a person is provisioned. Pair SCIM with single sign-on, so the provider that creates the account is also the one the person logs in through. SCIM and single sign-on are set up independently and neither requires the other.
  • The role a person gets comes from the card's default role and group mapping, never from roles or attributes in the provider. What the provider sends about a person beyond their address, name, id, and active flag is accepted and ignored.

Microsoft Entra ID

Provisioning is configured on an enterprise application. SAQ works with Entra's default attribute mappings, so the setup is mostly credentials and assignments. Test with one person before turning provisioning on.

  1. In the Entra admin center, open Enterprise applications → New application → Create your own application, name it (for example "SAQ provisioning"), and pick Integrate any other application you don't find in the gallery (Non-gallery). This must be a separate application from the app registration you made for single sign-on: the enterprise application Entra created for that registration only represents the sign-in app, and its Provisioning page says that automatic provisioning is not supported. The SCIM token is not tied to the single sign-on connection, so the two applications need no link; people provisioned through this one log in through the other.
  2. Under Provisioning → Get started, set Provisioning Mode to Automatic. Under Admin Credentials, enter the card's Base URL (https://saq.no/scim/v2) as Tenant URL and the bearer token as Secret Token, then select Test Connection and Save. The test is a lookup by userName that finds nobody, which is the expected answer; it does not change the card, whose last-request time updates on the first push.
  3. Under Mappings → Provision Microsoft Entra ID Users, keep the defaults. SAQ reads userName, externalId (the Entra object id), active, displayName, and the name fields; the rest of Entra's mapping (title, phone numbers, addresses, the enterprise extension's department and manager) is accepted and ignored, so nothing needs deleting. Check one thing: the source of userName, which is userPrincipalName by default. SAQ provisions only addresses on a domain you have verified, and userName is the address the person logs in with. If people's user principal names are on another domain than their email addresses (a tenant's onmicrosoft.com domain, for example), change the userName mapping to mail. The emails attribute is not used; the address is always userName.
  4. Under Mappings → Provision Microsoft Entra ID Groups, leave group provisioning on if roles should follow groups. Entra sends each assigned group's display name and object id, then its membership changes; SAQ matches the display name against the card's Group → role mapping, ignoring case. Only groups assigned to the application are provisioned, and Entra does not expand nested groups.
  5. Under Settings, keep Scope at Sync only assigned users and groups, so that only people you assign use seats. Under Users and groups, assign the people, or the groups whose members should be provisioned. A person in an assigned group is provisioned as a user, and the group itself is provisioned too, so the mapping can grant its role.
  6. Under Provisioning → Provision on demand, pick one person and read the result step by step. They appear under Members with their mapped role, and the card's counts increase. Then set Provisioning Status to On and select Save. Entra runs its cycles on its own schedule, roughly every 40 minutes; its Provisioning logs show every request, and the card shows the last push and the last error.

What to expect afterwards:

  • Unassigning a person, removing them from every assigned group, or deleting them in Entra deactivates them in SAQ, as described under "What deactivation does" below. Assigning them again reactivates the same resource.
  • Renaming a group in Entra renames the group in SAQ. The mapping on the card is by name, so change the mapping too, or the group stops granting its role.
  • A person raised to Owner or Admin through a group must set up two-factor authentication before they can enter the workspace, unless the single sign-on connection's MFA assurance rule vouches for their login.
  • A person whose address is on a domain you have not verified is refused; Entra shows the failure in its provisioning logs, and the card shows it as the last error. Verify the domain, fix the userName mapping, or invite the person instead.

Roles and authority

  • A user's role is the highest role among the groups they belong to, else the default role. Mapping changes apply at once, also to people created by JIT provisioning, from the groups claim of their last login.
  • A token carries the authority of the person who created it. A token created by an admin can grant Admin or Member however the mapping reads; only a token created by an owner can grant Owner, and an admin-minted token cannot demote or deactivate an owner. Demoting the creator caps their tokens at the new role; removing them from the workspace revokes their tokens, and another owner or admin creates a new one.
  • A promotion to Owner or Admin revokes the person's personal API tokens, and they must have two-factor authentication before they can enter the workspace.
  • Adopting an existing member never demotes them: a create for an address that is already a member keeps their role when it is higher than the mapping says. From then on, group changes apply the mapping in both directions.

What the identity provider may do

Resource Operations
Users Create, get, list (filter on userName or externalId), replace, update (active, displayName, name, externalId), deactivate, delete.
Groups Create, get, list, rename, add and remove members, delete.

userName is the email address and cannot be changed through SCIM; it is the person's global login. Attributes SAQ does not store (title, phone numbers) are accepted and ignored. The name of a person who already had a SAQ account before SCIM saw them is not rewritten; the profile belongs to the person.

What deactivation does

Setting active to false, or deleting the user, does the same as removing them under Members:

  • The membership ends, with its project memberships and viewer grants.
  • The person's API tokens for this workspace are revoked.
  • Their name on old tickets, comments, and time becomes a placeholder such as "Former member 3".
  • Their account and their other workspaces are untouched.

The SCIM resource keeps its id, so the provider can reactivate the person later; their real name shows again. The last-owner rule applies: an owner cannot be deactivated, nor demoted through a group change, while they are the only owner. The push is refused, the person keeps their role, and the card shows "A workspace needs at least one owner" as the last error, so a workspace always keeps an account that can administer it.

Rules

  • A person removed by an admin, or who left, is not re-joined by JIT provisioning. A SCIM push does bring them back.
  • People on domains you have not verified (a consultant's personal address, say) cannot be pushed. Invite them instead.
  • Provisioned users use seats like invited ones. When the plan has no seats left, the create is refused.
  • On a plan without SCIM, and in a read-only workspace, existing tokens can still deactivate users but not create or update them, so a downgrade never strands people who should be removed.

Common problems

The provider reports invalidValue on create. The address is not on a verified domain. Verify the domain, or invite the person. In Entra, check which attribute feeds userName: a user principal name on the tenant's own domain is refused when only the mail domain is verified.

I confirmed a change by signing in again through the identity provider, and it was not saved. On this page the round trip keeps what you were doing: the settings save, the token creation, or the revocation completes when you return, and the card shows its usual message ("Saved.", the new token, or "Token revoked."). If it does not, the session that came back was not a fresh login; confirm with a password or passkey instead.

Entra says "Out of the box automatic provisioning to … is not supported today". You opened Provisioning on the enterprise application that belongs to the single sign-on app registration. Provisioning is only offered on gallery and non-gallery applications; create a separate non-gallery application for SCIM as described in step 1 above. Nothing in the single sign-on setup needs changing.

Entra's Test Connection fails. A wrong or revoked token answers 401; a workspace with SCIM turned off, a read-only workspace, or a plan without SCIM answers 403 with the reason. The Tenant URL must be exactly the card's Base URL, with /scim/v2 and nothing after it.

A user was pushed but their role did not change. They are in more groups than the provider puts in the token (see the group overage note on Set up single sign-on), or the mapping's group name differs from the provider's displayName.

An owner was not deactivated. The token was created by an admin, or the person is the last owner.