Provision Vault identities with SCIM

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

Vault exposes SCIM through the identity secrets engine.

• SCIM users map to Vault entities.
• When you configure alias_mount_accessor, SCIM users also create mount-bound entity aliases.
• SCIM groups map to Vault internal identity groups.
• A SCIM client can manage only the users and groups it owns.
• SCIM does not manage Vault policies.

The SCIM interface is a thin wrapper over the standard Vault identity APIs. SCIM requests use the same request serialization and write to the same identity store as other identity requests. Configure rate limits for the SCIM client and its identity provider (IdP) so a provisioning burst cannot overload the identity store.

Before you start

• You must have Vault Enterprise 2.x.x or later.
• You must have permissions to enable auth methods and manage identity resources.
• You should know the auth method you want to use for the SCIM client.

Any Vault auth method can work for SCIM if authentication resolves to the Vault entity configured as the access grant principal (access_grant_principal) for the SCIM client.

Some SCIM clients only support a static bearer token. In those cases, token auth usually gives you the simplest setup because you can mint a token tied to an entity alias and pass that token directly to the connector.

SCIM endpoints and namespaces

Vault exposes SCIM endpoints under the following endpoints:

• /v1/identity/scim/v2: SCIM base path for /Users, /Groups, /ServiceProviderConfig, /Schemas and /ResourceTypes.
• /v1/identity/scim/client (and /clients): management of Vault SCIM clients.

If you use Vault Enterprise namespaces, you can address SCIM in either of these ways:

• Put the namespace in the request path, such as /v1/admin/identity/scim/v2/Users.
• Use the standard Vault namespace header with the non-namespaced path.

Configure a SCIM client

Create a SCIM client before you send SCIM protocol requests.

Each SCIM client represents one external provisioning system. The SCIM client configuration consists of these fields:

• client_name (part of the URL): Namespace-scoped name for the external system.
• access_grant_principal: ID of the Vault entity that authorizes SCIM API requests for that client.
• alias_mount_accessor: Optional auth mount accessor. When set, Vault also creates a mount-bound entity alias for each SCIM user.
• default_schema_version: Optional Vault extension schema version. New clients default to 2.2. Set this to 2.0 to keep using the original extension for backward compatibility. Clients created before this option was introduced continue to use 2.0.
• allow_user_adoption and allow_group_adoption: Optional flags that allow the client to adopt eligible existing entities and groups. Both default to false.
• max_active_tokens and max_token_ttl: Limits for scim tokens. max_active_tokens defaults to 2, and max_token_ttl of 0 uses the cluster default.

Vault enforces these rules:

• access_grant_principal must refer to an existing entity in the same namespace.
• alias_mount_accessor, when set, must refer to an existing non-local auth mount in the same namespace.
• alias_mount_accessor is immutable after creation.
• A SCIM client can manage only the users and groups it owns.

Vault limits alias_mount_accessor to non-local auth mounts.

Extension schemas and compatibility

Vault supports the following Vault-specific SCIM extension schemas:

The 2.2 schemas evolve additively. Vault introduces another schema version only when it must make an incompatible change to an existing attribute.

The deprecated 2.0 metadata schema remains supported so existing connectors that were built against it keep working. Do not include it with the 2.2 User extension in the same request. When a request includes either extension block, its schema URI must also be present in the request's schemas array. Vault rejects undeclared extension blocks and requests that include both User extensions.

Each SCIM client determines its own extension schema version through default_schema_version, so different clients in the same namespace can use different versions. Vault uses that client's version for every request it makes, unless the request declares an extension schema itself.

When you omit default_schema_version, newly created clients return 2.2 extensions and clients created before this setting return 2.0 metadata for backward compatibility. Set the client default to 2.0 if a connector still depends on the original extension.

The 2.2 User extension supports the following behavior:

• entityName lets a client with alias_mount_accessor keep the entity name separate from userName. Without a primary alias mount, Vault requires the entity name to match userName.
• aliases manages secondary entity aliases. Each entry includes mount_accessor and name. An omitted array preserves managed secondary aliases; an empty array removes them. Vault never removes unmanaged aliases.
• metadata maps key–value pairs to entity metadata. An omitted value on update preserves metadata; an empty array clears it.

The 2.2 Group extension maps metadata to group metadata. An omitted metadata value preserves metadata and an empty array clears it.

Authentication model

A SCIM client authenticates to Vault through a supported auth method, gets 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:

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

Vault rejects SCIM requests if the token does not resolve to the configured entity or the entity does not have an associated SCIM client.

Simple bearer-token setup

The following example uses the token auth method because it is easy to connect to SCIM products that expect a static bearer token. But you can use any auth method that maps back to the configured entity for the SCIM client.

1. Create a policy for the SCIM client token

$ vault policy write scim-client - <<'EOF'
path "identity/scim/v2/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}
EOF

2. Create the Vault entity for the SCIM client

$ vault write -format=json identity/entity name="scim-client"

Save the returned entity ID.

3. Create the SCIM client configuration

$ vault write identity/scim/client/example-client \
    access_grant_principal="<entity_id>"

If you want Vault to create aliases for provisioned users as well, include the alias_mount_accessor parameter. For example:

4. Create an entity alias on the token auth mount

List auth mounts and record the accessor for token/.

$ vault auth list

Create an alias on that mount for the SCIM client entity.

