8.6. X.509 客户端证书用户身份验证

如果您已将服务器配置为使用 mutual SSL 身份验证，则 Red Hat build of Keycloak 支持使用 X.509 客户端证书登录。

一个典型的工作流：

客户端通过 SSL/TLS 频道发送身份验证请求。
在 SSL/TLS 握手期间，服务器和客户端会交换其 x.509/v3 证书。
容器(JBoss EAP)验证证书 PKIX 路径和证书过期日期。
X.509 客户端证书验证器使用以下方法验证客户端证书：
- 使用 CRL 或 CRL 分发点检查证书撤销状态。
- 使用 OCSP 检查证书撤销状态（在线证书状态协议）。
- 验证证书中的密钥是否与预期键匹配。
- 验证证书中的扩展密钥是否与预期的扩展密钥匹配。
如果其中任何检查失败，x.509 身份验证会失败。否则，验证器提取证书身份并将其映射到现有用户。

当证书映射到现有用户时，行为会根据身份验证流进行分类：

在 Browser Flow 中，服务器会提示用户确认其身份或使用用户名和密码登录。
在 Direct Grant Flow 中，服务器在用户中签名。

重要

请注意，这是 Web 容器负责验证证书 PKIX 路径。在 Red Hat build of Keycloak 端的 X.509 验证器只为检查证书过期、证书撤销状态和密钥用法提供了额外的支持。如果您使用在反向代理后部署的红帽 Keycloak 构建，请确保将反向代理配置为验证 PKIX 路径。如果您不使用反向代理和用户直接访问 JBoss EAP，则应该非常正常，因为 JBoss EAP 确保 PKIX 路径已被验证，只要它配置如下。

8.6.1. 功能

支持的证书身份源：

使用正则表达式匹配 SubjectDN
X500 主题的电子邮件属性
X500 Subject 来自 Subject Alternative Name Extension (RFC822Name General Name)的电子邮件。
来自 Subject Alternative Name Extension 的其他名称。这个其他名称是用户主体名称(UPN)，通常为.
X500 Subject 的通用名称属性
使用正则表达式匹配 IssuerDN
证书序列号
证书序列号和 IssuerDN
SHA-256 证书指纹
PEM 格式的完整证书

8.6.1.1. 正则表达式

Red Hat build of Keycloak 通过使用正则表达式作为过滤器从 Subject DN 或 Issuer DN 中提取证书身份。例如，此正则表达式与 email 属性匹配：

emailAddress=(.*?)(?:,|$)

如果将 Identity Source 设置为 Match SubjectDN using regular expression 或 Match IssuerDN using regular expression，会应用正则表达式过滤。

8.6.1.1.1. 将证书身份映射到现有用户

证书身份映射可以将提取的用户身份映射到现有用户的用户名、电子邮件或其值与证书身份匹配的自定义属性。例如，将 Identity source 设置为 Subject 的电子邮件 或用户映射方法到 Username 或 email 可使 X.509 客户端证书验证器在按用户名或电子邮件 搜索现有用户时，使用证书的主题 DN 中的 email 属性作为搜索条件。

重要

如果您在域设置中禁用 Login with email，则相同的规则适用于证书身份验证。用户无法使用 email 属性登录。
使用证书序列号和 IssuerDN 作为身份源，需要两个自定义属性用于序列号和 IssuerDN。
SHA-256 证书指纹 是 SHA-256 证书指纹的小写十六进制表示。
使用 PEM 格式的 Full certificate 作为身份源仅限于映射到外部联邦源（如 LDAP）的自定义属性。由于长度限制，Red Hat build of Keycloak 无法在其数据库中存储证书，因此当是 LDAP 时，您必须启用 Always Read Value from LDAP。

8.6.1.1.2. 扩展证书验证

使用 CRL 吊销状态检查。
使用 CRL/Distribution Point 吊销状态检查。
使用 OCSP/Responder URI 吊销状态检查。
证书密钥验证。
证书扩展密钥用法验证。

