
:guide-id: vault
:guide-title: Using a vault
:guide-summary: Learn how to use and configure a vault in {project_name}
:guide-priority: 999
:guide-tile-visible: true
:version: 26.2.2

include::../attributes.adoc[]

[[vault]]
= Using a vault

ifeval::["" == "true"]
WARNING: This {section} is describing a feature which is currently in preview.
ifeval::["" == ""]
Please provide your feedback while we’re continuing to work on this.
endif::[]
ifeval::["" != ""]
Please provide your feedback by link:[joining this discussion] while we’re continuing to work on this.
endif::[]
endif::[]


{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:

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

Analogically, for the Java KeyStore-based you need to specify the following build option:

[source,bash]
----
bin/kc.[sh|bat] build --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:

[source,bash]
----
bin/kc.[sh|bat] start --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]
----
${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:

[source,bash]
----
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}`.

== 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 `${vault.ldapBc}` as the value for the `Bind Credential` when configuring your LDAP User federation.


== Relevant options

[cols="12a,4",role="options"]
|===
| |Value

|
[.options-key]#``vault``# [.none]#icon:tools[role=options-build]#

[.options-description]#Enables a vault provider.#

[role="options-extended"]
--


*CLI:* `--vault` +
*Env:* `KC_VAULT`
--



|
`+file+`, `+keystore+`

|
[.options-key]#``vault-dir``# 

[.options-description]#If set, secrets can be obtained by reading the content of files within the given directory.#

[role="options-extended"]
--


*CLI:* `--vault-dir` +
*Env:* `KC_VAULT_DIR`
--



|

|
[.options-key]#``vault-file``# 

[.options-description]#Path to the keystore file.#

[role="options-extended"]
--


*CLI:* `--vault-file` +
*Env:* `KC_VAULT_FILE`
--



|

|
[.options-key]#``vault-pass``# 

[.options-description]#Password for the vault keystore.#

[role="options-extended"]
--


*CLI:* `--vault-pass` +
*Env:* `KC_VAULT_PASS`
--



|

|
[.options-key]#``vault-type``# 

[.options-description]#Specifies the type of the keystore file.#

[role="options-extended"]
--


*CLI:* `--vault-type` +
*Env:* `KC_VAULT_TYPE`
--



|[.options-default]#`+PKCS12+`# (default)


|===