$ vault write identity/entity-alias \
    name="example-client" \
    mount_accessor="<token_mount_accessor>" \
    canonical_id="<entity_id>"

5. Create a token role and mint a bearer token

$ vault write auth/token/roles/example-scim \
    allowed_entity_aliases="example-client" \
    orphan=true \
    token_no_default_policy=true

$ vault token create \
    -role=example-scim \
    -entity-alias=example-client \
    -policy=scim-client \
    -type=scim \
    -orphan \
    -no-default-policy

Use the returned token value as the bearer token for SCIM requests.

We strongly recommend planning token renewal or rotation around the TTL configured on your token auth mount.

SCIM token type

Use token_type=scim when you issue a static token for a SCIM client. A SCIM token is associated with the entity that represents the client and Vault limits it using that client's max_active_tokens and max_token_ttl settings.

SCIM tokens must be non-renewable orphan tokens. Vault rejects an issuance request when the effective entity is not a SCIM client's access_grant_principal, the requested TTL exceeds max_token_ttl, or the client has reached its active-token limit. Revoke an existing token before you issue another token when the limit is reached.

Vault restricts a SCIM token to a fixed set of paths: the SCIM protocol endpoints under identity/scim/v2, and its own auth/token/lookup-self, auth/token/renew-self, auth/token/revoke-self, and sys/capabilities-self. Vault rejects requests to any other path with that token, so you cannot use a SCIM token for general Vault API calls.

Send SCIM requests

Use the Vault token in the request header to call the SCIM endpoint:

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --header "Content-Type: application/scim+json" \
    ${VAULT_ADDR}/v1/identity/scim/v2/ServiceProviderConfig

How Vault maps SCIM resources

Important behavior:

• externalId is optional when you create a SCIM user.
• externalId stays fixed after creation and does not need to be unique within a namespace.
• Group members must reference Vault user resource IDs.
• 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.

Adopt, link, and unlink resources

Use adoption and linking only when you need to bring existing Vault identity resources under SCIM management.

• To adopt an entity through POST /Users, set allow_user_adoption=true on the client. Vault can adopt an unmanaged entity when userName matches an existing login alias.
• To adopt a group through SCIM, set allow_group_adoption=true and use a PUT or PATCH request for an eligible unmanaged group. POST creates a new group and does not adopt an existing group.
• Use the administrative link-entity or link-group endpoints to associate an existing unmanaged entity or group with a SCIM client. All members of a linked group must already belong to that client.
• Use unlink-entity or unlink-group to remove a client's ownership without deleting the resource. Unlinking an entity clears its externalId and can require confirmation to make secondary aliases unmanaged or remove group memberships.

When allow_group_adoption is true, a SCIM client can see unmanaged groups. Vault filters each group's members to users owned by the requesting client. The client can adopt an eligible group with PUT or PATCH.

After you link or adopt a resource, the owning SCIM client controls its SCIM-managed fields. You cannot move a managed resource to a different SCIM client. Vault also rejects identity-entity merge requests that involve SCIM-managed entities.

Supported protocol surface

Vault supports these SCIM areas:

• 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.

Current 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.
• Vault supports limited filtering on list endpoints.
  • /Users supports eq for userName, externalId, and active.
  • /Users and /Groups support gt, ge, lt, and le for meta.lastModified.
  • /Groups supports eq for displayName.
• Vault does not support arbitrary SCIM filter expressions beyond those documented fields and operators.
• Group members must use Vault user resource IDs, not userName or externalId.
• externalId is optional when you create a user. If provided, you cannot update it later through SCIM or normal identity API writes while the entity is SCIM-managed. Multiple users may share the same externalId value.
• User groups only shows direct memberships in groups managed by the same SCIM client.
• alias_mount_accessor is immutable after client creation and remains tied to the auth mount strategy you choose for that client.

Deleting a SCIM client

Deleting a SCIM client with managed resources requires an explicit cleanup strategy. This requirement is a breaking change from the initial beta behavior, which deleted linked resources automatically.

Use delete-linked-resources=true to delete the owned entities, aliases, and groups, or use unlink-resources=true to preserve them and remove their SCIM association. These options are mutually exclusive. Include the option as an explicit query string when you call the HTTP API:

$ curl \
    --request DELETE \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    "${VAULT_ADDR}/v1/identity/scim/client/example-client?unlink-resources=true"

Vault blocks new requests for the client and completes the selected cleanup in the background. Review the resources owned by a client before you choose a strategy.

Migrate from the initial beta

When you upgrade an existing beta deployment:

1. Update SCIM clients that use the deprecated metadata extension to declare urn:ietf:params:scim:schemas:extension:vault:2.0:Metadata in every request that includes its extension block. Migrate to the 2.2 User extension when your IdP supports it.
2. Do not send the 2.0 metadata and 2.2 User extension schemas together.
3. Review every client-deletion automation. Add exactly one of delete-linked-resources=true or unlink-resources=true when the client owns resources.
4. Review SCIM client names for case-only duplicates. Vault treats client names as case-insensitive.
5. Configure default_schema_version explicitly when a connector requires a stable response schema.
6. Stop using identity/entity/merge for SCIM-managed entities. Vault rejects those requests to preserve SCIM ownership boundaries.

Related documentation

• Identity concepts
• Identity secrets engine
• SCIM API