如何在Keycloak中设置MS AD FS 3.0作为中介身份提供者

2017年3月23日,星期四,由hynekmlna ř í k发布

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

先决条件

  • 两个服务器主机:
    • 已安装Active Directory联合身份验证服务 (AD FS) 的Microsoft Windows Server 2012。 广告域将被命名为域名。名称在这篇文章中。
    • Keycloak服务器。 这通常可以放在任何地方,但这里预计它将在单独的主机上运行
  • 域名系统设置:
    • Windows主机名将为fs.domain.name在这篇文章中
    • Keycloak主机名将是域名名称在这篇文章中

设置密钥斗篷服务器

Keycloak服务器已配置为SSL/TLS传输-AD FS必须与之通信。 这包括两个步骤:

  • 设置传入HTTPS的Keycloak 连接-提供步骤在服务器安装指南中
  • 将AD FS证书导出到Java truststore中,以启用传出HTTPS连接:
    • 在AD FS管理控制台中,转到服务 → 证书树中的节点并导出服务通信证书。
    • 使用Java keytool实用程序将证书导入Java truststore (JKS格式)。
    • 如前所述,在Keycloak中设置信任商店在服务器安装指南中

在Keycloak中设置身份提供程序

设置中介身份提供者的基本属性

在身份提供程序中,创建一个新的SAML v2.0身份提供程序。 在这篇文章中,身份提供者将以别名知道adfs-国内流离失所者-别名

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

如果发送到AD FS实例的身份验证请求被期望签名 (通常也是这种情况),则必须启用想要授权请求签名选项。 重要的是,然后SAML签名键名称启用后显示的字段想要授权请求签名选项必须设置为cert_主题,因为AD FS希望签名键名称提示是签名证书的主题。

将在下一步中设置AD FS,以Windows域名限定名称格式的名称ID进行响应,因此设置NameID策略格式相应的字段。



设置映射器

在下面设置AD FS的步骤中,将设置AD FS以SAML断言发送电子邮件和组信息。 要将这些详细信息从AD FS发布的SAML文档转换为Keycloak用户存储,我们需要在Identity Provider的mappers选项卡中设置两个相应的映射器:

  • 映射器命名组: 经理将是类型角色的SAML属性,并将映射名为http://schemas.xmlsoap.org/claims/Group,如果有属性值经理们,角色经理


  • 映射器命名属性: 电子邮件将是类型属性导入器,并将映射名为http://schemas.xmlsoap.org/ws/ 2005/05/身份/索赔/电子邮件地址进入名为的用户属性电子邮件

获取AD FS配置信息

现在,我们从重定向URI通过在此字段中的URI中添加 “/描述符”,在身份提供程序详细信息中的字段。 URI将类似于https://kc.domain.name:8443/auth/realms/master/broker/adfs-idp-别名/端点/描述符。 您可以通过在浏览器中输入URI来检查是否正确获得了URI-您应该收到SAML服务提供商XML描述符。

在AD FS中设置依赖方信任

设置依赖方

在AD FS管理控制台中,右键单击Trust关系 → 依赖方信任并选择添加依赖方信任从菜单:



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

设置声明映射

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

我们将设置三个规则: 一个用于映射用户id,第二个用于映射标准用户属性,第三个用于用户组。 全部从点击添加规则按钮在编辑kc.domain.name的声明规则窗口:



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



上面的示例针对windows帐户名称ID格式。 支持其他名称ID格式,但不在本文的范围内。 参见例如这个博客关于如何为持久性和瞬态格式设置名称id。


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



如果用户是命名组的成员,则第三条规则将发送组名称。 在添加转换声明规则窗口,然后选择发送组成员资格作为索赔规则类型。 然后在字段中输入请求的值:



此设置将发送一个名为在具有值的SAML断言中经理如果经过身份验证的用户是域 \ 管理器组。

故障排除

作为第一手工具,您应该检查浏览器中Keycloak和AD FS之间来回发送的SAML消息。 SAML解码器可作为浏览器扩展 (例如适用于Firefox的SAML Tracer,适用于Chrome的SAML Chrome面板)。 从捕获的通信中,您可能会看到错误状态代码以及设置映射器所需的SAML断言中的实际属性名称和值。 例如,如果无法识别名称ID格式,则AD FS将返回包含urn:oasis: 名称: tc:SAML:2.0: 状态: 无效名称idpolicy状态代码。


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


/子系统 = 日志记录/记录器 = org.keycloak.saml: 添加 (级别 = 调试)
/子系统 = 日志记录/记录器 = org.Keycloak.br oker.saml: 添加 (级别 = 调试)

然后,您将能够在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-别名/端点/描述符/联邦元数据/2007-06/联邦元数据.xml。 它会造成任何伤害吗?
答:这是无害的。 似乎Windows 2016版本首先通过添加来检查类似AD FS的描述符URLFederationMetadata/2007-06/FederationMetadata.xml到输入的URL。 Keycloak中不存在此类资源,因此报告错误。 但是,当发生这种情况时,AD FS似乎使用输入的URL导入。 另请参见原始电子邮件讨论在这个问题上。 

结论

如果您陷入困境,请毫不犹豫地向Keycloak用户论坛邮件列表。


由于总有改进的余地,如果您发现任何问题或对此文本有任何建议,请随时发表评论!