如何在 Keycloak 中将 MS AD FS 3.0 设置为代理身份提供者

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 下 شناخته می شود。

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

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

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

设置映射器

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

名为组：经理的映射器将是 SAML 属性到角色类型，并将映射名为 http://schemas.xmlsoap.org/claims/Group 的属性，如果该属性的值为经理，则映射到角色经理。

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

获取 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 管理控制台中，右键单击 Trust 关系 → 信赖方信任并从菜单中选择添加信赖方信任：

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

设置声明映射

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

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

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

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

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

第三条规则将在用户是命名组的成员时发送组名称。在添加转换声明规则窗口中再次开始，并选择将组成员资格作为声明发送规则类型。然后在字段中输入请求的值：

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

故障排除

作为首选工具，您应该检查在 Keycloak 和 AD FS 之间发送回的 SAML 消息。SAML 解码器可以作为浏览器扩展使用（例如，Firefox 的 SAML Tracer、Chrome 的 SAML Chrome Panel）。从捕获的通信中，您可能会看到错误状态代码以及 SAML 断言中用于设置映射器的实际属性名称和值。例如，如果名称 ID 格式无法识别，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：无法执行：javax.ws.rs.NotFoundException：RESTEASY003210：找不到完整路径的资源：https://kc.domain.name/auth/realms/master/broker/adfs-idp-alias/endpoint/descriptor/FederationMetadata/2007-06/FederationMetadata.xml。这会导致任何问题吗？
答：没有问题。似乎 Windows 2016 版本首先通过在输入的 URL 后添加 FederationMetadata/2007-06/FederationMetadata.xml 来检查 AD FS 类描述符 URL。Keycloak 中不存在此类资源，因此它会报告错误。但是，AD FS 似乎在发生这种情况时使用输入的 URL 进行导入。请参阅有关此问题的原始电子邮件讨论。

结论

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

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