8.6.2. 将 X.509 客户端证书身份验证添加到浏览器流中

点菜单中的 Authentication。
单击 浏览器 流。
从 Action 列表中，选择 Duplicate。
输入副本的名称。
点 Duplicate。
单击添加步骤。
单击 "X509/Validate Username Form"。
点击 Add。
X509 执行
在"Browser Forms"执行中，单击"X509/Validate Username Form"并拖动"X509/Validate Username Form"。
将要求设置为"ALTERNATIVE"。
X509 浏览器流
点 Action 菜单。
单击 绑定流。
单击下拉列表中的 Browser 流。
点击 Save。
X509 浏览器流绑定

8.6.3. 配置 X.509 客户端证书身份验证

X509 配置

X509 Configuration

用户身份源: 定义从客户端证书提取用户身份的方法。
启用规范 DN 表示: 定义是否使用规范格式来确定可分辨的名称。官方 Java API 文档描述了格式。这个选项只使用正则表达式和 Match IssuerDN 影响两个用户身份源s Match Subject DN。当您设置新的红帽构建的 Keycloak 实例时，请启用这个选项。禁用这个选项，以保持与现有红帽构建的 Keycloak 实例的向后兼容性。
启用序列号十六进制表示: 以十六进制表示序列号。符号位设置为 1 的序列号必须保留为 00 octet 的 padded。例如，根据 RFC5280，带有十进制值 161 或十六进制的 a1 的序列号被编码为 00a1。如需了解更多详细信息，请参阅 RFC5280, appendix-B。
正则表达式: 用作提取证书身份的过滤器的正则表达式。表达式必须包含单个组。
用户映射方法: 定义将证书身份与现有用户匹配的方法。用户名或电子邮件根据用户名或电子邮件 搜索现有用户。自定义属性映射程序 会搜索具有与证书身份匹配的自定义属性的现有用户。自定义属性的名称可以配置。
用户属性的名称: 其值与证书身份匹配的自定义属性。当属性映射与多个值相关时，使用多个自定义属性，例如 'Certificate Serial Number 和 IssuerDN'。
启用 CRL 检查: 使用证书撤销列表检查证书的撤销状态。列表的位置在 CRL 文件路径 属性中定义。
启用 CRL 发布点来检查证书撤销状态: 使用 CDP 检查证书撤销状态。大多数 PKI 权威在证书中包含 CDP。
CRL 文件路径: 包含 CRL 列表的文件路径。如果启用了 CRL Checking Enabled 选项，则该值必须是到有效文件的路径。
启用 OCSP 检查: 使用在线证书状态协议检查证书撤销状态。
OCSP Fail-Open 行为: 默认情况下，OCSP 检查必须返回正响应才能继续身份验证。然而，这个检查可能会不明确：例如，OCSP 服务器无法访问、过载，或者客户端证书可能不包含 OCSP 响应器 URI。当启用此设置时，只有在 OCSP 响应程序收到显式负响应且证书一定被撤销时才拒绝身份验证。如果没有有效的 OCSP 响应，则会接受身份验证尝试。
OCSP Responder URI: 覆盖证书中的 OCSP 响应器 URI 的值。
验证密钥使用: 验证是否设置了证书的 KeyUsage 扩展位。例如，"digitalSignature,KeyEncipherment"验证是否设置了 KeyUsage 扩展中的位 0 和 2。保留此参数为空以禁用 Key Usage 验证。如需更多信息，请参阅 RFC5280, Section-4.2.1.3。当发生密钥用量不匹配时，Red Hat build of Keycloak 会引发错误。
验证扩展的密钥用法: 验证扩展密钥使用扩展中定义的一个或多个目的。如需更多信息，请参阅 RFC5280, Section-4.2.1.12。将此参数设置为空，以禁用扩展的密钥用法验证。当发出 CA 和密钥使用扩展不匹配时，Red Hat build of Keycloak 会引发一个错误。
验证证书策略: 验证证书策略扩展中定义的一个或多个策略 OID。请参阅 RFC5280, section-4.2.1.4。将参数留空，以禁用证书策略验证。应该使用逗号分隔多个策略。
证书策略验证模式: 当在 Validate Certificate Policy 设置中指定多个策略时，它会决定匹配是否应该检查要存在的所有请求策略，或者一个匹配是否足以满足成功的身份验证。默认值为 All，表示所有请求的策略都应该存在于客户端证书中。
绕过身份确认: 如果启用，X.509 客户端证书身份验证不会提示用户确认证书身份。成功身份验证后，红帽构建的 Keycloak 签署用户。
重新验证客户端证书: 如果设置，客户端证书信任链总是使用配置的信任存储中存在的证书在应用程序级别验证。如果底层 Web 服务器不强制客户端证书链验证，例如，它位于非评估负载均衡器或反向代理后，或者允许的 CA 的数量对于 mutual SSL 协商而言太大（大多数浏览器在 32767 字节中表示最大 SSL 协商数据包大小，这对应于大约 200 个广告的 CA）。默认情况下，这个选项为 off。

