Predicates 和 PredicateValidations

项目
10/14/2024

注意

在 Azure Active Directory B2C 中，自定义策略主要用于解决复杂的情况。在大多数情况下，建议你使用内置用户流。如果尚未这样做，请从 Active Directory B2C 中的自定义策略入门了解自定义策略新手包。

Predicates 和 PredicateValidations 元素可用于执行验证过程，以确保向 Azure Active Directory B2C (Azure AD B2C) 租户仅输入正确格式的数据。

以下图示显示了元素之间的关系：

显示谓词和谓词验证关系的示意图

谓词

Predicate 元素定义基本验证，用以检查声明类型的值并返回 true 或 false。可通过使用指定的 Method 元素和一组与该方法相关的 Parameter 元素来完成验证。例如，谓词可以检查字符串声明值的长度是否在指定的最小和最大参数范围内，或者字符串声明值是否包含字符集。如果检查失败，UserHelpText 元素将为用户提供一条错误消息。 UserHelpText 元素的值可以使用语言自定义进行本地化。

Predicates 元素必须紧跟在 BuildingBlocks 元素中的 ClaimsSchema 元素之后。

Predicates 元素包含以下元素：

元素	出现次数	说明
Predicate	1:n	谓词列表。

Predicate 元素包含以下属性：

属性	必须	描述
ID	是	用于谓词的标识符。其他元素可以在策略中使用此标识符。
方法	是	用于验证的方法类型。可能的值：IsLengthRange、MatchesRegex、IncludesCharacters 或 IsDateRange。
HelpText	否	检查失败时向用户发送的错误消息。此字符串可以使用语言自定义进行本地化

Predicate 元素包含以下元素：

元素	出现次数	说明
UserHelpText	0:1	（已弃用）检查失败时向用户显示的错误消息。
parameters	1:1	用于字符串验证的方法类型参数。

Parameters 元素包含以下元素：

元素	出现次数	说明
参数	1:n	用于字符串验证的方法类型参数。

Parameter 元素包含以下属性：

元素	出现次数	说明
ID	1:1	该参数的标识符。

谓词方法

IsLengthRange

IsLengthRange 方法检查字符串声明值的长度是否在指定的最小和最大参数的范围内。查看此谓词方法的实时演示。谓词元素支持以下参数：

参数	必需	说明
最大值	是	可输入的最大字符数。
最小值	是	必须输入的最小字符数。

下面的示例展示了 IsLengthRange 方法使用参数 Minimum 和 Maximum 指定字符串的长度范围：

<Predicate Id="IsLengthBetween8And64" Method="IsLengthRange" HelpText="The password must be between 8 and 64 characters.">
  <Parameters>
    <Parameter Id="Minimum">8</Parameter>
    <Parameter Id="Maximum">64</Parameter>
  </Parameters>
</Predicate>

MatchesRegex

MatchesRegex 方法检查字符串声明值是否与正则表达式相匹配。查看此谓词方法的实时演示。谓词元素支持以下参数：

参数	必需	说明
RegularExpression	是	要匹配的正则表达式模式。

下面的示例说明 MatchesRegex 方法使用参数 RegularExpression 指定正则表达式：

<Predicate Id="PIN" Method="MatchesRegex" HelpText="The password must be numbers only.">
  <Parameters>
    <Parameter Id="RegularExpression">^[0-9]+$</Parameter>
  </Parameters>
</Predicate>

IncludesCharacters

IncludesCharacters 方法检查字符串声明值是否包含字符集。查看此谓词方法的实时演示。谓词元素支持以下参数：

参数	必需	说明
CharacterSet	是	可输入的字符集。例如，小写字符 `a-z`、大写字符 `A-Z`、数字 `0-9`，或符号列表，如 `@#$%^&*\-_+=[]{}\|\\:',?/~"();!`。

下面的示例说明 IncludesCharacters 方法使用参数 CharacterSet 指定字符集：

<Predicate Id="Lowercase" Method="IncludesCharacters" HelpText="a lowercase letter">
  <Parameters>
    <Parameter Id="CharacterSet">a-z</Parameter>
  </Parameters>
