Sovrain
  1. Documentation
  2. Identity provider

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

ItemValue
AuthenticationAuthorization: Bearer <token>, the Bearer token of the connection (Application settings › Connection). No other method.
HeadersAccept: application/scim+json, application/json; Content-Type: application/scim+json
Timeout10 seconds
Response sizeAt most 4 MiB
Addresseshttps only, on a public address. The address is resolved once and the connection pinned to it.
RedirectsNot followed
OriginEvery request goes to the same scheme, host and port as the base URL
ProxyNone

Discovery

During the connection test, Sovrain reads GET {base}/ServiceProviderConfig, /ResourceTypes and /Schemas.

  • When /ServiceProviderConfig answers 404 or 405, Sovrain assumes: no PATCH, filtering supported, index paging, users at /Users and groups at /Groups. Then GET /Users?count=1 must not answer 404.
  • Any other error from /ServiceProviderConfig fails the test.
  • Cursor paging is used when the application advertises it.

Operations

OperationRequest
Find a userGET {Users}?filter=userName eq "<value>"&count=2
Create a userAlways looks the user up first. One match is linked instead of created; more than one fails as ambiguous. Otherwise POST {Users}.
Update a userPATCH 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 userSets active to false
Delete a userDELETE. A 404 counts as done.
GroupsPOST 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" }
}
AttributeValue
userNameFrom userName source: email (default; verified address only), login, id or externalId. A user without a value is skipped. userName is sent on every update.
externalIdSovrain’s internal account number (the id attribute), not the OpenID Connect sub
activetrue; false when deactivated
Mapped attributesOne per attribute mapping. email is sent only when verified.

Attribute mapping

RuleDetail
Default mappingsemail → emails[type eq "work"].value, firstName → name.givenName, lastName → name.familyName
SourceA built-in attribute (email, firstName, …) or an attribute of the bank written as user_attributes.<name>, for example user_attributes.department
Path formsA dotted path (name.givenName) or one filter step (emails[type eq "work"].value)
Reserved rootsschemas, id, userName, externalId, active, groups, meta, password
Extension schemasPaths with a schema URN are refused
Read-onlyAttributes the application declares read-only are refused
CountAt 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.
  • displayName is the Group name in SP, or the group’s name.
  • externalId is sent when the group is created only.
  • members lists 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

TaskWhen
Compare Sovrain with what was sentEvery 60 seconds; at once after saving the mapping or the scope
Wait before a job is sent3 minutes; a waiting job can be cancelled
Jobs per runAt most 200, or 45 seconds
Order in a runUser creates, user updates, group updates, group creates, group deletes, deactivations, deletions
Reconciliation00:15, 06:15, 12:15 and 18:15 UTC
Finished jobs kept30 days; removed daily at 03:30 UTC. Waiting and running jobs are kept.

All times are UTC.

Retries

Answer from the applicationWhat Sovrain does
A network error, a timeout, or any other status of 300 or moreRetries after 30 seconds, 1 minute, 5 minutes, 30 minutes, 1 hour, 5 hours, 24 hours, then every 24 hours
429Waits for Retry-After (60 seconds if missing, at most 24 hours)
401 or 403Pauses the whole connection. Only a passing connection test lifts the pause.
501, or scimType mutability, invalidSyntax, invalidPath, noTarget, invalidValue, invalidVers, invalidFilter, sensitiveRejects the job without retrying, until an admin retries it

Tests

TestWhat it does
Test connectionRuns 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, the groups attribute on users, nested groups.
  • Undoing provisioning: removing a connection leaves the accounts in the application as they are.