为 mTLS 配置受信任的证书

了解如何配置相互 TLS 以验证连接到 Keycloak 的客户端。

为了正确验证客户端证书并启用某些身份验证方法(如双向 TLS 或 mTLS),您可以设置一个信任存储库,其中包含服务器应信任的所有证书(和证书链)。许多功能都依赖于此信任存储库来正确地使用证书对客户端进行身份验证,例如相互 TLS 和 X.509 身份验证。

启用 mTLS

默认情况下禁用使用 mTLS 的身份验证。要启用 mTLS 证书处理(当 Keycloak 作为服务器并且需要验证来自对 Keycloak 端点发出的请求的证书时),请将相应的证书放入信任存储库,并使用以下命令启用 mTLS

bin/kc.[sh|bat] start --https-client-auth=<none|request|required>

使用值 required 会将 Keycloak 设置为始终要求证书,并且如果请求中未提供证书,则会失败。通过将值设置为 request,Keycloak 也将接受没有证书的请求,并且仅在证书存在时验证证书的正确性。

mTLS 配置和信任存储库由所有 Realm 共享。无法为不同的 Realm 配置不同的信任存储库。
管理界面属性继承自主 HTTP 服务器,包括 mTLS 设置。这意味着当设置 mTLS 时,它也会为管理界面启用。要覆盖此行为,请使用 https-management-client-auth 属性。

为 mTLS 使用专用信任存储库

默认情况下,Keycloak 使用系统信任存储库来验证证书。有关详细信息,请参阅配置受信任的证书

如果您需要为 mTLS 使用专用信任存储库,则可以通过运行以下命令来配置此信任存储库的位置

bin/kc.[sh|bat] start --https-trust-store-file=/path/to/file --https-trust-store-password=<value>

信任存储库的已识别文件扩展名

  • .p12.pkcs12.pfx 用于 pkcs12 文件

  • .jks.truststore 用于 jks 文件

  • .ca.crt.pem 用于 pem 文件

如果您的信任存储库没有与其文件类型匹配的扩展名,您还需要设置 https-key-store-type 选项。

其他资源

将 mTLS 用于传出的 HTTP 请求

请注意,这是 Keycloak 充当服务器的 mTLS 用例的基本证书配置。当 Keycloak 充当客户端时,例如,当 Keycloak 尝试从由 mTLS 保护的代理身份提供程序的令牌端点获取令牌时,您需要设置 HttpClient 以在密钥库中为传出的请求提供正确的证书。要在这些场景中配置 mTLS,请参阅配置传出的 HTTP 请求

配置 X.509 身份验证

有关如何配置 X.509 身份验证的更多信息,请参阅X.509 客户端证书用户身份验证部分

相关选项

https-client-auth

配置服务器以要求/请求客户端身份验证。

CLI: --https-client-auth
Env: KC_HTTPS_CLIENT_AUTH

none(默认)、requestrequired

https-trust-store-file

保存要信任的证书的证书信息的信任存储库。

CLI: --https-trust-store-file
Env: KC_HTTPS_TRUST_STORE_FILE

https-trust-store-password

信任存储库文件的密码。

CLI: --https-trust-store-password
Env: KC_HTTPS_TRUST_STORE_PASSWORD

https-trust-store-type

信任存储库文件的类型。

如果未给出,则根据文件扩展名自动检测类型。如果 fips-mode 设置为 strict 且未设置值,则默认为 BCFKS

CLI: --https-trust-store-type
Env: KC_HTTPS_TRUST_STORE_TYPE

https-management-client-auth

配置管理界面以要求/请求客户端身份验证。

如果未给出,则该值从 HTTP 选项继承。仅当在管理界面上公开某些内容时才相关 - 请参阅指南了解详细信息。

CLI: --https-management-client-auth
Env: KC_HTTPS_MANAGEMENT_CLIENT_AUTH

none(默认)、requestrequired

在此页上