Sovrain
  1. Documentation
  2. Identity provider
  3. For developers
  4. Admin API

Reference

SCIM provisioning

Admin API endpoints for an application's SCIM connection - settings, token, test, mapping, scope, retries and reconciliation.

Endpoints under https://acme.sovrain.net/api/v1/apps/{slug}/scim, for applications of type SCIM and SAML applications with provisioning. Authentication and conventions are on Admin API. How provisioning works: SCIM.

Scope: apps:read for GET, apps:write for every other call.

These endpoints differ from the rest of the API:

  • Unknown fields in a body are ignored.
  • Every call except GET creates the connection when the application has none, except PUT …/provisioning with false (which deletes it), PUT …/token with a blank token and PUT …/scim with nothing to change (which answers 404).
  • Errors are 400, 404 and 422 in the usual format, or 500 with an empty body.

The connection object

{
  "enabled": true,
  "base_url": "https://expenses.acme.example/v2",
  "has_token": true,
  "last_test_status": "ok",
  "last_test_detail": null,
  "paused_since": null,
  "pause_reason": null,
  "username_source": "EMAIL",
  "options": {
    "create_users": true,
    "update_users": true,
    "deactivate_users": true,
    "deprov_behavior": "DEACTIVATE"
  },
  "scope_everyone": false,
  "mappings": [
    { "source": "email", "path": "emails[type eq \"work\"].value" },
    { "source": "firstName", "path": "name.givenName" },
    { "source": "lastName", "path": "name.familyName" }
  ]
}
FieldDefault for a new connectionNotes
enabledfalse
base_urlnullThe SCIM base URL of the application
has_tokenfalseThe token itself is never returned
last_test_statusnullok, auth_failed, timeout or error, in lower case
last_test_detailnull
paused_since, pause_reasonnullSet when the application answered 401 or 403
username_sourceEMAILEMAIL, LOGIN, ID or EXTERNAL_ID
options.create_userstrue
options.update_userstrue
options.deactivate_userstrueWhen false, users are neither deactivated nor deleted, except by Remove or Force sync… on drift
options.deprov_behaviorDEACTIVATEDEACTIVATE or DELETE
scope_everyonefalse
mappingsthe three shown above

The groups and users of the scope are not returned.

Get the connection

GET /api/v1/apps/{slug}/scim

Response 200: the connection object.

Errors: 404 not_found with Not found: SCIM connection of application portal when the application has no connection.

Change the connection

PUT /api/v1/apps/{slug}/scim

FieldTypeRequiredNotes
base_urlstringnoLeft out: unchanged. https only, on a public address. Sending it, even unchanged, marks the connection as not tested and stops jobs until a test passes.
optionsobjectnoLeft out: unchanged. Inside it, a boolean left out is false and deprov_behavior left out is DEACTIVATE.
options.create_usersbooleanno
options.update_usersbooleanno
options.deactivate_usersbooleanno
options.deprov_behaviorstringnoDEACTIVATE or DELETE
enabledbooleannoLeft out: unchanged

The parts are saved one after another: base_url, then options, then enabled. When one is refused, the parts before it stay saved.

To change only the options, leave base_url out.

{
  "options": {
    "create_users": true,
    "update_users": true,
    "deactivate_users": true,
    "deprov_behavior": "DEACTIVATE"
  },
  "enabled": true
}

Response 200: the connection object.

Errors:

StatuserrorWhen
422refusedSCIM base URL rejected: URL must use https: http://10.0.0.1/scim; SCIM base URL rejected: URL host cannot be resolved: expenses.acme.example

Turn provisioning on or off

PUT /api/v1/apps/{slug}/scim/provisioning

FieldTypeRequiredNotes
enabledbooleannotrue creates the connection if it is missing. false or left out deletes the connection with its mappings, scope and jobs.

Response 204. Accounts already created in the application are left as they are.

Set the token

PUT /api/v1/apps/{slug}/scim/token

