何时使用转换声明规则

  • 项目

如果需要将传入声明类型映射到传出声明类型，可以在 Active Directory 联合身份验证服务 (AD FS) 中使用此规则，然后应用一项操作，用于根据源自传入声明中的值确定应出现的输出。 使用此规则时，将根据你在此规则中配置的任一选项传递或转换与以下规则逻辑匹配的声明，如下表所述。

规则选项 规则逻辑
传递所有传入声明 如果传入声明类型等于指定的声明类型 并且值等于任意值，则传递该声明并且传出声明类型等于指定的声明类型
将传入声明值替换为不同的传出声明值 如果传入声明类型等于指定的声明类型 并且值等于指定的声明值，则使用新的传出声明值指定的声明值 和传出声明类型指定的声明类型 转换该声明。
将传入电子邮件后缀声明替换为新的电子邮件后缀 如果传入声明类型等于指定的声明类型 并且值等于任意后缀值，则使用新的传出声明值指定的后缀值 和传出声明类型指定的声明类型 转换该声明。

以下部分提供了声明规则的基本介绍，并提供了有关何时使用此规则的更多详细信息。

关于声明规则

声明规则表示使用传入声明、向其应用条件 (if x, then y) 并基于条件参数生成传出声明的业务逻辑的实例。 下面的列表概述了在进一步阅读本主题中的内容之前应了解的有关声明规则的重要提示：

  • 在“AD FS 管理”管理单元中，只能使用声明规则模板创建声明规则

  • 声明规则处理以下两种传入声明：直接来自声明提供程序（如 Active Directory 或另一个联合身份验证服务），或来自声明提供程序信任上的接受转换规则的输出。

  • 声明规则由声明颁发引擎按给定规则集内的时间顺序处理。 通过为规则设置优先级，可以进一步优化或筛选由给定规则集内以前的规则生成的声明。

  • 声明规则模板始终要求你指定传入声明类型。 但是，你可以使用单个规则处理声明类型相同的多个声明值。

有关声明规则和声明规则集的更多详细信息，请参阅声明规则的角色。 有关如何处理规则的详细信息，请参阅声明引擎的角色。 有关如何处理声明规则集的详细信息，请参阅声明管道的角色。

传递所有声明值

使用此操作时，会将与指定的传入声明类型相匹配的所有传入声明值映射到指定的传出声明类型，然后将这些声明值作为传出声明发送到由联合身份验证服务签名的令牌中。

例如，如果为规则设置“传递所有声明值”选项逻辑并且指定传入声明类型“组”和传出声明类型“角色”，那么，从发出方流入的所有传入声明值将逐一复制到声明类型为“角色”的新传出声明中。

转换声明

在 AD FS 中，术语“声明转换”表示将一个传入声明值替换为不同的传出声明值。 “转换传入声明”规则使该功能变为可能。 在该规则的属性内，你可以设置条件，以便根据指定的传入声明类型将传入值转换为不同的传出声明值。

例如，如下图所示，如果为规则设置将传入值替换为不同的传出声明值的条件，所有传入声明类型“组”都将映射到新的传出声明类型“角色”。 在这种情况下，传入声明值“Purchaser”将替换为新的传出声明值“Admin”。

when to use a transform

你也可以使用此规则应用一个条件，该条件将所有传入声明的指定电子邮件后缀值替换为新值。 例如，你可以在此规则中设置一个条件，以便将所有声明值的后缀 sales.corp.fabrikam.com 更改为 fabrikam.com。

对声明提供程序信任配置此规则

使用声明提供程序信任时，可以将此规则配置为将来自声明提供程序的传入声明转换为可信的等效声明。 声明类型或声明值在你的组织中的含义与在声明提供程序组织中的含义可能有所不同。 你可以使用此规则对来自声明提供程序的声明类型和值执行标准化，以便于信赖方理解其传出声明类型和值。

对信赖方信任配置此规则

使用信赖方信任时，可以将此规则配置为针对特定信赖方转换声明。 声明类型或声明值对于特定的信赖方可能有不同的含义，此规则允许为单个信赖方更改传出声明类型和值。

如何创建此规则

可以使用声明规则语言或使用“AD FS 管理”管理单元中的“转换传入声明”规则模板来创建此规则。 此规则模板提供以下配置选项：

  • 指定声明规则名称

  • 将特定的传入声明类型转换为指定的传出声明类型

  • 传递所有声明值

  • 将传入声明值替换为不同的传出声明值

  • 将传入电子邮件后缀声明替换为新的电子邮件后缀

有关如何创建此模板的更多说明，请参阅《AD FS 部署指南》中的创建规则以转换传入声明。

使用声明规则语言

如果传出声明必须根据多个传入声明的内容构造，则必须改为使用自定义规则。 如果传出声明的声明值必须基于传入声明的值，但是还包括其他内容，那么，也必须在该上下文中使用自定义规则。 有关详细信息，请参阅 When to Use a Custom Claim Rule。

有关如何构造转换规则语法的示例

使用声明规则语言语法转换声明时，可以将已转换声明的属性设置为新的文本值。 例如，以下规则将角色声明的值从“Administrators”更改为“root”，同时保持相同的声明类型：

c:[type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/role", value == "Administrators"]  => issue(type = c.type, value = "root");

正则表达式也可用于声明转换。 例如，下面的规则将 DOMAIN\USER 格式的 Windows 用户名声明中的域设置为 FABRIKAM：

c:[type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"] => issue(type = c.type, value = regexreplace(c.value, "(?<domain>[^\\]+)\\(?<user>.+)", "FABRIKAM\${user}"));

创建自定义规则的最佳做法

可以向使用基本筛选功能选定的声明有选择性地应用声明转换。 可以为用于筛选的每个声明属性分配值，并提供以下说明：

声明属性 说明
Type、Value、ValueType 为这些属性分配值的频率最高。 必须为生成的已转换声明至少指定类型和值。
颁发者 虽然声明规则语言允许设置声明的发出方，但通常不建议这样做。 声明的发出方在令牌中不会序列化。 收到令牌时，所有声明的 Issuer 属性都将设置为已对该令牌签名的联合服务器的标识符。 因此，在规则中设置声明的发出方对令牌的内容没有任何影响，而且一旦在令牌中打包该声明，该设置便会丢失。 唯一需要设置声明发出方的情况为：它在声明提供程序规则集中设置为某个特定值，而信赖方规则集使用引用此特定值的规则创作。 如果 Issuer 属性未显式设置为声明规则中的某个值，声明发出引擎会将其设置为“LOCAL AUTHORITY”。
OriginalIssuer 与 Issuer 相同的是，OriginalIssuer 通常不应显式分配一个值。 与 Issuer 不同的是，OriginalIssuer 属性在令牌中会被序列化，但令牌使用者所希望的是，如果设置，它将包含最初发出声明的联合服务器的标识符。
属性 如前一部分所述，声明的属性包不会保存在令牌中，因此，应该在后续的本地策略要引用属性中存储的信息时，才对属性分配值。

有关如何使用声明规则语言的详细信息，请参阅声明规则语言的角色。