Skip to content

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:

Authorization: Bearer <scim-token>

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.

  1. Open Integration → Provisioning → SCIM and issue a SCIM token for the realm.
  2. Copy the token into your HR system or IdP's provisioning connector as the bearer credential.
  3. Point the connector at the realm's SCIM base URL, /realms/{realm}/scim/v2.
  4. 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 invalidValue otherwise). 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 is 409 uniqueness and nothing is linked (a realm administrator resolves the account). The membership records provisionedBy: 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 response detail) while the membership part of the request still applies.
  • Groups are the organization's units. The enterprise extension department puts a user in the department unit of that name (created if missing, skipped once the organization holds 1000 units), and manager sets the manager link. A SCIM client cannot grant roles through units.
  • DELETE or active=false removes 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=true never 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.

See also