AD FS SAML SSO 配置指南：信赖方信任、声明规则与元数据

AD FS 的 SAML SSO 配置是一项典型的“后台工作”——大部分步骤在图形界面中完成，但真正决定成败的往往是元数据和声明规则这些细节。本文基于一份逐步操作指南，梳理信赖方信任的建立、声明规则的配置以及元数据交换中的常见雷区，帮助你在配置阶段就避开那些会导致登录失败的坑。

信赖方信任：配置的起点

在 AD FS 管理控制台中，添加信赖方信任是整个 SAML SSO 连接的第一步。操作路径通常是从“AD FS”节点下的“信赖方信任”文件夹右键选择“添加信赖方信任”，然后启动向导。向导会要求你选择数据源：可以从合作伙伴的元数据文件或 URL 导入，也可以手动输入信赖方的显示名称和 SAML 断言消费服务端点（Assertion Consumer Service URL）。

选择从元数据导入能自动填充端点、标识符和证书信息，减少手工输入错误。但即便使用元数据，仍需确认导入的标识符（信赖方标识符）与后续声明规则中使用的值一致，否则会出现令牌被拒绝的情况。

SAML 断言消费服务端点（Assertion Consumer Service URL，简称 ACS URL）是服务提供商（SP）侧接收 SAML 断言的地址。当用户在 AD FS 完成身份验证后，AD FS 会将包含用户身份信息的 SAML 断言通过 HTTP POST 绑定发送到这个 URL。ACS URL 必须与 SP 侧配置的接收端点完全一致，包括协议（通常是 https）、域名、端口和路径，任何字符差异都会导致断言无法投递或被 SP 拒绝。在元数据导入模式下，ACS URL 会自动从 SP 提供的元数据中读取；手动配置时则需要向 SP 管理员索取准确的地址。此外，一个 SP 可能配置多个 ACS 端点（如不同区域或不同应用实例），AD FS 默认使用索引为 0 的端点，必要时可在信赖方信任属性中调整。

声明规则：决定用户能拿到什么

信赖方信任建立后，需要配置声明规则。AD FS 的声明规则分为“颁发转换规则”和“颁发授权规则”两类，向导中的“编辑声明规则”对话框提供了模板化配置和自定义规则两种方式。

最常见的场景是将 Active Directory 属性映射为 SAML 断言中的声明。例如，使用“将 LDAP 属性作为声明发送”模板，将用户的 UPN 或电子邮件地址映射为 Name ID。名称 ID 的格式选择（如未指定、UPN、电子邮件地址）会直接影响服务提供商对用户身份的识别，如果 SP 期望的格式与 AD FS 发送的不一致，登录会失败。

自定义规则则提供了更细粒度的控制，比如基于组成员身份过滤声明，或对声明值进行转换。规则语言基于声明规则语言（Claim Rule Language），虽然语法简单，但容易因拼写或变量引用错误导致规则不生效。

声明规则语言（Claim Rule Language）是 AD FS 内置的一种轻量级 DSL，用于编写自定义的颁发转换规则和颁发授权规则。它支持条件判断（如 c:[Type == "..."] => issue(...)）、从 Active Directory 查询属性（c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-32-544"]）以及声明值的正则替换等操作。典型语法为“条件 => 动作”，动作可以是 issue（颁发新声明）、add（向现有声明追加值）或 issueStore（存入声明存储）。由于规则语言不做编译期检查，变量名拼写错误、claim type URI 写错或条件表达式语法不当都会导致规则在运行时静默失效——即规则被保存但永远不会触发，这也是排障时容易被忽略的隐蔽故障点。建议在编写复杂规则后，通过事件查看器中的 AD FS/Admin 日志确认规则是否按预期执行。

元数据：证书与端点的同步

元数据是 SAML 信任的“契约文件”，包含实体 ID、SAML 端点以及用于签名和加密的证书。AD FS 提供两种元数据地址：联合元数据（FederationMetadata.xml）和特定信赖方的元数据。服务提供商需要从 AD FS 获取元数据，或者将 AD FS 的签名证书手动配置到 SP 侧。

证书过期是元数据相关的常见故障点。AD FS 的令牌签名证书有有效期，如果 SP 侧未及时更新元数据中的证书，签名验证会失败。同样，如果 SP 的元数据中缺少加密证书，而 AD FS 配置了要求加密断言，令牌会被拒绝。

AD FS 的令牌签名证书和令牌解密证书默认有效期为一年，到期前 AD FS 会自动生成新证书并与旧证书并存一段时间（称为证书重叠期），以便 SP 侧有时间更新元数据。但如果 SP 侧在旧证书过期后才刷新元数据，或元数据缓存未及时失效，签名验证就会失败。为降低风险，可以启用 AD FS 的“自动证书滚动更新”功能，并建立定期检查证书到期时间的运维流程。另一方面，令牌加密是可选项：当 SP 要求加密断言时，SP 需在元数据中提供加密证书（公钥），AD FS 用该公钥加密断言后再发送，SP 用自己的私钥解密。若 SP 元数据缺少加密证书而 AD FS 被配置为“始终加密断言”，令牌会因无法加密而被拒绝。

常见故障：从配置到登录

根据原始指南的提示，许多登录失败在配置阶段就已埋下伏笔。端点 URL 的拼写错误、名称 ID 格式不匹配、声明规则中的变量引用错误、证书未同步，这四类问题覆盖了大部分排障场景。配置完成后，建议使用 AD FS 的测试工具（如 Test-AdfsClaimDescription 或事件查看器中的 AD FS 日志）验证声明输出，而不是等到用户报告登录失败才回头检查。

配置 AD FS SAML SSO 并不是一劳永逸的工作，元数据中的证书需要定期轮换，声明规则也可能随业务需求调整。把元数据交换和声明规则当作需要持续维护的契约，而不是一次性的向导任务，能减少后续的意外故障。