Set up a Vault SCIM server

Enterprise

Appropriate Vault Enterprise license required

You can configure Vault Enterprise to act as a System for Cross-domain Identity Management (SCIM) server that authenticates external identities.

Before you start

Deploy a Vault Enterprise or HCP Vault Dedicated server. SCIM support requires an Enterprise license.
Create the OIDC or SAML application in your IdP You must configure an OIDC or SAML application in your IdP prior to completing the Vault setup described here. After you complete Vault setup and have a SCIM token, you can then configure provisioning.
Check your permissions. You must have admin permissions on Vault.

Enable and configure OIDC auth method

To use Vault as a SCIM server that supports external identities authenticated with an identity provider (IdP) OpenID Connect (OIDC) workflow, you must enable the OIDC auth method and create a named role on the Vault server.

Some Vault deployments do not enable the OIDC auth method by default. List the enabled auth methods, then enable OIDC when oidc/ is absent:

$ vault auth list

$ vault auth enable oidc

Tip

The following example configures the OIDC auth method and role for Access and Identity Management. Adjust the discovery URL and credential variables as needed for your IdP.

$ vault write auth/oidc/config                                              \
    oidc_discovery_url="https://${PROVIDER_DOMAIN}"                             \
    oidc_client_id="$PROVIDER_CLIENT_ID"                                        \
    oidc_client_secret="$PROVIDER_CLIENT_SECRET"                                \
    default_role="vault-role-provider-default"

The following example creates the matching OIDC auth method role.

$ vault write auth/oidc/role/vault-role-provider-default                       \
    bound_audiences="$PROVIDER_CLIENT_ID"                                      \
    allowed_redirect_uris="$VAULT_ADDR/ui/vault/auth/oidc/oidc/callback"   \
    allowed_redirect_uris="http://localhost:8250/oidc/callback"            \
    user_claim="email"                                                     \
    oidc_scopes="profile,email"                                            \
    token_policies="default,scim-client-policy"

Enable and configure SAML auth method

You can authenticate users with SAML instead of OIDC. Some IdPs, such as Okta, can provide both SAML login and SCIM provisioning from a single application. To use the SAML workflow, enable the SAML auth method and create a named role on the Vault server.

$ vault auth enable saml

Tip

The following example configures the SAML auth method for an Okta SAML application. OKTA_SAML_APP_ID is the Okta application ID, which begins with 0oa. The admin segment of the ACS URL is a namespace. Vault servers without namespaces use $VAULT_ADDR/v1/auth/saml/callback.

$ vault write auth/saml/config                                                                    \
    idp_metadata_url="https://${OKTA_DOMAIN}/app/${OKTA_SAML_APP_ID}/sso/saml/metadata"           \
    acs_urls="$VAULT_ADDR/v1/admin/auth/saml/callback"                                            \
    entity_id="$VAULT_ADDR/ui/vault/auth/saml"                                                    \
    default_role="vault-role-okta-saml"

The entity_id value must match the audience URI (SP entity ID) of the IdP application, and acs_urls must include its single sign-on URL.

The following example creates the matching SAML auth method role.

$ vault write auth/saml/role/vault-role-okta-saml                          \
    groups_attribute="groups"                                              \
    bound_subjects="*"                                                     \
    bound_subjects_type="glob"                                             \
    token_policies="default"                                               \
    token_ttl="1h"

Set bound_subjects_type to glob when bound_subjects contains *. With string matching, Vault compares * literally and no subject matches.

Vault names the entity alias for a SAML login after the assertion subject. For SCIM-provisioned users to log in to their provisioned entity, bind the SCIM client to the SAML mount with alias_mount_accessor, as described in Bind a SCIM client to an auth mount.

Configure a SCIM client

You must create a SCIM client before you send SCIM protocol requests to Vault.

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

client_name: Namespace-scoped name for the external system. The name forms part of the endpoint URL.
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.

Vault enforces these limitations and 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.

Note

A SCIM client knows about only the resources it created. Pre-existing entities remain invisible to the client unless you set allow_user_adoption to true or link the entities with the link-entity endpoint of the SCIM API.

Bind a SCIM client to an auth mount

Without alias_mount_accessor, Vault creates no auth mount alias for provisioned users. A user who later logs in through an auth method such as SAML gets a separate entity instead of the provisioned one.

To link provisioned users to SAML logins, look up the accessor of the SAML mount and pass it when you create the SCIM client:

$ SAML_ACCESSOR=$(vault auth list -format=json | jq -r '."saml/".accessor')

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

Read the client back and confirm that alias_mount_accessor matches the accessor. You cannot change the value after creation, so a client created without it, or for a different mount, must be replaced with a new client.

Create the client before users log in

Create the SCIM client and provision users before anyone logs in through the bound auth mount. A login before provisioning creates an entity that the SCIM client does not own, and the client cannot claim it without a link or user adoption.

Auth method and token caveats

Any auth method can work for SCIM if authentication resolves to the Vault entity set as the SCIM client's access_grant_principal.

Some SCIM clients support only a static bearer token. In those cases, use the token auth method. You can create a token tied to an entity alias and pass that token directly to your SCIM client.

Set up a bearer-token workflow

The following example uses the token auth method, which supports SCIM products that require a static bearer token. You can use any auth method that maps back to the configured entity for the SCIM client.

Create an access control list (ACL) policy that grants access to the SCIM API endpoints. A later step assigns the policy to the token for the SCIM client.

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

Create the Vault entity for the SCIM client.
```
$ vault write -format=json identity/entity name="scim-client"
```
Record the returned entity ID for the following step.
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. Refer to Bind a SCIM client to an auth mount.

Create an alias on the token/ mount for the SCIM client entity. List the auth mounts to find the accessor for token/:

$ vault auth list

Create the alias with the accessor you recorded:

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

Create a token role that allows the entity alias example-client, excludes the default policy, and issues orphan tokens.

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

Create a token from the token auth method. The command specifies the entity alias and the scim-client policy, and excludes the default policy.

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

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

Tip

Plan token renewal or rotation around the time to live (TTL) value configured on your token auth mount.

Send SCIM requests

The following example calls the ServiceProviderConfig endpoint with a Vault token in the request header:

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

Delete a SCIM client

When you delete a SCIM client, Vault starts an asynchronous cleanup workflow.

Vault blocks new SCIM requests for that client.
Vault removes the users and groups owned by that client.
Vault continues removing the managed resources and the SCIM client configuration in the background.

Review the resources owned by a SCIM client before you delete it.