Configure SCIM provisioning

Use System for Cross-domain Identity Management (SCIM) to provision directory users, groups, memberships, and deactivation from your identity provider. Stacklok Enterprise implements SCIM 2.0 (RFC 7644) as a service provider.

SCIM records display their source in the console. Update these records in the identity provider.

Declare the issuer first

Add the provider under directory.issuers in the platform chart and create a Secret containing a random bearer token:

kubectl create secret generic directory-scim-token-okta \
  -n <NAMESPACE> \
  --from-literal=token="$(openssl rand -base64 32)"

Declare the issuer:

values.yaml

directory:
  # Absolute base URL for the SCIM endpoints. Set this whenever any issuer is
  # configured: some providers reject relative URLs.
  scimExternalBaseURL: 'https://<PLATFORM_HOST>'
  issuers:
    - id: 'okta-prod'
      issuer_url: 'https://<TENANT>.okta.com'
      audience: 'enterprise-manager'
      binding_claim: 'uid'
      scim_bearer_token_ref:
        namespace: '<NAMESPACE>'
        name: 'directory-scim-token-okta'
        key: 'token'

Field	Value
id	A short name you choose. It becomes a path segment, so keep it URL-safe
issuer_url	Your provider's OIDC discovery base URL, HTTPS only
audience	The audience your provider puts in admin tokens
binding_claim	The claim carrying the stable per-user identifier: uid for Okta, oid for Entra
scim_bearer_token_ref	The Secret you just created

provisioning_attribute is optional and defaults to externalId, the SCIM attribute whose value must match binding_claim. Change it only if your provider carries that identifier somewhere else.

The endpoint

The issuer's id determines its base URL:

https://<PLATFORM_HOST>/scim/<ISSUER_ID>/v2

Configure the identity provider with this base URL and the bearer token from the Secret. Standard discovery endpoints and the /Users and /Groups collections are available beneath the base path.

Give each additional provider its own issuers entry, id, and Secret.

What is supported

Capability	Supported	Notes
Users and Groups	Yes	Create, read, replace, delete
PATCH	Yes	Add, replace, and remove operations
Filtering	Yes	Up to 200 results per request
Sorting	Yes	sortBy and sortOrder
Bulk operations	No	Returns not-implemented; providers fall back to individual requests
ETags	No
Password change	No	Credentials stay with your identity provider

Providers read these capabilities from /ServiceProviderConfig. Large initial syncs use individual requests because the service does not support SCIM bulk operations.

How records are matched

The directory matches a user by external identifier and issuer. Use a stable provider identifier so email or name changes update the existing record.

Group membership can reference both users and other groups, so a nested group structure in your provider arrives as subgroups here.

Set it up

1. Declare the issuer and create its token Secret, then upgrade the release so the endpoint exists.
2. Create the SCIM application, or enable provisioning on your existing single-sign-on application, in your identity provider.
3. Set the base URL to https://<PLATFORM_HOST>/scim/<ISSUER_ID>/v2, using the id you chose.
4. Supply the same bearer token you put in the Secret.
5. Enable user provisioning and deactivation, then group provisioning.
6. Push an initial sync, then confirm in the console under User management that users and groups appear with a SCIM source.

Start with a small test group to validate mappings before a full sync.

After provisioning

Connector grants and budgets reference the provisioned directory groups. Define a stable naming convention before rollout and update references after renaming a group.

If you use cluster authorization policy, align SCIM directory groups with the OIDC group claims used in policy. See Directory groups and OIDC claim groups.

Next steps

• Users and groups for what these records govern.
• Identity providers to configure upstream OAuth for connectors.

Troubleshooting

Your provider cannot authenticate

Confirm that the token matches the Secret named in scim_bearer_token_ref. Check the Secret namespace and remove trailing newlines from the value.

The endpoint is not found

Use the issuer id from directory.issuers in the path and confirm that the release includes your updated values.

Users are provisioned but groups are missing

Enable group provisioning after the initial user sync.

User deactivation does not take effect

Configure the provider to send deactivation.

Duplicate users appear

Check whether the external identifier changed in the provider. Reconcile the records there, then resync.