bin/kc.[sh|bat] build --vault=fileKeycloak provides two out-of-the-box implementations of the Vault SPI: a plain-text file-based vault and Java KeyStore-based vault.
The file-based vault implementation is especially useful for Kubernetes/OpenShift secrets. You can mount Kubernetes secrets into the Keycloak Container, and the data fields will be available in the mounted folder with a flat-file structure.
The Java KeyStore-based vault implementation is useful for storing secrets in bare metal installations. You can use the KeyStore vault, which is encrypted using a password.
Secrets stored in the vaults can be used at the following places of the Administration Console:
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
For enabling the file-based vault you need to build Keycloak first using the following build option:
bin/kc.[sh|bat] build --vault=fileAnalogically, for the Java KeyStore-based you need to specify the following build option:
bin/kc.[sh|bat] build --vault=keystoreIn order to use the Java KeyStore-based vault, you need to create a KeyStore file first. You can use the following command for doing so:
keytool -importpass -alias <realm-name>_<alias> -keystore keystore.p12 -storepass keystorepasswordand then enter a value you want to store in the vault. Note that the format of the -alias parameter depends on the key resolver used. The default key resolver is REALM_UNDERSCORE_KEY.
This by default results to storing the value in a form of generic PBEKey (password based encryption) within SecretKeyEntry.
You can then start Keycloak using the following runtime options:
bin/kc.[sh|bat] start --vault-file=/path/to/keystore.p12 --vault-pass=<value> --vault-type=<value>Note that the --vault-type parameter is optional and defaults to PKCS12.
Secrets stored in the vault can then be accessed in a realm via the following placeholder (assuming using the REALM_UNDERSCORE_KEY key resolver): ${vault.realm-name_alias}.
To process the secret correctly, you double all underscores in the <secretname>. When REALM_UNDERSCORE_KEY key resolver is used, underscores in <realmname> are also doubled and <secretname> and <realmname> is separated by a single underscore.
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.
To learn more about key resolvers, see the Key resolvers chapter in the Server Administration guide.
A realm named secrettest
A desired Name ldapBc for the bind Credential
Resulting file name: secrettest_ldapBc
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.