FieldTypeRequiredNotes
tokenstringnoThe bearer token Sovrain sends to the application. At most 8192 characters. Blank or left out: nothing changes. Any other value, even the stored token, marks the connection as not tested.

Response 204. The token is stored encrypted and can never be read back.

Test the connection

POST /api/v1/apps/{slug}/scim/test

FieldTypeRequiredNotes
modestringnouser runs the test with a temporary user. Any other value, or none, runs the connection test.
base_urlstringnoSaved before the test
tokenstringnoSaved before the test

The body is optional. What each test does: SCIM › Tests.

Response 200, also when the test fails:

{
  "status": "ok",
  "detail": "…"
}

status is ok, auth_failed, timeout or error. A passing test lifts a pause and unlocks provisioning.

Errors: 422 refused when no URL or no token is stored, for example Set the SCIM base URL before testing the connection.

Replace the attribute mapping

PUT /api/v1/apps/{slug}/scim/mapping

PUT /api/v1/apps/{slug}/scim/mapping?dry_run=true

FieldTypeRequiredNotes
username_sourcestringyesEMAIL, LOGIN, ID or EXTERNAL_ID, in upper case
mappingsarraynoThe complete list, each {source, path}. source is a built-in attribute or user_attributes.<name> for an attribute of the bank. Left out: every mapping is removed. At most 200. Path rules: SCIM › Attribute mapping.
{
  "username_source": "EMAIL",
  "mappings": [
    { "source": "email", "path": "emails[type eq \"work\"].value" },
    { "source": "firstName", "path": "name.givenName" },
    { "source": "lastName", "path": "name.familyName" }
  ]
}

Response 200, the number of jobs queued (they wait 3 minutes before they run):

{ "queued": 12 }

With dry_run=true nothing is saved, and the response is the impact:

{
  "user_creates": 0,
  "user_updates": 12,
  "user_deactivates": 0,
  "user_deletes": 0,
  "group_creates": 0,
  "group_updates": 0,
  "group_deletes": 0,
  "skip_reasons": []
}

Errors: 422 refused, for example Unknown userName source 'email', or a path that breaks the rules.

Replace the scope

PUT /api/v1/apps/{slug}/scim/scope

PUT /api/v1/apps/{slug}/scim/scope?dry_run=true

FieldTypeRequiredNotes
everyonebooleannoDefault false. true: everyone in the organization is in scope.
groupsarraynoLeft out: none. At most 5000. Each {id, sync, sp_name}.
groups[].idstringyesGroup id
groups[].syncbooleannoDefault false: provision the members only. true: also create the group in the application.
groups[].sp_namestringnoThe group’s name in the application, when sync is true. At most 255 characters. Default: the group’s name.
usersarray of user idsnoUsers in scope besides the groups. Left out: none. At most 5000.

The whole scope is replaced. Invited users are never provisioned.

{
  "everyone": false,
  "groups": [ { "id": "SuT8oWQLVMPzwYQyhKjm32", "sync": true, "sp_name": "Engineering" } ],
  "users": ["FomjVqEuLmL5CBPAfVwYK2"]
}

Response 200:

{ "queued": 3, "canceled": 0 }

canceled counts jobs of the old scope that were still waiting and are no longer needed. With dry_run=true the response is the impact object shown above.

Errors: 422 refused for an unknown group or more than 5000 entries; 404 not_found for an unknown user.

Retry failed jobs

POST /api/v1/apps/{slug}/scim/jobs/retry-all

No body. Queues every failed and rejected job again.

Response 200:

{ "retried": 2 }

Reconcile now

POST /api/v1/apps/{slug}/scim/reconcile

No body. Runs a reconciliation with the application and waits for it. What it does: SCIM › Reconciliation.

Response 200:

{
  "outcome": "not_operational",
  "message": "Reconciliation skipped — provisioning is not active for this application."
}

outcome is done, not_operational or sp_unreadable. The drift found is not returned; it is shown on the application’s Activity tab.