Using Kubernetes secrets

Keycloak supports a file-based vault implementation for Kubernetes/OpenShift secrets. Mount Kubernetes secrets into the Keycloak Container, and the data fields will be available in the mounted folder with a flat-file structure.

Available integrations

You can use Kubernetes/OpenShift secrets for the following purposes:

  • Obtain the SMTP Mail server Password

  • Obtain the LDAP Bind Credential when using LDAP-based User Federation

  • Obtain the OIDC identity providers Client Secret when integrating external identity providers

Enabling the vault

Enable the file based vault by building Keycloak using the following build option:

bin/kc.[sh|bat] build --vault=file

Setting the base directory to lookup secrets

Kubernetes/OpenShift secrets are basically mounted files. To configure a directory where these files should be mounted, enter this command:

bin/kc.[sh|bat] start --vault-dir=/my/path

Realm-specific secret files

Kubernetes/OpenShift Secrets are used on a per-realm basis in Keycloak, which requires a naming convention for the file in place:

${vault.<realmname>_<secretname>}

Using underscores in the Name

To process the secret correctly, you double all underscores in the <realmname> or the <secretname>, separated by a single underscore.

Example

  • Realm Name: sso_realm

  • Desired Name: ldap_credential

  • Resulting file Name:

sso__realm_ldap__credential

Note the doubled underscores between sso and realm and also between ldap and credential.

Example: Use an LDAP bind credential secret in the Admin Console

Example setup

  • A realm named secrettest

  • A desired Name ldapBc for the bind Credential

  • Resulting file name: secrettest_ldapBc

Usage in Admin Console

You can then use this secret from the Admin Console by using ${vault.ldapBc} as the value for the Bind Credential when configuring your LDAP User federation.

Relevant options

Type Default

vault

Enables a vault provider.

CLI: --vault

Env: KC_VAULT

file, hashicorp

vault-dir

If set, secrets can be obtained by reading the content of files within the given directory.

CLI: --vault-dir

Env: KC_VAULT_DIR