How-to guide
Receive accounts from Sovrain over SCIM
Build the SCIM server side of your app so that Sovrain can create, update, deactivate and delete its accounts and groups.
This guide prepares your application to receive accounts from Sovrain. Sovrain is a SCIM 2.0 client: it calls your application’s SCIM server to create, update, deactivate and delete accounts, and optionally groups. It assumes you know SCIM 2.0 (RFC 7643 and RFC 7644); the exact requests and payloads are in SCIM.
Before you start
- Your SCIM server must be on
https, at a public address. Sovrain refuses private addresses and plainhttp. - Decide on the base URL, for example
https://portal.acme.example/scim/v2, and issue a bearer token for Sovrain. Sovrain sends onlyAuthorization: Bearer <token>; it cannot use OAuth, Basic or mutual TLS. - An admin of the organization enters both in Sovrain; see Provision accounts with SCIM.
Accept every request Sovrain sends
- Answer within 10 seconds, with at most 4 MiB.
- Read
Content-Type: application/scim+json. Answer JSON asapplication/scim+jsonorapplication/json; Sovrain accepts both. A2xxanswer with a body that is not JSON counts as a failure; an empty body is fine. - Answer directly. Sovrain does not follow redirects and treats any
3xxas an error. - Serve every endpoint on the scheme, host and port of the base URL. Sovrain sends nothing to another origin, also
when your
/ResourceTypesnames one.
Describe your server
During the admin’s connection test, Sovrain reads three discovery endpoints:
GET /ServiceProviderConfig. Setpatch.supportedtotrueif you take PATCH, andfilter.supportedtotrue. If you page listings by cursor, setpagination.cursortotrue.GET /ResourceTypes, with theendpointofUserandGroup. Without it, Sovrain uses/Usersand/Groups.GET /Schemas. Sovrain refuses mappings to attributes you mark"mutability": "readOnly".
If you serve no /ServiceProviderConfig (404 or 405), Sovrain assumes PUT only, filtering and index paging, and
then checks that GET /Users?count=1 does not answer 404. Any other error fails the test.
Handle users
Support the
userNamefilter. Before every create, Sovrain asks:GET /scim/v2/Users?filter=userName%20eq%20%22anna%40acme.example%22&count=2Return only exact matches in
Resources, and an empty list when there is none. One match is linked to the Sovrain account and updated instead of created; two matches fail the job as ambiguous. Without a working filter, Sovrain cannot create users at all.On
POST /Users, create the account and return it with itsid. Sovrain stores thatidand uses it for every later call. If you return noid, Sovrain looks the account up byuserNameagain.Store what Sovrain sends.
userNamecomes from the source the admin chose (by default the verified email) and can change later.externalIdis Sovrain’s internal account number. Other attributes follow the admin’s mapping; see SCIM › User resource.Take updates. With PATCH, Sovrain sends one
replacefor every attribute it maps,userName,externalIdandactiveincluded, and oneremovefor every mapped attribute that has no value any more:{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "replace", "path": "active", "value": true }, { "op": "replace", "path": "emails", "value": [{ "type": "work", "value": "anna@acme.example" }] }, { "op": "replace", "path": "externalId", "value": "42" }, { "op": "replace", "path": "name.givenName", "value": "Anna" }, { "op": "replace", "path": "userName", "value": "anna@acme.example" }, { "op": "remove", "path": "name.familyName" } ] }Without PATCH, Sovrain reads the account with
GET /Users/{id}, changes what it maps, leaves the rest as you returned it, dropsmetaandgroups, and sends it back withPUT /Users/{id}.Take deactivation. Sovrain sets
activetofalse, with a PATCHreplaceor with the merged PUT. When the person comes back, an ordinary update setsactivetotrueagain.On
DELETE /Users/{id}, delete the account. A404counts as done.
Answer 404 for an id only when the account is really gone. When an update gets 404, Sovrain drops its link
and creates the account again on its next run.
Handle groups, if the admin sends them
Sovrain sends groups only for groups the admin sets to Group+members.
- Support the
displayNamefilter: before creating a group, Sovrain asksGET /Groups?count=2&attributes=id,displayName,externalId&filter=displayName eq "Engineering". If your filter returns groups of other names, Sovrain lists all groups instead. The admin pages also search withdisplayName co "…"to pick one of your existing groups. - On
POST /Groups, create the group withdisplayName,externalIdandmembers, and return itsid. - Take updates of the whole member list, each member
{"value": "<the user's id in your app>"}: a PATCHreplaceofmembers(and ofdisplayNameafter a rename), or a merged PUT without PATCH.[]empties the group. - On
DELETE /Groups/{id}, delete the group. Sovrain deletes only groups it created.
Answer listings
Several times a day, Sovrain reconciles: it lists your users and groups and repairs its links. Answer:
GET /scim/v2/Users?attributes=id,userName,active&startIndex=1&count=200
GET /scim/v2/Groups?attributes=id,displayName,externalId&startIndex=1&count=200
Return Resources and totalResults, honouring the 1-based startIndex. If you page by cursor, return
nextCursor; Sovrain then asks for cursor=<value>&count=200. Sovrain gives up, and changes nothing, beyond 50,000
entries or 45 seconds. What it does with the listing: SCIM › Reconciliation.
Answer errors so that Sovrain does the right thing
| When | Answer | What Sovrain does |
|---|---|---|
| The token is wrong or revoked | 401 | Pauses the whole connection until an admin’s test passes |
| You are overloaded | 429 with Retry-After in seconds or as a date | Waits as long as you ask, at most 24 hours |
| The request will never succeed as sent | 400 with a scimType such as invalidValue or invalidPath, or 501 | Stops retrying the job until an admin retries it |
| Anything temporary | 5xx | Retries with growing pauses |
Do not answer 403 for a single account or a missing permission on one attribute: Sovrain reads 403 like 401
and pauses every job of the connection. The scimType values that stop retries and the retry pauses are in
SCIM › Retries.
Check your server
Ask the admin to run Test connection and then Test with user… in Sovrain. The second test creates a user
named like scim-test-1a2b3c4d@acme.invalid, reads it by id, finds it with the userName filter and deletes it,
so your server must accept an email address on the .invalid domain. The test fails if the filter does not return
the user just created.
What Sovrain never sends, such as /Bulk, ETags or extension schemas: SCIM › Not supported.
Related
- About provisioning, for why Sovrain pushes and when changes are sent.
- SCIM, for the schedule, the scope and every rule.