SCIM API

Use the SCIM API to provision Vault identity entities and internal groups from external identity systems.

The SCIM protocol endpoints are a thin wrapper over standard Vault identity resources. The SCIM protocol endpoints use the same request serialization and identity store as the normal identity APIs. Configure rate limits for your SCIM client and identity provider to protect the identity store from provisioning bursts.

Authentication and Authorization

SCIM authenticates clients using standard Vault ACL policy evaluation, but only authorizes requests where the entity ID associated with the token matches the access_grant_principal field of a SCIM client in the same namespace. Vault also uses the entity ID and access_grant_principal value to resolve the identity of the calling SCIM client.

SCIM client scope

• Vault scopes SCIM clients to a specific namespace.
• Vault considers users and groups created by a SCIM client to be managed by that SCIM client.
• When allow_group_adoption is true, SCIM clients can read unmanaged groups, but Vault filters each group's members to include only Vault entities owned by the requesting client.
• Vault admins can read SCIM-managed resources and modify fields that are not managed by SCIM.
• Only the SCIM client can delete the resource and modify SCIM-managed fields.
• Vault returns SCIM protocol responses with the application/scim+json content type.

SCIM client endpoints

Use SCIM client endpoints to define the external provisioning system that can call the SCIM protocol endpoints. You cannot change or clear alias_mount_accessor once you create a SCIM client.

Deleting a SCIM client marks it for an asynchronous cleanup workflow. When the client owns resources, you must choose whether Vault deletes or unlinks them.

Path parameters

• client_name (string: <required>) - Name of the SCIM client. The name must be unique within the namespace.

Request parameters

• access_grant_principal (string: <required>) - ID of an existing Vault entity in the same namespace. Vault uses the targeted entity to authorize SCIM protocol requests.
• alias_mount_accessor (string: <optional>) - Auth mount accessor used to create an entity alias for each SCIM user. The accessor must refer to an existing non-local auth mount in the same namespace.
• default_schema_version (string: "2.2") - Vault extension schema version for this SCIM client. Vault uses this version for the client's responses unless a request declares an extension schema. Vault continues to support the original 2.0 extension for backward compatibility; set this to 2.0 to keep using it. Clients created before this setting was introduced default to 2.0.
• allow_user_adoption (boolean: false) - Allows POST /Users to adopt an eligible unmanaged entity whose login alias matches userName.
• allow_group_adoption (boolean: false) - Allows PUT and PATCH requests to adopt eligible unmanaged groups. POST creates a new group and does not adopt an existing group.
• allowed_extra_alias_mount_accessors (array: []) - Mount accessors allowed for secondary aliases managed by this client. The primary alias_mount_accessor is always allowed and must not be included. Mounts must be non-local and in the same namespace. If no allowlist is configured, any non-local mount is allowed. On update, omitting this field preserves the current value and an empty list clears the allowlist.
• max_active_tokens (integer: 2) - Maximum active scim tokens for the client. The value must be greater than zero.
• max_token_ttl (duration: 0) - Maximum TTL for scim tokens. Set 0 to use the cluster default.

Delete query parameters

When a client owns entities or groups, include exactly one of the following query parameters on DELETE:

• delete-linked-resources=true deletes the owned entities, aliases, and groups.
• unlink-resources=true preserves the resources and removes their SCIM client association.

Vault rejects a deletion without one of these options when the client owns resources, and rejects a request that specifies both options. Cleanup runs asynchronously.

Resource linking parameters

The link and unlink endpoints take the following request parameters:

• link-entity: entity_id identifies an unmanaged entity to associate with the SCIM client. You can also provide externalId, a list of alias IDs in scim_managed_aliases, and group IDs in group_memberships. scim_managed_aliases must not include the primary alias. Vault manages the primary alias automatically. Each group must be owned by this client.
• unlink-entity: entity_id identifies an entity to remove from SCIM management. If the entity has secondary SCIM-managed aliases, set unlink_secondary_aliases=true to confirm they become unmanaged. If the entity belongs to SCIM-managed groups, set remove_memberships=true to direct Vault to remove the entity's memberships in those groups. Unlinking also clears externalId.
• link-group: group_id identifies an unmanaged group to associate with the client. Every group member must already be owned by the client.
• unlink-group: group_id identifies a group to remove from SCIM management.

