SCIM API

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

Before you call these endpoints, activate the SCIM feature flag enable-scim through the activation flags endpoint.

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.
• 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 as deleting: true and launches an asynchronous removal of all entities, aliases and groups owned by that client.

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.

Sample payload

{
  "access_grant_principal": "d8be46f8-b754-7d85-2dc6-37e15a24d7d5",
  "alias_mount_accessor": "auth_userpass_7d1d6f49"
}

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.

Vault requires userName and externalId on create and makes externalId immutable after creation.

Supported filters

Vault supports simple eq filters on /Users for the following fields:

• userName
• externalId
• active

Vault rejects complex filter expressions and other filter 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.0:Metadata"
  ],
  "userName": "jane.doe",
  "externalId": "00u123456789",
  "active": true,
  "urn:ietf:params:scim:schemas:extension:vault:2.0:Metadata": {
    "items": [
      {
        "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.

Vault only allows SCIM clients to work with members owned by that client. You cannot add groups as members to other groups.

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

• Activating the SCIM feature flag is a one-way action.
• 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 complex eq filters on /Users for userName, externalId, or active.
• Vault does not support group filters or complex SCIM filter expressions.
• Group members must use Vault user entity IDs, not userName or externalId.
• You must provide externalId when you create a user and you cannot update it later.
• 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 migrate resources between SCIM clients.
• You cannot remove SCIM management from a resource currently managed by SCIM.