8.6.4. 将 X.509 客户端证书身份验证添加到直接授予流

点菜单中的 Authentication。
从 "Action list" 中选择 Duplicate 来制作内置 "Direct grant" 流的副本。
输入副本的名称。
点 Duplicate。
点创建的流。
单击"Username Validation"的垃圾箱图标 HEKETI"，然后单击" 删除 "。
单击"密码"的垃圾箱图标，再单击删除。
单击添加步骤。
单击 "X509/Validate Username"。
点击 Add。
X509 直接授权执行
按照 x509 浏览器流部分中描述的步骤来设置 x509 身份验证配置。
单击 Bindings 选项卡。
点 Direct Grant Flow 下拉列表。
点新创建的 "x509 Direct Grant" 流。
点 Save。
X509 直接授权流绑定

8.6.4.1. 使用 CURL 的示例

以下示例演示了如何使用直接授权流在 realm 测试 中为用户获取访问令牌。示例在 secure apps 部分和机密客户端 资源所有者 中使用 OAuth2 Resource Owner Password Credentials Grant ：

curl \
  -d "client_id=resource-owner" \
  -d "client_secret=40cc097b-2a57-4c17-b36a-8fdf3fc2d578" \
  -d "grant_type=password" \
  --cacert /tmp/truststore.pem \
  --cert /tmp/keystore.pem:kssecret \
  "https://localhost:8543/realms/test/protocol/openid-connect/token"

文件 /tmp/truststore.pem 指向包含红帽构建的 Keycloak 服务器的证书的信任存储的文件。文件 /tmp/keystore.pem 包含与红帽构建的 Keycloak 用户对应的私钥和证书，这将由此请求成功进行身份验证。它取决于验证器的配置是映射至 Keycloak 用户红帽构建的证书中的内容，如配置部分所述。kssecret 可能是此密钥存储文件的密码。

根据您的环境，可能需要对 CURL 命令使用更多选项，如实例：

如果您使用自签名证书，则 option- insecure
option--capath，用于包含证书颁发机构路径的整个目录
如果要使用与 PEM不同的文件，options-- cert -type or--key -type

如果需要，请参阅 curl 工具的文档。如果您使用除 curl 以外的其他工具，请查阅您的工具文档。但是，设置类似于：如果您使用机密客户端，则需要包含密钥存储和信任存储以及客户端凭据。

注意

如果有可能，最好将服务帐户与 MTLS 客户端身份验证（客户端验证器 X509 证书）一起使用，而不是将直接授权与 X.509 身份验证一起使用，因为直接授权可能需要与客户端应用程序共享用户证书。在使用服务帐户时，令牌将代表客户端本身获得，这通常更好且更安全的做法。