SCIM provisioning

An identity provider adds and removes a space's people over SCIM 2.0. A provisioned person is an account and a membership; deactivation removes the membership and keeps the account.

Overview

Each space serves SCIM 2.0 Users under its own path. The provider creates a person as an account (if one does not already exist for the address) and a membership at the space's single sign-on role, or member when no role is configured. When the provider deactivates the person, the membership is removed and the account stays: the person may belong to other spaces, and a signed merge record that names them keeps naming them. A later reactivation restores the membership.

Endpoints

GET    /orgs/<space>/scim/v2/ServiceProviderConfig
GET    /orgs/<space>/scim/v2/ResourceTypes
GET    /orgs/<space>/scim/v2/Schemas
GET    /orgs/<space>/scim/v2/Users            ?filter=userName eq "x" | externalId eq "x"  &startIndex=&count=
POST   /orgs/<space>/scim/v2/Users
GET    /orgs/<space>/scim/v2/Users/<id>
PUT    /orgs/<space>/scim/v2/Users/<id>
PATCH  /orgs/<space>/scim/v2/Users/<id>
DELETE /orgs/<space>/scim/v2/Users/<id>
GET    /orgs/<space>/scim/v2/Groups           always empty

The bearer is a space token with the space's admin permission, minted under the space's Settings → Credentials. The Sigbound-Version header that every other API path requires is not required on SCIM paths: a provider speaks SCIM and nothing else. Responses are application/scim+json.

The service provider configuration declares patch and filtering supported (filters of exactly the two forms above, at most 200 results per page), and bulk, sorting, ETags and password changes unsupported. Groups are read as an empty list so a provider that syncs groups finds none rather than an error; roles are set in Sigbound.

Setup at the identity provider

  1. Mint a space token under Settings → Credentials.
  2. In the provider, create a SCIM (or "provisioning") integration with the base URL https://api.sigbound.com/orgs/<space>/scim/v2 and the token as the bearer.
  3. Map the person's email address to userName, a display name to displayName (or name.formatted, or given and family names), and the provider's own identifier to externalId.
  4. Assign the people or groups the provider should provision. The provider creates each person on first sync.

Semantics

Create

POST Users with userName (an email address), optional externalId, a display name, and active (true when absent). The account is looked up by address or created; when active, the membership is added. A second create for the same address in the same space answers 409. A userName that is not an address answers 400.

Update

PUT replaces what the provider owns: externalId, the display name, and active. PATCH accepts the operations providers send: replace or add with a value object such as {"active": false}, or with a path of active, displayName or externalId and a scalar value. userName is the person's address and is not changed through SCIM. A change from inactive to active adds the membership; a change from active to inactive removes it.

Deactivate

DELETE Users/<id> and setting active to false do the same thing: the membership is removed, the account and the space's SCIM record are kept, inactive, so a provider that re-adds the person finds them. The response to a delete is 204.

Audit

Each provisioning act is recorded in the space's audit log with the space token's account as the actor and the person as the subject:

  • organization.scim.provisioned: created, or reactivated.
  • organization.scim.updated: an attribute changed without a change of membership.
  • organization.scim.deprovisioned: deactivated or deleted.

The membership itself is added and removed through the same path as a manual change, so the usual membership records appear beside these.

Limits

  • Users only; groups are not synchronised.
  • One page holds at most 200 users; the default page is 100.
  • An installation without provisioning configured answers 501 on every Users path.