</Predicate>

IsDateRange

IsDateRange 方法检查日期声明值是否在指定的最小和最大参数范围内。查看此谓词方法的实时演示。谓词元素支持以下参数：

参数	必需	说明
最大值	是	可输入的最大日期。日期格式遵循 `yyyy-mm-dd` 约定或 `Today`。
最小值	是	可输入的最小日期。日期格式遵循 `yyyy-mm-dd` 约定或 `Today`。

下面的示例说明 IsDateRange 方法使用参数 Minimum 和 Maximum 指定格式为 yyyy-mm-dd 和 Today 的日期范围。

<Predicate Id="DateRange" Method="IsDateRange" HelpText="The date must be between 1970-01-01 and today.">
  <Parameters>
    <Parameter Id="Minimum">1970-01-01</Parameter>
    <Parameter Id="Maximum">Today</Parameter>
  </Parameters>
</Predicate>

PredicateValidations

尽管谓词定义了根据声明类型进行检查的验证，但是 PredicateValidations 会对一组谓词进行分组，以构成可应用于声明类型的用户输入验证。每个 PredicateValidation 元素均包含一组 PredicateGroup 元素，其中包含一组指向 Predicate 的 PredicateReference 元素。为了通过验证，声明的值应通过所有 PredicateGroup 下的任何谓词的全部测试，及其包含的一组 PredicateReference 元素。

PredicateValidations 元素必须紧跟在 BuildingBlocks 元素中的 Predicates 元素之后。

<PredicateValidations>
  <PredicateValidation Id="">
    <PredicateGroups>
      <PredicateGroup Id="">
        <UserHelpText></UserHelpText>
        <PredicateReferences MatchAtLeast="">
          <PredicateReference Id="" />
          ...
        </PredicateReferences>
      </PredicateGroup>
      ...
    </PredicateGroups>
  </PredicateValidation>
...
</PredicateValidations>

PredicateValidations 元素包含以下元素：

元素	出现次数	说明
PredicateValidation	1:n	谓词验证列表。

PredicateValidation 元素包含以下属性：

属性	必须	描述
ID	是	用于谓词验证的标识符。 ClaimType 元素可以在策略中使用此标识符。

PredicateValidation 元素包含以下元素：

元素	出现次数	说明
PredicateGroups	1:n	谓词组列表。

PredicateGroups 元素包含以下元素：

元素	出现次数	说明
PredicateGroup	1:n	谓词列表。

PredicateGroup 元素包含以下属性：

属性	必须	描述
ID	是	用于谓词组的标识符。

PredicateGroup 元素包含以下元素：

元素	出现次数	说明
UserHelpText	0:1	谓词的说明，可以帮助用户了解应键入哪些值。
PredicateReferences	1:n	谓词引用的列表。

PredicateReferences 元素包含以下属性：

属性	必须	说明
MatchAtLeast	否	指定该值针对要接受的输入必须至少匹配多个谓词定义。如果未指定，则该值必须与所有谓词定义匹配。

PredicateReferences 元素包含以下元素：

元素	出现次数	说明
PredicateReference	1:n	对谓词的引用。

PredicateReference 元素包含以下属性：

属性	必须	描述
ID	是	用于谓词验证的标识符。

配置密码复杂性

使用 Predicates 和 PredicateValidationsInput，可以在创建帐户时控制用户提供的密码的复杂性要求。默认情况下，Azure AD B2C 使用强密码。此外，Azure AD B2C 还支持用于控制客户可以使用的密码复杂性的配置选项。你可以使用这些谓词元素来定义密码的复杂性：

IsLengthBetween8And64 使用 IsLengthRange 方法，验证密码必须介于 8 到 64 个字符之间。
Lowercase 使用 IncludesCharacters 方法，验证密码包含一个小写字母。
Uppercase 使用 IncludesCharacters 方法，验证密码包含一个大写字母。
Number 使用 IncludesCharacters 方法，验证密码包含一个数字。
Symbol 使用 IncludesCharacters 方法验证密码是否包含几个符号字符之一。
PIN 使用 MatchesRegex 方法，验证密码仅包含数字。
AllowedAADCharacters 使用 MatchesRegex 方法，验证提供了仅限密码的无效字符。
DisallowedWhitespace 使用 MatchesRegex 方法，验证密码不以空格字符开头或结尾。

