SCIM provisioning

Embed
Preview of the card
<a href="https://forumulate.com/p/watchtower/docs/scim"><img src="https://forumulate.com/api/public/orgs/watchtower/spaces/docs/pages/67f905a3-3d79-4fe4-90e2-c4764304e796/social-card.svg?v=3e7ae33eec8b" alt="SCIM provisioning" width="600" height="315"></a>

Watchtower implements a SCIM 2.0 server (RFC 7643/7644) so an identity provider can create, update and deprovision users and groups. It is outside /v1: base URL https://<host>/scim/v2, content type application/scim+json.

Setup

  1. In Settings, SCIM provisioning, create a token. The secret (wts_<prefix>_<secret>) is shown once and stored only as a SHA-256 hash. At most five live tokens per org; revoke to rotate.

  2. Give the IdP the base URL and the token as a bearer token.

  3. Optional: map groups to roles with PUT /v1/orgs/{org}/scim/group-role-mappings ([{group, role, project_id?}], group is a SCIM group id or display name).

Supported

Area

Support

Resources

Users, Groups, discovery (ServiceProviderConfig, ResourceTypes, Schemas)

Filter

eq on userName, externalId, id, displayName, joined with and

PATCH

add, replace, remove on active, name.*, displayName, emails, members; at most 100 operations

Not supported

Bulk, sort, ETag, change password; other filter operators and paths answer 400 (invalidFilter, invalidPath)

Limits

10,000 users and 5,000 groups per org, 5,000 members per group, page size 200 (tooMany, 413)

Users and sign-in

userName is the email. Create makes a user with a placeholder identity (atlas_user_id = scim:<uuid>) and an org membership with the org's JIT role. On that person's first Atlas sign-in with an email on a verified domain of the org, the placeholder is linked to the real Atlas subject. This is the only email-based link in the system and works for SCIM placeholders only.

Deprovisioning

active=false (PUT or PATCH) and DELETE run the shared deprovisioning path: sessions are revoked before the response, personal keys revoked, project roles and memberships removed, and the user is disabled with reason scim. Re-activation lifts that disable but restores no keys or memberships. Users of another org are 404.

Roles from groups

The effective org role is the highest mapped role among the user's groups (org_admin > project_admin > engineer > read_only). Mappings with a project_id set a project role. Updating the mappings applies immediately to all group members; membership changes apply at the change. An org with no mappings is untouched, and a user in no mapped group returns to the org's JIT role.

Audit

scim.token.created|revoked, scim.user.create|update|deprovision, scim.group.create|update|delete, scim.group.role_mappings.updated. Token secrets never appear.

Not covered

Enforcing 2FA or password policy needs the Atlas amr claim (gap G6-03), so SEC-006 stays in progress.

Updated