配置受信任的证书

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

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

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

配置系统信任库

现有的 Java 默认信任库证书将始终被信任。如果需要额外的证书,例如您有自签名或内部证书颁发机构,而 JRE 无法识别它们,则可以将它们包含在 conf/truststores 目录或子目录中。证书可以是 PEM 文件,也可以是扩展名为 .p12.pfx.pkcs12 的 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 安全连接,LDAP 安全连接需要严格的主机名检查。

相关选项

tls-hostname-verifier

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

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

STRICT 和 WILDCARD 已被弃用,请改用 DEFAULT。 已弃用值: STRICT, WILDCARD

ANY, WILDCARD (已弃用), STRICT (已弃用), DEFAULT (默认)

truststore-paths

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

CLI: --truststore-paths
Env: KC_TRUSTSTORE_PATHS

在此页中