How-to guide
Provision accounts with SCIM
Let Sovrain create, update and deactivate accounts in an application over SCIM 2.0, and choose who gets an account there.
This guide makes Sovrain keep accounts in an application up to date: it creates an account when a person joins, updates it when their details change, and deactivates it when they leave. Sovrain pushes these changes to the application’s SCIM 2.0 server.
Sovrain is only a SCIM client. It does not offer a SCIM server, so other systems cannot push accounts into Sovrain over SCIM.
Before you start
From the application, get:
- its SCIM base URL, for example
https://expenses.acme.example/scim/v2; - a bearer token for that SCIM server. Sovrain authenticates only with a bearer token.
The application’s SCIM server must support filtering users by userName, because Sovrain always looks an account
up before creating it. Without filtering, Sovrain cannot create accounts there.
Add provisioning to an application
Choose one:
- For a SAML app that should also get accounts: open the application, and on the App identity tab tick SCIM provisioning for this app. For a new application, tick Add SCIM provisioning to this app on the Add application form. The application’s page then has an SSO / Provisioning switch above the tabs; select Provisioning.
- For an application that only needs accounts, without sign-in: select Add application, choose the Application type Standalone SCIM (provisioning only) and select Create application.
OpenID Connect applications cannot have provisioning.
Connect to the application
- Open the Connection tab.
- Fill in SCIM base URL (HTTPS, on a publicly reachable address; internal addresses such as 10.x or 192.168.x are refused) and paste the Bearer token. Sovrain stores the token encrypted and never shows it again.
- Select Test connection. Sovrain reads the server’s capabilities and shows Connection OK or what failed. Diagnostics — last test shows every request and answer.
- Optionally select Test with user…. Sovrain creates a temporary test user in the application, reads it back and deletes it. This proves that creating accounts really works.
The other provisioning tabs stay locked until a test passes. Changing the base URL or the token locks them again until the next passing test.
Choose what Sovrain may do
On the Options tab:
- Create users, Update user attributes and Deactivate users are all on. Turning off Deactivate users also stops Sovrain from deleting accounts, except when you select Force sync… or Remove on a drifted account.
- Under Deprovisioning behavior, keep Set
active=falseto keep the account disabled in the application, or choose SendDELETEto remove it there.
Choose which attributes are sent
On the Attribute mapping tab:
- Pick the userName source:
email(the default; only a verified address is sent),login,idorexternalId. People without a value are skipped. - Check the mappings. Sovrain starts with
email,firstNameandlastName. Select + Add mapping to add more, for example a custom attribute. Suggestions come from the application after a test. - Select Save changes…. Sovrain shows Apply mapping changes? with how many accounts will be updated.
- Select Apply.
Choose who gets an account
Who gets an account (the provisioning scope) is separate from who can sign in (Group access). Set both.
On the Scope tab:
- Choose Selected groups and users or Everyone in this organization. A new connection starts with Selected groups and users and nobody selected, so nothing is sent until you add someone.
- Under Groups, select + Add group and pick a group, for example
Engineering. For each group choose:- Group+members to create the group in the application as well, or Members only to send just the accounts;
- in Group name in SP, pick an existing group in the application or type a new name.
- Under Users, select + Add user for people who should get an account without being in one of the groups.
- Select Save changes…. Sovrain shows Apply scope changes? with what will be created, changed or removed. Read it carefully: people who leave the scope are deactivated or deleted in the application.
- Select Apply, or Discard changes to go back.
Invited people get no account until they accept their invitation.
Turn provisioning on
- On the Connection tab, turn on Enable SCIM provisioning for this application.
- Open the Activity tab and watch Recent activity.
Every change waits 3 minutes before Sovrain sends it. Until then you can Cancel it on the Activity tab. Cancel holds that person or group for 5 minutes. To stop the change for good, change the scope, mapping or Options behind it in that time; otherwise the job comes back.
Failed changes, a refused token and accounts that Sovrain does not manage also show on the Activity tab later; Keep SCIM provisioning healthy covers them, and pausing or removing provisioning.
Related
- SCIM for the requests Sovrain sends.
- Limits.
- About provisioning.
- SCIM in the Admin API.