SCIM 2.0 User Provisioning
Overview
SCIM 2.0 lets an identity provider create, update and deactivate Scaler accounts from the directory, without anyone signing in first. This document explains how to connect one.
SCIM is an addition to SAML2 SSO, not a replacement for it: SCIM decides who has an account, SAML decides how they sign in. SSO must already be configured before provisioning can be switched on.
The examples below use Microsoft Entra ID, which is the identity provider Scaler has validated against. Any SCIM 2.0 client works the same way.
What Scaler Provides
Scaler’s team enables provisioning per organization and supplies two values:
| Value | Where it goes in the IdP | Example |
|---|---|---|
| Tenant URL | Tenant URL | https://sso.scalerglobal.com/scim/[company_uuid]/v2 |
| Secret Token | Secret Token | scim_… (shown once when it is issued) |
The [company_uuid] is the same identifier used in the SAML endpoints.
The secret token is stored hashed and cannot be read back. If it is lost, ask Scaler to issue a new one — the old one stops working the moment the new one is issued.
Every SCIM request must carry the token:
Authorization: Bearer scim_…Requests without it — or with a withdrawn one — are answered 401 with a SCIM error body. This is also what happens before provisioning has been enabled for the organization, so switch-on order matters: configure the IdP first, then ask Scaler to enable it.
Supported Endpoints
All endpoints are under the tenant URL above.
| Resource | Methods |
|---|---|
/Users | GET, POST |
/Users/{id} | GET, PUT, PATCH, DELETE |
/Groups | GET, POST |
/Groups/{id} | GET, PUT, PATCH, DELETE |
/ServiceProviderConfig | GET |
/ResourceTypes | GET |
/Schemas | GET |
Filtering (filter=userName eq "…"), index pagination (startIndex / count, up to 500 per page) and PATCH operations are supported.
User Attribute Mappings
Scaler stores a small set of attributes. Everything else a directory sends is accepted and ignored.
| SCIM attribute | Stored as | Notes |
|---|---|---|
userName | Email address | Required. Must be the same address the SAML assertion carries. |
active | Account state | false deactivates, true restores. See Deprovisioning below. |
displayName | Full name | Wins over name.* when a request carries both. |
name.givenName, name.familyName | Full name | Combined into the single name Scaler shows. |
externalId | IdP object id | Stored for reference; Scaler never matches on it. |
emails | — | Read-only. Returned from the stored address; writes are ignored. |
One attribute owns the email address
userName is the account’s identity in Scaler: it is what SAML matches at login, and what the directory’s own userName eq lookup finds. emails[type eq "work"].value is returned as a copy of it and never written back.
In Entra ID, remove the emails[type eq "work"].value mapping from the provisioning attribute list, or map it from the same source as userName. Leaving Entra’s default (mail) in place while userName comes from userPrincipalName means the directory reports a mismatch on every sync cycle for any user whose two addresses differ.
Map userName from whichever attribute the SAML assertion uses — for most Entra tenants that is userPrincipalName.
How Existing Users Are Handled
Switching provisioning on does not start an organization from scratch.
- A user who already exists in Scaler with the same email address — invited by an administrator, or created on their first SSO login — is taken over by the directory. They keep their id, their access and their history.
- The takeover happens on the first write. Until then the directory’s
userName eqlookup does not return them, so the IdP sends a create, and Scaler answers with the existing account rather than a new one. Expect the provisioning log to say “create” the first time, for a user you know is already there. - From then on the directory is the source of truth. They sign in through SSO, and their password (if they had one) no longer works.
- A user is never duplicated. An address already in use by a different organization, or by another SSO tenant, is refused with
409 uniqueness. - The endpoints only ever show the directory its own users. Colleagues in the same organization who have never belonged to it are not listed and cannot be written to; naming one by their exact address in a create is what takes them over, and there is no other way to reach them.
Just-in-Time Creation Is Disabled
Before SCIM, an unknown user who passed SSO was created on the spot as a Member. Once provisioning is enabled that stops: the directory decides who has an account.
Someone who reaches SSO without having been provisioned is refused, and told to ask their IT administrator to assign them to the Scaler application. Assigning them in the directory creates the account on the next sync cycle.
Organizations without SCIM are unaffected: just-in-time creation works exactly as before.
Deprovisioning
Removing someone’s access is reversible, and is triggered either way a directory asks for it:
PATCH /Users/{id}withactive: false— what Entra ID sends when a user is unassigned, disabled or deleted.DELETE /Users/{id}— treated the same way, and answered204.
Either one:
- blocks SSO login for that account;
- revokes every API token it holds, immediately;
- refuses every request the account was already making, so a browser left open on Scaler is sent back to the sign-in screen on its next action;
- stops all notifications to it.
Nothing is deleted. The account keeps its Scaler id, its SCIM id and everything recorded against it.
Restoring is active: true, which is what a directory sends when someone is re-assigned or rehired. The same account comes back with the same ids and the same access. The user signs in again through SSO.
Timing
Deprovisioning is only as fast as the directory’s sync cycle. Entra ID syncs roughly every 40 minutes, so that is the window between unassigning a user and their access ending.
To remove access immediately, use Provision on demand in the IdP, or ask Scaler to deactivate the account in the admin panel — both take effect at once.
Groups and Roles
Provisioned groups are how a directory decides what its users may do in Scaler.
- The IdP pushes groups and their members to
/Groups. - Scaler’s team maps each group to a Scaler role.
- Membership changes then move users between roles on each sync cycle.
Rules:
- A user in no mapped group is a Member.
- A user in several mapped groups keeps the highest role of them. The order is Admin, then Member, then Asset Manager, then Visitor.
- A user removed from a mapped group returns to Member.
- Groups a directory pushes but nobody maps grant nothing.
A group must reach Scaler before it can be mapped, so provision groups first and ask for the mapping afterwards.
Setting It Up in Microsoft Entra ID
- Open the Scaler enterprise application, then Provisioning.
- Set Provisioning Mode to Automatic.
- Enter the Tenant URL and Secret Token supplied by Scaler.
- Select Test Connection. It should succeed.
- Under Mappings → Provision Microsoft Entra ID Users, remove the
emails[type eq "work"].valuemapping (see One attribute owns the email address above) and check thatuserNamecomes fromuserPrincipalName. - Under Settings, set Scope to the users and groups you want in Scaler, and turn Provisioning Status on.
- Assign users and groups to the application.
Use Provision on demand for a single user to confirm the end-to-end path before the first full cycle.
Troubleshooting
| Symptom | Cause |
|---|---|
Test Connection fails with 401 | Token wrong or withdrawn, or provisioning not yet enabled for the organization |
409 uniqueness on a create | That email address already belongs to a user in another organization |
| A user is told their account is not set up | They are not assigned to the application, or the sync cycle has not run yet |
| A user is told their account has been deactivated | They are deactivated in Scaler; re-assign them in the directory to restore |
500 on a write, retried successfully next cycle | Scaler could not record the change in its audit trail, so it kept nothing; the IdP’s retry applies it |
| A user’s name keeps changing between sync cycles | displayName and name.* are mapped from sources that disagree |
| An address change does not take effect | emails is read-only — change the source userName is mapped from |