配置受信任证书

如何配置 Keycloak 信任库以通过 TLS 进行通信。

当 Keycloak 与外部服务通信或通过 TLS 接收传入连接时,它必须验证远程证书以确保它连接到受信任的服务器。这是为了防止中间人攻击。

这些客户端或服务器的证书,或签署这些证书的 CA,必须放在信任库中。然后将此信任库配置为 Keycloak 使用。

配置系统信任库

现有的 Java 默认信任库证书将始终被信任。如果您需要其他证书(如果您有自签名或内部证书颁发机构未被 JRE 识别,则会出现这种情况),则可以将它们包含在 conf/truststores 目录或子目录中。证书可以是 PEM 文件,也可以是扩展名为 .p12.pfx 的 PKCS12 文件。如果为 PKCS12,证书必须未加密 - 意味着不需要密码。

如果您需要替代路径,请使用 --truststore-paths 选项来指定包含 PEM 或 PKCS12 文件的附加文件或目录。路径相对于您启动 Keycloak 的位置,因此建议使用绝对路径。如果指定目录,它将被递归扫描以查找信任库文件。

包含所有适用的证书后,信任库将通过 javax.net.ssl 属性用作系统默认信任库,并用作 Keycloak 内部使用的默认值。

例如

bin/kc.[sh|bat] start --truststore-paths=/opt/truststore/myTrustStore.pfx,/opt/other-truststore/myOtherTrustStore.pem

仍然可以直接设置您自己的 javax.net.ssl 信任库系统属性,但建议改为使用 --truststore-paths

主机名验证策略

您可以使用 tls-hostname-verifier 属性来细化 TLS 连接如何验证主机名。

  • DEFAULT(默认值)允许子域名称中的通配符(例如 *.foo.com)与具有相同级别数量的名称匹配(例如 a.foo.com,但不包括 a.b.foo.com) - 规则和排除规则适用于基于 https://publicsuffix.org/list/ 的公共后缀

  • ANY 意味着主机名未经验证。

  • WILDCARD(已弃用)允许子域名称中的通配符(例如 *.foo.com)匹配任何内容,包括多个级别(例如 a.b.foo.com)。改为使用 DEFAULT。

  • STRICT(已弃用)允许子域名称中的通配符(例如 *.foo.com)与具有相同级别数量的名称匹配(例如 a.foo.com,但不包括 a.b.foo.com) - 有一些有限的排除。改为使用 DEFAULT。

    请注意,此设置不适用于 LDAP 安全连接,这些连接需要严格的主机名检查。

相关选项

tls-hostname-verifier

用于传出 HTTPS 和 SMTP 请求的 TLS 主机名验证策略。

CLI: --tls-hostname-verifier
Env: KC_TLS_HOSTNAME_VERIFIER

STRICT 和 WILDCARD 已被弃用,请改为使用 DEFAULT。已弃用的值:WILDCARDSTRICT

ANYWILDCARDSTRICTDEFAULT(默认值)

truststore-paths

pkcs12(p12 或 pfx 文件扩展名)、PEM 文件或包含这些文件的目录列表,这些文件将用作系统信任库。

CLI: --truststore-paths
Env: KC_TRUSTSTORE_PATHS

在本页上