<Predicates>
  <Predicate Id="IsLengthBetween8And64" Method="IsLengthRange" HelpText="The password must be between 8 and 64 characters.">
    <Parameters>
      <Parameter Id="Minimum">8</Parameter>
      <Parameter Id="Maximum">64</Parameter>
    </Parameters>
  </Predicate>

  <Predicate Id="Lowercase" Method="IncludesCharacters" HelpText="a lowercase letter">
    <Parameters>
      <Parameter Id="CharacterSet">a-z</Parameter>
    </Parameters>
  </Predicate>

  <Predicate Id="Uppercase" Method="IncludesCharacters" HelpText="an uppercase letter">
    <Parameters>
      <Parameter Id="CharacterSet">A-Z</Parameter>
    </Parameters>
  </Predicate>

  <Predicate Id="Number" Method="IncludesCharacters" HelpText="a digit">
    <Parameters>
      <Parameter Id="CharacterSet">0-9</Parameter>
    </Parameters>
  </Predicate>

  <Predicate Id="Symbol" Method="IncludesCharacters" HelpText="a symbol">
    <Parameters>
      <Parameter Id="CharacterSet">@#$%^&amp;*\-_+=[]{}|\\:',.?/`~"();!</Parameter>
    </Parameters>
  </Predicate>

  <Predicate Id="PIN" Method="MatchesRegex" HelpText="The password must be numbers only.">
    <Parameters>
      <Parameter Id="RegularExpression">^[0-9]+$</Parameter>
    </Parameters>
  </Predicate>

  <Predicate Id="AllowedAADCharacters" Method="MatchesRegex" HelpText="An invalid character was provided.">
    <Parameters>
      <Parameter Id="RegularExpression">(^([0-9A-Za-z\d@#$%^&amp;*\-_+=[\]{}|\\:',?/`~"();! ]|(\.(?!@)))+$)|(^$)</Parameter>
    </Parameters>
  </Predicate>

  <Predicate Id="DisallowedWhitespace" Method="MatchesRegex" HelpText="The password must not begin or end with a whitespace character.">
    <Parameters>
      <Parameter Id="RegularExpression">(^\S.*\S$)|(^\S+$)|(^$)</Parameter>
    </Parameters>
  </Predicate>

定义基本验证后，你可以将它们组合在一起，并创建一组可以在策略中使用的密码策略：

SimplePassword 验证 DisallowedWhitespace、AllowedAADCharacters 和 IsLengthBetween8And64
StrongPassword 验证 DisallowedWhitespace、AllowedAADCharacters、IsLengthBetween8And64。最后一组 CharacterClasses 运行一组额外的谓词，其中 MatchAtLeast 设置为 3。用户密码长度必须为 8 到 16 个字符，且必须包含下列其中的三类字符：小写、大写、数字或符号。
CustomPassword 仅验证 DisallowedWhitespace 和 AllowedAADCharacters。因此，只要字符有效，用户可以提供任意长度的任何密码。

<PredicateValidations>
  <PredicateValidation Id="SimplePassword">
    <PredicateGroups>
      <PredicateGroup Id="DisallowedWhitespaceGroup">
        <PredicateReferences>
          <PredicateReference Id="DisallowedWhitespace" />
        </PredicateReferences>
      </PredicateGroup>
      <PredicateGroup Id="AllowedAADCharactersGroup">
        <PredicateReferences>
          <PredicateReference Id="AllowedAADCharacters" />
        </PredicateReferences>
      </PredicateGroup>
      <PredicateGroup Id="LengthGroup">
        <PredicateReferences>
          <PredicateReference Id="IsLengthBetween8And64" />
        </PredicateReferences>
      </PredicateGroup>
    </PredicateGroups>
  </PredicateValidation>

  <PredicateValidation Id="StrongPassword">
    <PredicateGroups>
      <PredicateGroup Id="DisallowedWhitespaceGroup">
        <PredicateReferences>
          <PredicateReference Id="DisallowedWhitespace" />
       </PredicateReferences>
      </PredicateGroup>
      <PredicateGroup Id="AllowedAADCharactersGroup">
        <PredicateReferences>
          <PredicateReference Id="AllowedAADCharacters" />
        </PredicateReferences>
      </PredicateGroup>
      <PredicateGroup Id="LengthGroup">
        <PredicateReferences>
          <PredicateReference Id="IsLengthBetween8And64" />
        </PredicateReferences>
      </PredicateGroup>
      <PredicateGroup Id="CharacterClasses">
        <UserHelpText>The password must have at least 3 of the following:</UserHelpText>
        <PredicateReferences MatchAtLeast="3">
          <PredicateReference Id="Lowercase" />
          <PredicateReference Id="Uppercase" />
          <PredicateReference Id="Number" />
          <PredicateReference Id="Symbol" />
        </PredicateReferences>
      </PredicateGroup>
    </PredicateGroups>
  </PredicateValidation>

  <PredicateValidation Id="CustomPassword">
    <PredicateGroups>
      <PredicateGroup Id="DisallowedWhitespaceGroup">
        <PredicateReferences>
          <PredicateReference Id="DisallowedWhitespace" />
        </PredicateReferences>
      </PredicateGroup>
      <PredicateGroup Id="AllowedAADCharactersGroup">
        <PredicateReferences>
          <PredicateReference Id="AllowedAADCharacters" />
        </PredicateReferences>
      </PredicateGroup>
    </PredicateGroups>
  </PredicateValidation>
</PredicateValidations>

在声明类型中，添加 PredicateValidationReference 元素，并将标识符指定为 SimplePassword、StrongPassword 或 CustomPassword 等谓词验证中的一个。

<ClaimType Id="password">
  <DisplayName>Password</DisplayName>
  <DataType>string</DataType>
  <AdminHelpText>Enter password</AdminHelpText>
  <UserHelpText>Enter password</UserHelpText>
  <UserInputType>Password</UserInputType>
  <PredicateValidationReference Id="StrongPassword" />
</ClaimType>

下面显示了当 Azure AD B2C 显示错误消息时元素的组织方式：

谓词和 PredicateGroup 密码复杂性示例的示意图

配置日期范围

借助 Predicates 和 PredicateValidations 元素，你可以通过使用 DateTimeDropdown 来控制 UserInputType 的最小和最大日期值。如下例所示，可使用 IsDateRange 方法创建 Predicate 并提供最小和最大参数。

<Predicates>
  <Predicate Id="DateRange" Method="IsDateRange" HelpText="The date must be between 01-01-1980 and today.">
    <Parameters>
      <Parameter Id="Minimum">1980-01-01</Parameter>
      <Parameter Id="Maximum">Today</Parameter>
    </Parameters>
  </Predicate>
</Predicates>

添加引用 DateRange 谓词的 PredicateValidation。

<PredicateValidations>
  <PredicateValidation Id="CustomDateRange">
    <PredicateGroups>
      <PredicateGroup Id="DateRangeGroup">
        <PredicateReferences>
          <PredicateReference Id="DateRange" />
        </PredicateReferences>
      </PredicateGroup>
    </PredicateGroups>
  </PredicateValidation>
</PredicateValidations>

在声明类型中，添加 PredicateValidationReference 元素，并将标识符指定为 CustomDateRange。

<ClaimType Id="dateOfBirth">
  <DisplayName>Date of Birth</DisplayName>
  <DataType>date</DataType>
  <AdminHelpText>The user's date of birth.</AdminHelpText>
  <UserHelpText>Your date of birth.</UserHelpText>
  <UserInputType>DateTimeDropdown</UserInputType>
  <PredicateValidationReference Id="CustomDateRange" />
</ClaimType>

后续步骤

了解如何通过谓词验证在 Azure Active Directory B2C 中使用自定义策略配置密码复杂性。

通过