Documentation
User provisioning (SCIM)
Add people from your identity provider and remove them when they leave, over SCIM 2.0: what Ansengine accepts, and what provisioning does and does not do.
SCIM lets your identity provider add people to the workspace and, more to the point, take them out the day they leave. Ansengine implements SCIM 2.0 for users; groups are not supported. Every plan includes it. The workspace owner sets it up under Settings, Security, Automatic provisioning.
Connect your identity provider
- 1In Ansengine, open Settings, Security and choose Issue token under Automatic provisioning. Only the owner can. Copy the token when it appears: it starts scim_, it is stored hashed, and it is never shown again.
- 2Copy the Base URL from the same panel. It ends in /scim/v2.
- 3In your identity provider, turn on SCIM provisioning for the Ansengine app. Enter the base URL, and send the token as a Bearer token in the Authorization header.
- 4Turn on creating users and deactivating users. Leave group push and attribute updates off: groups answer 501, and a change to anything but active is refused or ignored, as the table below says.
- 5Push one person, then deactivate them in your provider and check they are signed out. The panel shows when your provider last called.
What the token can do
The provisioning token adds, reads, deactivates, reactivates and removes members of this workspace, and nothing else: it cannot read a measurement, spend on an engine call or publish. It is not an API key. Issuing a new token revokes the old one, and Stop provisioning revokes it outright.
What Ansengine accepts
| Request | What happens |
|---|---|
| GET /scim/v2/ServiceProviderConfig | What is supported, and it needs no token: PATCH and filtering yes, up to 200 results; bulk, sorting, ETags and password changes no. |
| GET /scim/v2/Users | The workspace's members. Pages start at 1 (startIndex) and hold up to 200 (count, 100 when not sent). The only filter accepted is userName eq "someone@yourcompany.com"; any other filter is refused with invalidFilter. |
| GET /scim/v2/Users/{id} | One member. |
| POST /scim/v2/Users | Adds a member. userName must be an email address. The name comes from displayName, else name.formatted, else givenName and familyName. active false adds them already deactivated. The role is the first entry in roles when it is admin, member or viewer; anything else becomes member, and owner is never given. A member takes a seat on your plan (a viewer takes none, up to 100 viewers); with no seat left the answer is 403, its detail says so, and nobody is added. |
| PATCH /scim/v2/Users/{id} | Sets active to true or false, sent as a replace with the value {"active": false} or as a replace on the path active. That is the only change it makes: its other operations are ignored, and a PATCH that does not set active is refused with a 400. |
| PUT /scim/v2/Users/{id} | Sets active from the body and ignores every other field. A body without active set to true or false is refused. Providers such as Okta send the whole user on an update, so the other fields are ignored rather than refused, which would fail every update. |
| DELETE /scim/v2/Users/{id} | Removes the member from the workspace. |
| /scim/v2/Groups | Answers 501: group provisioning is not implemented. |
What deactivating does
- Every session and API key the member holds stops working at once: the keys are revoked in the same step, and a key held by a deactivated member is refused anyway.
- A password sign in is refused. A sign in through your provider is refused too: no session is opened, and the page tells them their access has been turned off.
- Reactivating (active true) lets them sign in again. Their old keys stay revoked.
- The workspace owner cannot be deactivated or removed by provisioning.
What provisioning does not do
- Groups: no group push, and no roles from groups. Set roles under Settings, Team, or send one on the user when it is created.
- Renames and address changes: userName and the name are read only when a member is created.
- Passwords: a member created by provisioning has none. They sign in through single sign on, which needs their email domain verified under Settings, Security, or set a password with the reset link. Provisioning itself needs no verified domain.
- Seats: provisioning never adds a member past your plan's seats. Free a seat or change the plan, then let your provider push the person again.
- Moves between workspaces: an address that already has an Ansengine account, in this workspace or another, is answered 409 with scimType uniqueness.
Note
The audit log under Settings records each member your provider added, deactivated, reactivated or removed, as identity provider (SCIM), and each token issued or revoked.