使用 Vault

了解如何在 Keycloak 中使用和配置 Vault

Keycloak 提供了 Vault SPI 的两个开箱即用的实现：基于纯文本文件的 Vault 和基于 Java KeyStore 的 Vault。

基于文件的 Vault 实现对于 Kubernetes/OpenShift 密钥尤其有用。您可以将 Kubernetes 密钥挂载到 Keycloak 容器中，数据字段将在挂载的文件夹中以扁平文件结构提供。

基于 Java KeyStore 的 Vault 实现对于在裸机安装中存储密钥很有用。您可以使用 KeyStore Vault，它使用密码加密。

可用的集成

存储在 Vault 中的密钥可以在管理控制台的以下位置使用

要启用基于文件的 Vault，您需要首先使用以下构建选项构建 Keycloak

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

类似地，对于基于 Java KeyStore 的 Vault，您需要指定以下构建选项

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

Kubernetes/OpenShift 密钥基本上是挂载的文件。要配置这些文件应挂载到的目录，请输入以下命令

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

Kubernetes/OpenShift 密钥在 Keycloak 中按 Realm 使用，这需要对文件进行命名约定

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

为了使用基于 Java KeyStore 的 Vault，您需要首先创建一个 KeyStore 文件。您可以使用以下命令来执行此操作

keytool -importpass -alias <realm-name>_<alias> -keystore keystore.p12 -storepass keystorepassword

然后输入您要存储在 Vault 中的值。请注意，`-alias` 参数的格式取决于所使用的密钥解析器。默认的密钥解析器是 `REALM_UNDERSCORE_KEY`。

默认情况下，这会将值以通用 PBEKey（基于密码的加密）的形式存储在 SecretKeyEntry 中。

然后，您可以使用以下运行时选项启动 Keycloak

bin/kc.[sh|bat] start  --vault-file=/path/to/keystore.p12 --vault-pass=<value> --vault-type=<value>

请注意，`--vault-type` 参数是可选的，默认为 `PKCS12`。

存储在 Vault 中的密钥随后可以通过以下占位符在 realm 中访问（假设使用 `REALM_UNDERSCORE_KEY` 密钥解析器）：`${vault.realm-name_alias}`。

为了正确处理密钥，您需要将 <secretname> 中的所有下划线加倍。当使用 `REALM_UNDERSCORE_KEY` 密钥解析器时，<realmname> 中的下划线也会加倍，并且 <secretname> 和 <realmname> 之间用单个下划线分隔。

示例

sso__realm_ldap__credential

请注意 *sso* 和 *realm* 之间以及 *ldap* 和 *credential* 之间的双下划线。

要了解有关密钥解析器的更多信息，请参阅服务器管理指南中的密钥解析器部分。

示例设置

在管理控制台中的用法

然后，您可以在管理控制台中使用此密钥，方法是在配置 LDAP 用户联合身份验证时，将 `${vault.ldapBc}` 用作“绑定凭据”的值。