为 mTLS 配置受信任证书

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

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

启用 mTLS

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

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

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

所有 Realm 共享 mTLS 配置和信任库。无法为不同的 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>

其他资源

对传出的 HTTP 请求使用 mTLS

请注意,这是 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

在本页上