Reference
SCIM
How Sovrain provisions accounts in other applications as a SCIM 2.0 client - requests, payloads, scope, schedule, retries and limits.
Sovrain is a SCIM 2.0 client: it creates, updates, deactivates and deletes accounts and groups in other applications that offer a SCIM server. Sovrain itself has no SCIM server endpoint; other systems cannot provision users into Sovrain over SCIM.
Each application has at most one SCIM connection: an application of type Standalone SCIM (provisioning only), or a SAML application with SCIM provisioning added. The options are on Application settings; the API on Admin API › SCIM provisioning. Background: About provisioning.
When provisioning runs
Jobs run only while all of these hold:
- Enable SCIM provisioning for this application is on;
- the last connection test passed;
- the connection is not paused;
- the application is active. Disabling the application stops provisioning; nobody is deprovisioned because of it.
Changing the base URL or the token marks the connection as not tested until the next passing test.
Requests
| Item | Value |
|---|---|
| Authentication | Authorization: Bearer <token>, the Bearer token of the connection (Application settings › Connection). No other method. |
| Headers | Accept: application/scim+json, application/json; Content-Type: application/scim+json |
| Timeout | 10 seconds |
| Response size | At most 4 MiB |
| Addresses | https only, on a public address. The address is resolved once and the connection pinned to it. |
| Redirects | Not followed |
| Origin | Every request goes to the same scheme, host and port as the base URL |
| Proxy | None |
Discovery
During the connection test, Sovrain reads GET {base}/ServiceProviderConfig, /ResourceTypes and /Schemas.
- When
/ServiceProviderConfiganswers404or405, Sovrain assumes: no PATCH, filtering supported, index paging, users at/Usersand groups at/Groups. ThenGET /Users?count=1must not answer404. - Any other error from
/ServiceProviderConfigfails the test. - Cursor paging is used when the application advertises it.
Operations
| Operation | Request |
|---|---|
| Find a user | GET {Users}?filter=userName eq "<value>"&count=2 |
| Create a user | Always looks the user up first. One match is linked instead of created; more than one fails as ambiguous. Otherwise POST {Users}. |
| Update a user | PATCH with one replace per attribute and a remove per cleared attribute, when the application advertises PATCH. Otherwise GET, then PUT of the merged resource, keeping attributes Sovrain does not map. |
| Deactivate a user | Sets active to false |
| Delete a user | DELETE. A 404 counts as done. |
| Groups | POST to create; PATCH, or PUT without PATCH support, with the full member list to update; DELETE for groups Sovrain created |
An application that does not support filtering cannot have users created.
User resource
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "anna@acme.example",
"externalId": "42",
"active": true,
"emails": [{ "type": "work", "value": "anna@acme.example" }],
"name": { "givenName": "Anna", "familyName": "Nowak" }
}
| Attribute | Value |
|---|---|
userName | From userName source: email (default; verified address only), login, id or externalId. A user without a value is skipped. userName is sent on every update. |
externalId | Sovrain’s internal account number (the id attribute), not the OpenID Connect sub |
active | true; false when deactivated |
| Mapped attributes | One per attribute mapping. email is sent only when verified. |
Attribute mapping
| Rule | Detail |
|---|---|
| Default mappings | email → emails[type eq "work"].value, firstName → name.givenName, lastName → name.familyName |
| Source | A built-in attribute (email, firstName, …) or an attribute of the bank written as user_attributes.<name>, for example user_attributes.department |
| Path forms | A dotted path (name.givenName) or one filter step (emails[type eq "work"].value) |
| Reserved roots | schemas, id, userName, externalId, active, groups, meta, password |
| Extension schemas | Paths with a schema URN are refused |
| Read-only | Attributes the application declares read-only are refused |
| Count | At most 200 mappings |
Group resource
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"displayName": "Engineering",
"externalId": "idp-<tag>-<id>",
"members": [{ "value": "<the user's id in the application>" }]
}
- Groups are sent only for scope groups set to Group+members.
displayNameis the Group name in SP, or the group’s name.externalIdis sent when the group is created only.memberslists the active members who already exist in the application. The full list is sent each time.- When the application already has a group with that name that Sovrain did not create, the job is rejected. An admin links the existing group by choosing it as Group name in SP. A linked group is never renamed or deleted.
Scope
Who is provisioned is set on the Scope tab: Application settings › Scope.
- Invited users are never provisioned.
- Suspended users, removed users and users who leave the scope are deprovisioned: deactivated (default) or deleted, as set in Deprovisioning behavior, unless Deactivate users is off.
Schedule
| Task | When |
|---|---|
| Compare Sovrain with what was sent | Every 60 seconds; at once after saving the mapping or the scope |
| Wait before a job is sent | 3 minutes; a waiting job can be cancelled |
| Jobs per run | At most 200, or 45 seconds |
| Order in a run | User creates, user updates, group updates, group creates, group deletes, deactivations, deletions |
| Reconciliation | 00:15, 06:15, 12:15 and 18:15 UTC |
| Finished jobs kept | 30 days; removed daily at 03:30 UTC. Waiting and running jobs are kept. |
All times are UTC.
Retries
| Answer from the application | What Sovrain does |
|---|---|
A network error, a timeout, or any other status of 300 or more | Retries after 30 seconds, 1 minute, 5 minutes, 30 minutes, 1 hour, 5 hours, 24 hours, then every 24 hours |
429 | Waits for Retry-After (60 seconds if missing, at most 24 hours) |
401 or 403 | Pauses the whole connection. Only a passing connection test lifts the pause. |
501, or scimType mutability, invalidSyntax, invalidPath, noTarget, invalidValue, invalidVers, invalidFilter, sensitive | Rejects the job without retrying, until an admin retries it |
Tests
| Test | What it does |
|---|---|
| Test connection | Runs discovery with the URL and token |
| Test with user… | Creates scim-test-<8 hex>@<organization>.invalid, reads it by id, finds it by filter, then deletes it |
Reconciliation
Reconciliation lists the users and groups in the application (200 per page, at most 50,000 entries, at most 45 seconds; if any of it fails, nothing is changed) and then:
- links accounts by
userName; - adopts matching accounts that Sovrain did not create;
- activates again accounts that were deactivated directly in the application;
- creates again groups Sovrain created that have disappeared;
- records drift: accounts and groups in the application that Sovrain does not manage.
Reconciliation never deletes anything in the application. Drift is removed only by an admin, per entry with Remove or all at once with Force sync…, both after a confirmation and the 3-minute wait. Accounts are deactivated or deleted as set in Deprovisioning behavior, also when Deactivate users is off; groups are deleted.
Not supported
- A SCIM server in Sovrain (provisioning into Sovrain).
- OAuth, Basic or mutual TLS authentication towards the application.
- Extension-schema attributes (for example the enterprise user extension).
/Bulk, ETags, thegroupsattribute on users, nested groups.- Undoing provisioning: removing a connection leaves the accounts in the application as they are.