Provision Vault identities with SCIM

Vault Enterprise supports System for Cross-domain Identity Management (SCIM) 2.0 for provisioning identity users and groups from external identity platforms.

Enterprise

Appropriate Vault Enterprise license required

Vault acts as a SCIM server by exposing SCIM through the identity secrets engine.

SCIM users map to Vault entities.
SCIM users can also create mount-bound entity aliases.
SCIM groups map to Vault internal identity groups.
A SCIM client can only read and manage the users and groups it created.
SCIM does not manage Vault policies.

Authentication model

A SCIM client authenticates to Vault through a supported auth method, receives a Vault token, and uses that token for SCIM requests. Vault infers the SCIM client identity based on the token entity.

At a high level, the workflow consists of the following steps:

Create a Vault entity to represent the SCIM client.
Bind the entity to a SCIM client with access_grant_principal.
Authenticate through an auth method that resolves to that entity.
Use the resulting Vault token for SCIM API calls.

Vault rejects SCIM requests in the following cases:

The token does not resolve to the configured entity.
The entity does not have an associated SCIM client.

Refer to Set up a Vault SCIM server for the SCIM client configuration fields.

How Vault maps SCIM resources

Vault maps SCIM resources to identity resources as follows:

SCIM resource	Vault resource	Behavior
`User`	Entity	`userName` maps to the entity name and `externalId` maps to the entity external ID.
`Group`	Internal identity group	`displayName` maps to the group name.

Vault enforces the following behavior when mapping SCIM resources:

externalId is required when you create a SCIM user.
externalId stays fixed after creation.
Group members must reference Vault user resource IDs, not userName or externalId.
A SCIM client can only add the users it owns to a group.

If the SCIM client sets alias_mount_accessor, Vault creates a mount-bound entity alias for each provisioned user and keeps the alias name aligned with the SCIM userName. You cannot change alias_mount_accessor after you create the client. It stays tied to the auth mount strategy you choose.

Supported SCIM operations

Vault supports the following SCIM operations and endpoints:

SCIM client configuration through /identity/scim/client
User create, read, list, replace, patch, and delete
Group create, read, list, replace, patch, and delete
Discovery endpoints for Schemas, ResourceTypes, and ServiceProviderConfig

Vault returns SCIM responses as application/scim+json.

Limitations

Vault does not support /Me.
Vault does not support SCIM bulk operations.
Vault does not support sort, ETag, or change password operations.
User PATCH only supports a single replace operation for active.
Group PATCH only supports member add and remove operations.
User groups only shows direct memberships in groups managed by the same SCIM client.

Supported filters

Vault supports limited filtering on list endpoints:

Endpoint	Operators	Fields
`/Users`	`eq`	`userName`, `externalId`, and `active`
`/Groups`	`eq`	`displayName`
`/Users` and `/Groups`	`gt`, `ge`, `lt`, and `le`	`meta.lastModified`

Vault does not support filter expressions beyond the documented fields and operators.