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 路径，就可以验证 PKIX 路径。
8.6.1. 功能
支持的证书身份源：
- 使用正则表达式匹配 SubjectDN
- X500 主题的电子邮件属性
- 来自 Subject Alternative Name Extension (RFC822Name General Name)的 X500 主题的电子邮件
- 来自 Subject Alternative Name Extension 的 X500 主题的其他名称。另一个名称是 User Principal Name (UPN)，通常为。
- X500 主题的通用名称属性
- 使用正则表达式匹配 IssuerDN
- 证书序列号
- 证书序列号和 IssuerDN
- SHA-256 证书指纹
- PEM 格式的完整证书
8.6.1.1. 正则表达式
Red Hat build of Keycloak 通过使用正则表达式作为过滤器从主题 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 或 User mapping method to Username 或 email 使 X.509 客户端证书验证器 使用 email 属性作为搜索条件。
- 如果您在 realm 设置中禁用 电子邮件登录，则相同的规则适用于证书身份验证。用户无法使用 email 属性登录。
-
使用证书序列号和 IssuerDN作为身份源，需要两个用于序列号和 IssuerDN 的自定义属性。 -
SHA-256 证书指纹是 SHA-256 证书指纹的小写十六进制表示。 -
使用
PEM 格式的完整证书作为身份源，仅限于映射到外部联邦源（如 LDAP）的自定义属性。由于长度限制，红帽构建的 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。
- 点 Add step。
- 点 "X509/Validate Username Form"。
点击 Add。
X509 执行
- 点并在"Browser Forms"执行中拖动 "X509/Validate Username Form"。
将要求设置为"ALTERNATIVE"。
X509 浏览器流
- 单击 Action 菜单。
- 单击 绑定流。
- 从下拉列表中选择 Browser 流。
点击 Save。
X509 浏览器流绑定
8.6.3. 配置 X.509 客户端证书身份验证
X509 配置
- 用户身份源
- 定义从客户端证书中提取用户身份的方法。
- 启用规范 DN 表示
- 定义是否使用规范格式来确定可分辨的名称。官方 Java API 文档描述了格式。这个选项会影响两个用户身份源 Match SubjectDN，只使用 正则表达式的 Match IssuerDN。设置新的 Keycloak 实例时，启用这个选项。禁用这个选项，以保持与现有红帽构建的 Keycloak 实例的向后兼容性。
- 启用序列号十六进制表示
- 以十六进制表示 序列号。符号位设为 1 的序列号必须保留为 00 八位。例如，根据 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。当此设置打开 ON 时，只有在 OCSP 响应程序收到显式负响应并且证书被绝对撤销时，才会拒绝身份验证。如果没有可用的有效 OCSP 响应，则接受身份验证尝试。
- OCSP Responder URI
- 覆盖证书中的 OCSP 响应器 URI 的值。
- 验证密钥使用
- 验证是否设置了证书的 KeyUsage 扩展位。例如，"digitalSignature,KeyEncipherment" 验证是否设置了 KeyUsage 扩展中的位 0 和 2。保留此参数为空以禁用 Key Usage 验证。如需更多信息，请参阅 RFC5280, Section-4.2.1.3。当发生密钥使用不匹配时，红帽构建的 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 协商来说太大（大多数浏览器将最大 SSL 协商数据包大小上限为 32767 字节），它对应于 200 公告的 CA。默认情况下，这个选项为 off。
8.6.4. 将 X.509 客户端证书身份验证添加到 Direct Grant Flow
- 点菜单中的 Authentication。
- 从 "Action list" 选择 Duplicate 来复制内置"Direct grant"流。
- 输入副本的名称。
- 点 Duplicate。
- 点创建的流。
- 点垃圾桶图标 "Username Validation" 的图标，然后点 Delete。
- 点击垃圾箱图标 "Password" 的图标，然后单击 Delete。
- 点 Add step。
- 点 "X509/Validate Username"。
点击 Add。
X509 直接授权执行
- 按照 x509 Browser Flow 部分中描述的步骤设置 x509 身份验证配置。
- 单击 Bindings 选项卡。
- 点 Direct Grant Flow 下拉列表。
- 点新创建的 "x509 Direct Grant" 流。
点 Save。
X509 直接授权流绑定