Sample payload

{
  "access_grant_principal": "d8be46f8-b754-7d85-2dc6-37e15a24d7d5",
  "alias_mount_accessor": "auth_userpass_7d1d6f49",
  "default_schema_version": "2.2",
  "allow_user_adoption": true,
  "max_active_tokens": 2,
  "max_token_ttl": "1h"
}

User endpoints

Vault supports the following standard SCIM /Users endpoints:

SCIM users map to Vault entities as follows:

• id maps to the entity ID.
• userName maps to the entity name.
• externalId maps to the entity external ID.
• active maps to the inverse of the entity disabled state.
• groups is a read-only field that lists direct memberships in groups that the same SCIM client manages (the list excludes memberships in unmanaged groups).

Vault requires userName on create. externalId is optional and, if provided, is immutable after creation. Multiple users may share the same externalId value.

Vault extension schemas

Use urn:ietf:params:scim:schemas:extension:vault:2.2:User for entityName, secondary aliases, and metadata. Each alias contains mount_accessor and name; each metadata item contains key and value.

Vault also accepts the deprecated 2.0:Metadata extension for backward compatibility. Declare its schema URI in schemas when you use it, and don't combine it with the 2.2 User extension in the same request.

When a request does not declare an extension schema, Vault uses the SCIM client's default_schema_version to determine the extension version for the response.

Omitting aliases or metadata on an update preserves the existing value; send an empty array to clear it.

Supported filters

Vault supports the following filters on /Users:

Vault rejects other user filter attributes and operators.

Supported PATCH behavior

Vault only supports a single replace operation for the active field when you patch a user.

Sample create user payload

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:vault:2.2:User"
  ],
  "userName": "jane.doe",
  "externalId": "00u123456789",
  "active": true,
  "urn:ietf:params:scim:schemas:extension:vault:2.2:User": {
    "metadata": [
      {
        "key": "department",
        "value": "engineering"
      }
    ]
  }
}

Group endpoints

Vault supports the following standard SCIM /Groups endpoints:

SCIM groups map to Vault internal identity groups as follows:

• id maps to the group ID.
• displayName maps to the group name.
• members[].value must contain Vault user entity IDs.

Each SCIM client only works with members it owns. You cannot add groups as members to other groups.

Use urn:ietf:params:scim:schemas:extension:vault:2.2:Group to manage group metadata. Metadata is an array of key and value objects. Omit metadata on an update to preserve it or send an empty array to clear it.

When a request does not declare the Group extension schema, Vault uses the client's default_schema_version. For clients configured with the 2.2 default, group metadata is SCIM-managed and cannot be changed through the normal Vault identity API.

Supported filters

Vault supports the following filters on /Groups:

Vault rejects other group filter attributes and operators.

Supported PATCH behavior

Vault limits PATCH support to adding and removing group members for an existing group. Any other group patch operation fails.

Sample create group payload

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:Group"
  ],
  "displayName": "vault-admins",
  "members": [
    {
      "value": "2cc3c936-fb4e-4635-b213-9cf55b87f2d4"
    }
  ]
}

Discovery endpoints

Vault supports the following standard SCIM discovery endpoints:

Clients can call /identity/scim/v2/ServiceProviderConfig without authentication.

Vault also declares /identity/scim/v2/Me, but the endpoint returns 501 Not Implemented.

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 does not support arbitrary SCIM filter expressions beyond the documented fields and operators for /Users and /Groups.
• Group members must use Vault user entity IDs, not userName or externalId.
• externalId is optional when you create a user. If provided, it cannot be updated later through SCIM, and normal identity API writes also cannot change the external ID of a SCIM-managed entity. 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.
• alias_mount_accessor cannot refer to a local mount, only non-local ones.
• You cannot manage existing resources with a SCIM client.
• You cannot move a managed resource between SCIM clients.
• Only eligible unmanaged resources can be adopted or linked.

SCIM token type

Use token_type=scim to issue a token for a SCIM client's access-grant principal. SCIM tokens must be non-renewable orphan tokens. Vault enforces the client's max_active_tokens and max_token_ttl values when it issues the token.

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.