Using a vault to obtain secrets

To obtain a secret from a vault rather than entering it directly, enter the following specially crafted string into the appropriate field:

**${vault.**_key_**}**

where the key is the name of the secret recognized by the vault.

To prevent secrets from leaking across realms, Keycloak combines the realm name with the key obtained from the vault expression. This method means that the key does not directly map to an entry in the vault but creates the final entry name according to the algorithm used to combine the key with the realm name.

You can obtain the secret from the vault in the following fields:

SMTP password

In the realm SMTP settings

LDAP bind credential

In the LDAP settings of LDAP-based user federation.

OIDC identity provider secret

In the Client Secret inside identity provider OpenID Connect Config

Key resolvers

All built-in providers support the configuration of key resolvers. A key resolver implements the algorithm or strategy for combining the realm name with the key, obtained from the ${vault.key} expression, into the final entry name used to retrieve the secret from the vault. Keycloak uses the keyResolvers property to configure the resolvers that the provider uses. The value is a comma-separated list of resolver names. An example of the configuration for the files-plaintext provider follows:

kc.[sh.bat] start --spi-vault-file-key-resolvers=REALM_UNDERSCORE_KEY,KEY_ONLY

The resolvers run in the same order you declare them in the configuration. For each resolver, Keycloak uses the last entry name the resolver produces, which combines the realm with the vault key to search for the vault’s secret. If Keycloak finds a secret, it returns the secret. If not, Keycloak uses the next resolver. This search continues until Keycloak finds a non-empty secret or runs out of resolvers. If Keycloak finds no secret, Keycloak returns an empty secret.

In the previous example, Keycloak uses the REALM_UNDERSCORE_KEY resolver first. If Keycloak finds an entry in the vault that using that resolver, Keycloak returns that entry. If not, Keycloak searches again using the KEY_ONLY resolver. If Keycloak finds an entry by using the KEY_ONLY resolver, Keycloak returns that entry. If Keycloak uses all resolvers, Keycloak returns an empty secret.

A list of the currently available resolvers follows:

Name Description

KEY_ONLY

Keycloak ignores the realm name and uses the key from the vault expression.

REALM_UNDERSCORE_KEY

Keycloak combines the realm and key by using an underscore character. Keycloak escapes occurrences of underscores in the realm or key with another underscore character. For example, if the realm is called master_realm and the key is smtp_key, the combined key is master__realm_smtp__key.

REALM_FILESEPARATOR_KEY

Keycloak combines the realm and key by using the platform file separator character.

FACTORY_PROVIDED

Keycloak combines the realm and key by using the vault provider factory’s VaultKeyResolver, allowing the creation of a custom key resolver by extending an existing factory and implementing the getFactoryResolver method.

If you have not configured a resolver for the built-in providers, Keycloak selects the REALM_UNDERSCORE_KEY.