如何设置 MS AD FS 3.0 作为 Keycloak 中的代理身份提供商

2017 年 3 月 23 日，作者：Hynek Mlnařík

这篇文章已超过一年。博客文章中的内容可能已过时。

本文档指导您完成 Microsoft Active Directory 联合身份验证服务 3.0 作为 Keycloak 的代理身份提供商的初始设置。

先决条件

两台服务器主机

安装了 Active Directory 联合身份验证服务 (AD FS) 的 Microsoft Windows Server 2012。AD 域在本篇文章中将被命名为 DOMAIN.NAME。
Keycloak 服务器。通常可以放置在任何地方，但此处期望它在单独的主机上运行

DNS 设置

Windows 主机名在本篇文章中将为 fs.domain.name。
Keycloak 主机名在本篇文章中将为 kc.domain.name。

设置 Keycloak 服务器

Keycloak 服务器已配置为 SSL/TLS 传输 - 这对于 AD FS 与之通信是强制性的。这包括两个步骤

为传入的 HTTPS 连接设置 Keycloak - 步骤在服务器安装指南中提供。
将 AD FS 证书导出到 Java 信任库，以启用传出的 HTTPS 连接

在 AD FS 管理控制台中，转到树中的服务 → 证书节点，并导出服务通信证书。
使用 Java keytool 工具将证书导入到 Java 信任库（JKS 格式）。
按照服务器安装指南中的描述，在 Keycloak 中设置信任库。

在 Keycloak 中设置身份提供商

设置代理身份提供商的基本属性

在身份提供商中，创建一个新的 SAML v2.0 身份提供商。在本篇文章中，身份提供商将以别名 adfs-idp-alias 为人所知。

现在滚动到底部，并在从 URL 导入字段中输入 AD FS 描述符 URL。对于 AD FS 3.0，此 URL 为 https://fs.domain.name/FederationMetadata/2007-06/FederationMetadata.xml。单击“导入”后，检查设置。通常，您至少应启用验证签名选项。

如果发送到 AD FS 实例的身份验证请求需要签名（通常也是这种情况），则必须启用需要身份验证请求签名选项。重要的是，然后启用需要身份验证请求签名选项后显示的SAML 签名密钥名称字段必须设置为 CERT_SUBJECT，因为 AD FS 期望签名密钥名称提示是签名证书的主题。

AD FS 将在下一步中设置为以 Windows 域限定名格式响应 NameID，因此请相应地设置NameID 策略格式字段。

设置映射器

在下面的 AD FS 设置步骤中，AD FS 将设置为在 SAML 断言中发送电子邮件和组信息。为了将这些详细信息从 AD FS 颁发的 SAML 文档转换为 Keycloak 用户存储，我们需要在身份提供商的“映射器”选项卡中设置两个相应的映射器

名为Group: managers的映射器将是SAML 属性到角色类型，并将名为http://schemas.xmlsoap.org/claims/Group的属性（如果该属性的值为managers）映射到角色manager。

名为Attribute: email的映射器将是属性导入器类型，并将名为http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress的属性映射到名为email的用户属性中。

获取 AD FS 配置的信息

现在我们从身份提供商详细信息中的重定向 URI字段中确定将在 AD FS 设置中使用的 SAML 服务提供商描述符 URI，方法是在此字段的 URI 中添加“/descriptor”。URI 将类似于 https://kc.domain.name:8443/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor。您可以通过将 URI 输入浏览器来检查您是否获得了正确的 URI - 您应该收到一个 SAML 服务提供商 XML 描述符。

在 AD FS 中设置信赖方信任

设置信赖方

在 AD FS 管理控制台中，右键单击信任关系 → 信赖方信任，然后从菜单中选择添加信赖方信任：

在向导的开始，在联合元数据地址字段中输入上一步中获得的 SAML 描述符 URL，并让 AD FS 导入设置。继续向导，并在适当的地方调整设置。在这里我们仅使用默认设置。请注意，您需要编辑声明规则，因此当在向导的最后一页要求您这样做时，您可以保持选中复选框。

