mirror of
https://github.com/keycloak/keycloak.git
synced 2026-01-10 15:32:05 -03:30
22f0f81507
Closes: #211 Signed-off-by: Peter Zaoral <pzaoral@redhat.com> Co-authored-by: Václav Muzikář <vmuzikar@redhat.com>
91 lines
4.0 KiB
Plaintext
91 lines
4.0 KiB
Plaintext
<#import "/templates/guide.adoc" as tmpl>
|
|
<#import "/templates/kc.adoc" as kc>
|
|
|
|
<@tmpl.guide
|
|
title="Using a vault"
|
|
summary="Learn how to use and configure a vault in {project_name}"
|
|
priority=30
|
|
includedOptions="vault vault-*">
|
|
|
|
{project_name} 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 {project_name} 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.
|
|
|
|
== Available integrations
|
|
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
|
|
|
|
== Enabling a vault
|
|
For enabling the file-based vault you need to build {project_name} first using the following build option:
|
|
|
|
<@kc.build parameters="--vault=file"/>
|
|
|
|
Analogically, for the Java KeyStore-based you need to specify the following build option:
|
|
|
|
<@kc.build parameters="--vault=keystore"/>
|
|
|
|
== Configuring the file-based vault
|
|
|
|
=== 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:
|
|
|
|
<@kc.start parameters="--vault-dir=/my/path"/>
|
|
|
|
=== Realm-specific secret files
|
|
Kubernetes/OpenShift Secrets are used on a per-realm basis in {project_name}, which requires a naming convention for the file in place:
|
|
[source, bash]
|
|
----
|
|
${r"${vault.<realmname>_<secretname>}"}
|
|
----
|
|
|
|
== Configuring the Java KeyStore-based vault
|
|
|
|
In 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:
|
|
[source, bash]
|
|
----
|
|
keytool -importpass -alias <realm-name>_<alias> -keystore keystore.p12 -storepass keystorepassword
|
|
----
|
|
and 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 {project_name} using the following runtime options:
|
|
|
|
<@kc.start parameters=" --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): `${r"${vault.realm-name_alias}"}`.
|
|
|
|
== Using underscores in the secret names
|
|
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.
|
|
|
|
.Example
|
|
* Realm Name: `sso_realm`
|
|
* Desired Name: `ldap_credential`
|
|
* Resulting file name:
|
|
[source, bash]
|
|
----
|
|
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 link:{adminguide_link}#_vault-key-resolvers[Key resolvers section in the Server Administration guide].
|
|
|
|
== 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 `${r"${vault.ldapBc}"}` as the value for the `Bind Credential` when configuring your LDAP User federation.
|
|
|
|
</@tmpl.guide>
|