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 身份验证会失败。否则，验证器会提取证书身份并将其映射到现有用户。
当证书映射到现有用户时，行为会根据身份验证流程进行分散：
- 在浏览器流中，服务器提示用户确认其身份或使用用户名和密码登录。
- 在 Direct Grant Flow 中，服务器在用户中签名。
请注意，web 容器负责验证证书 PKIX 路径。红帽构建的 Keycloak 端的 X.509 身份验证程序只提供检查证书过期、证书撤销状态和密钥用法的额外支持。如果您使用部署在反向代理后的 Keycloak 的红帽构建，请确保将反向代理配置为验证 PKIX 路径。如果您不使用反向代理，并且用户直接访问 JBoss EAP，您应当很正常，因为 JBoss EAP 确保 PKIX 路径被验证，只要其已配置，如下所述。
8.6.1. 功能
支持的证书身份源：
- 使用正则表达式匹配 SubjectDN
- X500 主题的电子邮件属性
- 主题备用名称扩展中的 X500 主题电子邮件(RFC822Name General Name)
- 来自 Subject Alternative Name Extension 的 X500 主题的其他名称。这个其他名称为 User Principal Name (UPN)，通常是。
- X500 主题的 Common Name 属性
- 使用正则表达式匹配 IssuerDN
- 证书序列号
- 证书序列号和 IssuerDN
- SHA-256 证书指纹
- PEM 格式的完整证书
8.6.1.1. 正则表达式
Red Hat build of Keycloak 通过使用正则表达式作为过滤器从主题 DN 或 Issuer DN 中提取证书身份。例如，这个正则表达式与 email 属性匹配：
emailAddress=(.*?)(?:,|$)
如果 Identity Source 设置为使用正则表达式的 Match SubjectDN 或使用正则表达式 的 Match IssuerDN，则应用正则表达式 过滤。
8.6.1.1.1. 将证书身份映射到现有用户
证书身份映射可以将提取的用户身份映射到现有用户的用户名、电子邮件或自定义属性，其值与证书身份匹配。例如，将 Identity source 设置为 Subject 的电子邮件 或用户映射方法 设置为 Username 或 email，使 X.509 客户端证书验证器 使用证书的主题 DN 中的 email 属性作为搜索条件，按用户名或电子邮件搜索现有用户。
- 如果您使用 realm 设置中的 电子邮件禁用登录，则相同的规则将应用到证书身份验证。用户无法使用 email 属性登录。
-
将证书序列号和 IssuerDN用作身份源需要两个自定义属性用于序列号和 IssuerDN。 -
SHA-256 证书指纹是 SHA-256 证书指纹的小写十六进制表示。 -
使用
PEM 格式的 Full certificate作为身份源仅限于映射到外部联邦源的自定义属性，如 LDAP。由于长度限制，红帽构建的 Keycloak 无法将证书存储在数据库中，因此对于 LDAP，您必须启用Always Read Value from LDAP。
8.6.1.1.2. 扩展证书验证
- 使用 CRL 吊销状态检查。
- 使用 CRL/Distribution Point 进行撤销状态检查。
- 使用 OCSP/Responder URI 吊销状态检查。
- 证书验证。
- 证书 ExtendedKeyUsage 验证。
8.6.2. 在浏览器流中添加 X.509 客户端证书身份验证
- 点菜单中的 Authentication。
- 单击 浏览器 流。
- 从 Action 列表中，选择 Duplicate。
- 输入副本的名称。
- 点 Duplicate。
- 点 Add step。
- 点 "X509/Validate Username Form"。
点 Add。
X509 执行
- 点并将 "X509/Validate Username Form" 拖到"Browser Forms"执行中。
将要求设置为"ALTERNATIVE"。
X509 浏览器流
- 点 Action 菜单。
- 点 Bind flow。
- 从下拉列表中选择 浏览器流。
点 Save。
X509 浏览器流绑定
8.6.3. 配置 X.509 客户端证书身份验证
X509 配置
- 用户身份源
- 定义从客户端证书提取用户身份的方法。
- 启用规范 DN 表示
- 定义是否使用规范格式来确定可分辨名称。官方 Java API 文档描述了格式。此选项 使用正则表达式影响两个用户身份源匹配 SubjectDN，只使用 正则表达式匹配 IssuerDN。设置新的 Keycloak 实例时，启用这个选项。禁用这个选项，以保持与现有红帽构建的 Keycloak 实例的向后兼容性。
- 启用序列号十六进制表示
- 以十六进制形式表示 序列号。符号位设置为 1 的序列号必须保留为 00 octet。例如，十进制值为 161 的序列号或十六进制表示的序列号被编码为 00 a1 ，具体取决于 RFC5280。如需了解更多详细信息，请参阅 RFC5280、附录-B。
- 正则表达式
- 用作提取证书身份的过滤器的正则表达式。表达式必须包含单个组。
- 用户映射方法
- 定义将证书身份与现有用户匹配的方法。用户名或电子邮件按用户名或电子邮件 搜索现有用户。自定义属性映射程序 使用与证书身份匹配的自定义属性搜索现有用户。自定义属性的名称是可配置的。
- 用户属性的名称
- 与证书身份匹配的自定义属性。当属性映射与多个值相关时，请使用多个自定义属性，例如 'Certificate Serial Number 和 IssuerDN'。
- CRL 检查已启用
- 使用证书撤销列表检查证书的撤销状态。列表的位置在 CRL file path 属性中定义。
- 启用 CRL 分发点以检查证书撤销状态
- 使用 CDP 检查证书撤销状态。大多数 PKI 授权在其证书中包括 CDP。
- CRL 文件路径
- 包含 CRL 列表的文件的路径。如果启用了 CRL Checking Enabled 选项，该值必须是到有效文件的路径。
- OCSP 检查已启用
- 使用在线证书状态协议检查证书撤销状态。
- OCSP Fail-Open Behavior
- 默认情况下，OCSP 检查必须返回一个正响应才能继续成功验证。有时，这个检查可能不是不冲突的：例如，OCSP 服务器可能无法访问、过载，或者客户端证书可能不包含 OCSP 响应者 URI。当此设置开启 ON 时，只有在 OCSP 响应程序收到显式负响应并且证书被撤销时，才会拒绝身份验证。如果没有有效的 OCSP 响应，则接受身份验证尝试。
- OCSP Responder URI
- 覆盖证书中的 OCSP 响应 URI 的值。
- 验证密钥用法
- 验证是否设定了证书的 KeyUsage 扩展位。例如，"digitalSignature,KeyEncipherment" 验证 KeyUsage 扩展中的位 0 和 2 是否设置了 KeyUsage 扩展。将此参数设置为为空，以禁用 Key Usage 验证。如需更多信息，请参阅 RFC5280，第-4.2.1.3 节。当发生密钥使用不匹配时，红帽构建的 Keycloak 会引发错误。
- 验证扩展的密钥用法
- 验证扩展的密钥用法扩展中定义的一个或多个目的。如需更多信息，请参阅 RFC5280, section-4.2.1.12。将此参数设置为为空，以禁用扩展的密钥用法验证。当发布 CA 和发生密钥使用扩展不匹配时，Red Hat build of Keycloak 会抛出一个错误。
- 验证证书策略
- 验证证书策略扩展中定义的一个或多个策略 OID。请参阅 RFC5280，第-4.2.1.4 节。将参数留空，以禁用证书策略验证。应该使用逗号分隔多个策略。
- 部署策略验证模式
-
当在
Validate 证书策略设置中指定多个策略时，它会决定匹配是否应该检查所有请求的策略是否存在，或者一个匹配项足以成功进行身份验证。默认值为All，表示所有请求的策略都应存在于客户端证书中。 - 绕过身份确认
- 如果启用，X.509 客户端证书身份验证不会提示用户确认证书身份。身份验证成功后，红帽在用户构建 Keycloak 进行签名。
- 重新验证客户端证书
- 如果设置，客户端证书信任链始终使用配置的信任存储中存在的证书，始终在应用程序级别验证。如果底层 web 服务器不强制实施客户端证书链验证，例如，它位于非评估负载均衡器或反向代理后面，或者允许 CA 的数量对于 mutual SSL 协商（大多数浏览器上限为 32767 字节）时很有用。默认情况下，这个选项为 off。
8.6.4. 在直接授予流中添加 X.509 客户端证书验证
- 点菜单中的 Authentication。
- 从 "Action 列表中选择 Duplicate，以制作内置"直接授权"流的副本。
- 输入副本的名称。
- 点 Duplicate。
- 点创建的流。
- 单击"Username Validation"的回收站图标，然后单击 Delete。
- 单击"密码"的回收站图标，然后单击 Delete。
- 点 Add step。
- 点 "X509/Validate Username"。
点 Add。
X509 直接授权执行
- 按照 x509 浏览器流部分中介绍的步骤来设置 x509 身份验证配置。
- 点 Bindings 选项卡。
- 点 Direct Grant Flow 下拉列表。
- 点新创建的 "x509 Direct Grant" 流。
点 Save。
X509 直接授权流绑定
