<#import "/templates/guide.adoc" as tmpl>
<#import "/templates/kc.adoc" as kc>

<@tmpl.guide
title="Using Kubernetes secrets"
summary="Learn how to use Kubernetes/OpenShift secrets in Keycloak"
priority=30
includedOptions="vault vault-*">

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:

<@kc.build parameters="--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:

<@kc.start parameters="--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:
[source, bash]
----
${r"${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:
[source, bash]
----
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 `${r"${vault.ldapBc}"}` as the value for the `Bind Credential` when configuring your LDAP User federation.

</@tmpl.guide>