设置声明映射

现在 SAML 协议将正确进行，AD FS 将能够根据来自 Keycloak 的请求正确验证用户身份，但请求的 NameID 格式尚未被识别，并且 SAML 响应将不包含任何其他信息，例如电子邮件。因此，有必要将声明从 AD 用户详细信息映射到 SAML 文档中。

我们将设置三个规则：一个用于映射用户 ID，第二个用于映射标准用户属性，第三个用于用户组。所有规则都从单击kc.domain.name 的编辑声明规则窗口中的添加规则按钮开始：

第一个规则将 Windows 限定域名中的用户 ID 映射到 SAML 响应。在添加转换声明规则窗口中，选择转换传入声明规则类型：

上面的示例针对 Windows 帐户名称 ID 格式。支持其他名称 ID 格式，但不在本文档的范围之内。例如，请参阅此博客，了解如何为持久性和瞬态格式设置名称 ID。

第二个规则将用户电子邮件映射到 SAML 响应。在添加转换声明规则窗口中，选择发送 LDAP 属性作为声明规则类型。您可以根据需要添加其他属性：

第三个规则将在用户是指定组的成员时发送组名。再次在添加转换声明规则窗口中启动，然后选择发送组成员身份作为声明规则类型。然后在字段中输入请求的值：

如果经过身份验证的用户是DOMAIN\Managers组的成员，则此设置将在 SAML 断言中发送一个名为Group的属性，其值为managers。

故障排除

作为第一手工具，您应该在浏览器中检查 Keycloak 和 AD FS 之间来回发送的 SAML 消息。SAML 解码器可以作为浏览器扩展程序使用（例如，Firefox 的 SAML Tracer，Chrome 的 SAML Chrome Panel）。从捕获的通信中，您可能会看到错误状态代码以及 SAML 断言中设置映射器所需的实际属性名称和值。例如，如果 NameID 格式无法识别，AD FS 将返回包含 urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy 状态代码的 SAML 响应。

作为第二种方法，请检查日志。对于 AD FS，日志在事件查看器的应用程序和服务日志 → AD FS → 管理员下可用。在 Keycloak 中，您可以通过 jboss-cli.sh 连接到正在运行的 Keycloak 实例并输入以下命令来启用 SAML 处理的跟踪：

/subsystem=logging/logger=org.keycloak.saml:add(level=DEBUG)

/subsystem=logging/logger=org.keycloak.broker.saml:add(level=DEBUG)

然后，您将能够在 Keycloak 服务器日志中找到 SAML 消息和与代理相关的 SAML 处理消息。

常见问题

问：我无法注销！当我在我的应用程序中单击注销时，看起来我已经从 Keycloak 注销了，但是当我返回到应用程序时，AD FS 登录表单永远不会显示，并且我以与之前相同的用户身份重定向回已验证状态！

答：不要惊慌。这不是 Keycloak 问题，而是 AD FS 身份验证策略的设置。尝试禁用 Windows 身份验证，然后再报告问题。

问：在 Windows 2016 中使用 AD FS 时，从 URL 导入描述符后，Keycloak 日志中出现以下错误：RESTEASY002010: Failed to execute: javax.ws.rs.NotFoundException: RESTEASY003210: Could not find resource for full path: https://kc.domain.name/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor/FederationMetadata/2007-06/FederationMetadata.xml。这会造成任何损害吗？
答：这是无害的。似乎 Windows 2016 版本首先通过将 FederationMetadata/2007-06/FederationMetadata.xml 添加到输入的 URL 来检查类似 AD FS 的描述符 URL。Keycloak 中不存在此类资源，因此它报告错误。但是，当发生这种情况时，AD FS 似乎会使用输入的 URL 进行导入。另请参阅关于此问题的原始邮件讨论。

结论

如果您遇到困难，请随时在 Keycloak 用户论坛 邮件列表中提出问题。

由于总有改进的空间，如果您发现本文档有任何问题或有任何建议，请随时留下评论！