SCIM Provisioning¶
Keep users and groups in sync automatically — in from your HR system or IdP, and out to your downstream apps — over the open SCIM 2.0 standard.
What it is¶
HelixIAM is a full SCIM 2.0 server, and it provisions in both directions:
- Inbound — your HR system or upstream IdP pushes users and groups into Helix. Joiners, movers, and leavers flow through automatically.
- Outbound — Helix provisions accounts out to your downstream SCIM-capable apps, so deprovisioning a user in Helix removes their access everywhere.
Bearer auth, not admin session¶
The SCIM API is a machine-to-machine surface. Unlike the admin API (session + CSRF), it is authenticated by a per-realm SCIM token presented as a bearer token — no cookie jar, no CSRF header:
Mint the token for the realm from the console, then hand it to your provisioning source. All SCIM requests use the SCIM media type application/scim+json.
Rate limit¶
Each token (realm or organization) may make 600 requests a minute by default, counted cluster-wide (helix.scim.rate-limit.per-token-per-minute). Past it the request gets 429 in the SCIM error shape with a Retry-After header; retry after that many seconds. A refused token is logged (WARN) and audited as SCIM_RATE_LIMITED, at most once a minute per token. The audit names the token by its id (an organization token) or by a short fingerprint of its hash (the realm token), never the token itself, and names the organization for an organization token.
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
"status": "429",
"detail": "Too many requests for this SCIM token. Retry after the time in the Retry-After header."
}
In the console¶
SCIM lives under Integration → Provisioning → SCIM.
- Open Integration → Provisioning → SCIM and issue a SCIM token for the realm.
- Copy the token into your HR system or IdP's provisioning connector as the bearer credential.
- Point the connector at the realm's SCIM base URL,
/realms/{realm}/scim/v2. - Start from ServiceProviderConfig to confirm which capabilities Helix advertises, then map your source attributes.
Inbound (Helix as the SCIM server)¶
Point your provisioning source at the realm's SCIM endpoints under /realms/{realm}/scim/v2 and authenticate with the per-realm SCIM token.
Create a user¶
curl -s -X POST "$HELIX_URL/realms/$REALM/scim/v2/Users" \
-H "Authorization: Bearer $SCIM_TOKEN" \
-H "Content-Type: application/scim+json" \
-d '{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"userName": "jane@example.com",
"name": { "givenName": "Jane", "familyName": "Doe" },
"emails": [{ "value": "jane@example.com", "primary": true }],
"active": true
}'
The server responds 201 Created with the provisioned SCIM resource, including its server-assigned id — use that for subsequent read, replace, patch, and delete calls on /Users/{id}.
Bearer required
Every SCIM call must carry Authorization: Bearer <scim-token>. Requests without it are rejected with 401 Unauthorized.
Endpoints¶
Method & path (under /realms/{realm}/scim/v2) |
Purpose |
|---|---|
GET /Users · POST /Users |
List / create users |
GET · PUT · PATCH · DELETE /Users/{id} |
Read / replace / patch / deactivate a user |
GET /Groups · POST /Groups |
List / create groups |
GET · PUT · PATCH · DELETE /Groups/{id} |
Read / replace / patch / delete a group |
GET /ServiceProviderConfig |
Capabilities Helix supports |
GET /Schemas |
Resource schemas |
GET /ResourceTypes |
Available resource types |
Standards-based, vendor-neutral
Any SCIM 2.0 client works — start from ServiceProviderConfig to discover exactly what Helix supports, then map your source attributes.
Per-organization tokens¶
An organization can have its own SCIM tokens, created by its organization admins (permission org:scim) or a realm admin:
# create (the token is shown once, then only its hash is kept)
curl -s -b cookies.txt -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
-d '{"name":"Workday sync"}' \
"$HELIX_URL/admin/realms/$REALM/organizations/$ORG/scim-tokens"
# list (id, name, createdAt, lastUsedAt, revokedAt; the id is what the DELETE call needs) and revoke
curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/organizations/$ORG/scim-tokens"
curl -s -b cookies.txt -X DELETE -H "X-XSRF-TOKEN: $CSRF" \
"$HELIX_URL/admin/realms/$REALM/organizations/$ORG/scim-tokens/$TOKEN_ID"
The create response is {"id", "name", "token"}. Use token as the bearer credential on the same endpoints as the realm token (/realms/{realm}/scim/v2/...). An organization token limits every operation to that organization:
- Users are its members; a user who is not a member is not found. Creating or linking a user works only for an email address in a verified domain of the organization (
400 invalidValueotherwise). An existing account with that address is linked as a member without being changed, but only when that account has verified the address; otherwise the create is409 uniquenessand nothing is linked (a realm administrator resolves the account). The membership recordsprovisionedBy: scim:<tokenId>. - Attribute changes (address, names,
active) apply only to accounts the organization owns: an address in its verified domain, not a realm or master admin, a member of no other organization, no admin permissions. Otherwise the attribute change is ignored (named in the responsedetail) while the membership part of the request still applies. - Groups are the organization's units. The enterprise extension
departmentputs a user in the department unit of that name (created if missing, skipped once the organization holds 1000 units), andmanagersets the manager link. A SCIM client cannot grant roles through units. - DELETE or
active=falseremoves the membership. A member who holds an organization permission (org:*, through a role or a unit) cannot be removed or deactivated this way (403 mutability); the last Org admin never can. Taking a member out of a unit that grants a permission, and deleting such a unit, are refused the same way. An administrator makes those changes. The account is deactivated only when this token's membership was its last one and the organization still owns the account. active=truenever re-enables an account an administrator disabled. SCIM enables only an account that SCIM disabled (realm tokens too).
A realm token keeps its realm-wide behaviour. A token of another realm is 401.
Outbound (Helix to downstream targets)¶
Register the apps Helix should provision into as SCIM targets, managed over the admin API (session + CSRF):
Method & path (under /admin/realms/{realm}) |
Purpose |
|---|---|
GET /scim-targets · POST /scim-targets |
List / register downstream targets |
PUT · DELETE /scim-targets/{id} |
Update / remove a target |
Each target stores the downstream base URL and credentials. When a user is created, updated, or deactivated in Helix, the change is pushed to every connected target — one source of truth, consistent access everywhere.