Sovrain
  1. Documentation
  2. Identity provider
  3. For developers

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 plain http.
  • Decide on the base URL, for example https://portal.acme.example/scim/v2, and issue a bearer token for Sovrain. Sovrain sends only Authorization: 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 as application/scim+json or application/json; Sovrain accepts both. A 2xx answer 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 3xx as an error.
  • Serve every endpoint on the scheme, host and port of the base URL. Sovrain sends nothing to another origin, also when your /ResourceTypes names one.

Describe your server

During the admin’s connection test, Sovrain reads three discovery endpoints:

  1. GET /ServiceProviderConfig. Set patch.supported to true if you take PATCH, and filter.supported to true. If you page listings by cursor, set pagination.cursor to true.
  2. GET /ResourceTypes, with the endpoint of User and Group. Without it, Sovrain uses /Users and /Groups.
  3. 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

  1. Support the userName filter. Before every create, Sovrain asks:

    GET /scim/v2/Users?filter=userName%20eq%20%22anna%40acme.example%22&count=2
    

    Return 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.

  2. On POST /Users, create the account and return it with its id. Sovrain stores that id and uses it for every later call. If you return no id, Sovrain looks the account up by userName again.

  3. Store what Sovrain sends. userName comes from the source the admin chose (by default the verified email) and can change later. externalId is Sovrain’s internal account number. Other attributes follow the admin’s mapping; see SCIM › User resource.

  4. Take updates. With PATCH, Sovrain sends one replace for every attribute it maps, userName, externalId and active included, and one remove for 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, drops meta and groups, and sends it back with PUT /Users/{id}.

  5. Take deactivation. Sovrain sets active to false, with a PATCH replace or with the merged PUT. When the person comes back, an ordinary update sets active to true again.

  6. On DELETE /Users/{id}, delete the account. A 404 counts 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.

  1. Support the displayName filter: before creating a group, Sovrain asks GET /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 with displayName co "…" to pick one of your existing groups.
  2. On POST /Groups, create the group with displayName, externalId and members, and return its id.
  3. Take updates of the whole member list, each member {"value": "<the user's id in your app>"}: a PATCH replace of members (and of displayName after a rename), or a merged PUT without PATCH. [] empties the group.
  4. 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

WhenAnswerWhat Sovrain does
The token is wrong or revoked401Pauses the whole connection until an admin’s test passes
You are overloaded429 with Retry-After in seconds or as a dateWaits as long as you ask, at most 24 hours
The request will never succeed as sent400 with a scimType such as invalidValue or invalidPath, or 501Stops retrying the job until an admin retries it
Anything temporary5xxRetries 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.

  • About provisioning, for why Sovrain pushes and when changes are sent.
  • SCIM, for the schedule, the scope and every rule.