第 14 章 使用密码库获取 secret


红帽 Keycloak 的构建目前提供了 Vault SPI 的两个开箱即用的实现:基于纯文本文件的 vault 和基于 Java KeyStore 的密码库。

要从 vault 获取 secret 而不是直接输入它,请在适当的字段中输入以下特殊调整字符串:

${vault.key}
Copy to Clipboard Toggle word wrap

其中,密钥是 vault 可识别的 secret 的名称。

为了防止 secret 在域间泄漏,红帽构建的 Keycloak 将领域名称与从 vault 表达式获取 的密钥 合并。此方法意味着 密钥 不会直接映射到密码库中的条目,而是根据用于将 密钥 与域名称组合的算法创建最终条目名称。对于基于文件的密码库,此类组合反映了特定文件名,对于基于 Java KeyStore 的库,则它是一种特定的别名名称。

您可以在以下字段从 vault 获取 secret:

SMTP 密码
在域 SMTP 设置中
LDAP 绑定凭证
在基于 LDAP 的用户联邦的 LDAP 设置中。
OIDC 身份提供程序 secret
在身份提供程序 OpenID Connect Config中的 Client Secret

14.1. 密钥解析器

所有内置供应商都支持关键解析器的配置。密钥解析器实施算法或策略,将域名称与从 ${vault.key} 表达式获取的键组合到用于从密码库检索 secret 的最终条目名称。Red Hat build of Keycloak 使用 keyResolvers 属性来配置供应商使用的解析器。该值是一个以逗号分隔的解析器名称列表。files-plaintext 供应商配置示例如下:

kc.[sh|bat] start --spi-vault-file-key-resolvers=REALM_UNDERSCORE_KEY,KEY_ONLY
Copy to Clipboard Toggle word wrap

解析器按照您在配置中声明的顺序运行。对于每个解析器,红帽构建的 Keycloak 使用解析器生成的最后一个条目名称,它将 realm 与 vault 键相结合来搜索 vault 的 secret。如果红帽构建的 Keycloak 找到 secret,它会返回 secret。如果没有,红帽构建的 Keycloak 将使用下一个解析器。这个搜索将继续,直到红帽构建的 Keycloak 找到非空 secret 或没有解析器运行。如果红帽构建的 Keycloak 没有找到 secret,红帽构建的 Keycloak 会返回一个空的 secret。

在上例中,红帽构建的 Keycloak 首先使用 REALM_UNDERSCORE_KEY 解析器。如果红帽构建的 Keycloak 在使用该解析器的 vault 中有一个条目,则红帽构建的 Keycloak 会返回该条目。如果没有,红帽构建的 Keycloak 会再次使用 KEY_ONLY 解析器进行搜索。如果红帽构建的 Keycloak 使用 KEY_ONLY 解析器查找条目,红帽构建的 Keycloak 会返回该条目。如果红帽构建的 Keycloak 使用所有解析器,Red Hat build of Keycloak 会返回空 secret。

当前可用的解析器列表如下:

Expand
Name描述

KEY_ONLY

Red Hat build of Keycloak 忽略 realm 名称,并使用 vault 表达式中的密钥。红帽构建的 Keycloak 转义在键中用另一个下划线字符出现下划线。例如,如果密钥名为 my_secret,红帽构建的 Keycloak 会在名为 my__secret 的 vault 中搜索条目。这是为了防止与默认的 REALM_UNDERSCORE_KEY 解析器冲突。

REALM_UNDERSCORE_KEY

红帽构建的 Keycloak 使用下划线字符组合了 realm 和 key。红帽构建的 Keycloak 转义在 realm 或 key 中用另一个下划线字符发生。例如,如果域名为 master_realm,并且密钥是 smtp_key,则组合键为 master__realm_smtp_key

REALM_FILESEPARATOR_KEY

红帽构建的 Keycloak 使用平台文件分隔符字符组合了 realm 和 key。vault 表达式禁止使用可能会导致路径遍历的字符,从而防止访问对应域之外的 secret。

如果您还没有为内置提供程序配置解析器,红帽构建的 Keycloak 选择 REALM_UNDERSCORE_KEY

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

Theme

© 2025 Red Hat