Predicates 和 PredicateValidationsPredicates and PredicateValidations

备注

在 Azure Active Directory B2C 中,custom policies 主要用于解决复杂方案。In Azure Active Directory B2C, custom policies are designed primarily to address complex scenarios. 大多数情况下,建议使用内置的用户流For most scenarios, we recommend that you use built-in user flows.

Predicates 和 PredicateValidations 元素可用于执行验证过程,以确保向 Azure Active Directory B2C (Azure AD B2C) 租户仅输入正确格式的数据。The Predicates and PredicateValidations elements enable you to perform a validation process to ensure that only properly formed data is entered into your Azure Active Directory B2C (Azure AD B2C) tenant.

以下图示显示了元素之间的关系:The following diagram shows the relationship between the elements:

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

谓词Predicates

Predicate 元素定义基本验证,用以检查声明类型的值并返回 truefalseThe Predicate element defines a basic validation to check the value of a claim type and returns true or false. 可通过使用指定的 Method 元素和一组与该方法相关的 Parameter 元素来完成验证。The validation is done by using a specified Method element and a set of Parameter elements relevant to the method. 例如,谓词可以检查字符串声明值的长度是否在指定的最小和最大参数范围内,或者字符串声明值是否包含字符集。For example, a predicate can check whether the length of a string claim value is within the range of minimum and maximum parameters specified, or whether a string claim value contains a character set. 如果检查失败,UserHelpText 元素将为用户提供一条错误消息。The UserHelpText element provides an error message for users if the check fails. UserHelpText 元素的值可以使用语言自定义进行本地化。The value of UserHelpText element can be localized using language customization.

Predicates 元素必须紧跟在 BuildingBlocks 元素中的 ClaimsSchema 元素之后。The Predicates element must appear directly following the ClaimsSchema element within the BuildingBlocks element.

Predicates 元素包含以下元素:The Predicates element contains the following element:

元素Element 出现次数Occurrences 说明Description
PredicatePredicate 1:n1:n 谓词列表。A list of predicates.

Predicate 元素包含以下属性:The Predicate element contains the following attributes:

属性Attribute 必须Required 说明Description
IDId Yes 用于谓词的标识符。An identifier that's used for the predicate. 其他元素可以在策略中使用此标识符。Other elements can use this identifier in the policy.
方法Method Yes 用于验证的方法类型。The method type to use for validation. 可能的值:IsLengthRangeMatchesRegexIncludesCharactersIsDateRangePossible values: IsLengthRange, MatchesRegex, IncludesCharacters, or IsDateRange.
HelpTextHelpText No 检查失败时向用户发送的错误消息。An error message for users if the check fails. 此字符串可以使用语言自定义进行本地化This string can be localized using the language customization

Predicate 元素包含以下元素:The Predicate element contains the following elements:

元素Element 出现次数Occurrences 说明Description
UserHelpTextUserHelpText 0:10:1 (已弃用)检查失败时向用户显示的错误消息。(Deprecated) An error message for users if the check fails.
parametersParameters 1:11:1 用于字符串验证的方法类型参数。The parameters for the method type of the string validation.

Parameters 元素包含以下元素:The Parameters element contains the following elements:

元素Element 出现次数Occurrences 说明Description
参数Parameter 1:n1:n 用于字符串验证的方法类型参数。The parameters for the method type of the string validation.

Parameter 元素包含以下属性:The Parameter element contains the following attributes:

元素Element 出现次数Occurrences 说明Description
IDId 1:11:1 该参数的标识符。The identifier of the parameter.

谓词方法Predicate methods

IsLengthRangeIsLengthRange

IsLengthRange 方法检查字符串声明值的长度是否在指定的最小和最大参数的范围内。The IsLengthRange method checks whether the length of a string claim value is within the range of minimum and maximum parameters specified. 谓词元素支持以下参数:The predicate element supports the following parameters:

参数Parameter 必需Required 说明Description
最大值Maximum Yes 可输入的最大字符数。The maximum number of characters that can be entered.
最小值Minimum Yes 必须输入的最小字符数。The minimum number of characters that must be entered.

下面的示例说明 IsLengthRange 方法使用参数 MinimumMaximum 指定字符串的长度范围:The following example shows a IsLengthRange method with the parameters Minimum and Maximum that specify the length range of the string:

<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>

MatchesRegexMatchesRegex

MatchesRegex 方法检查字符串声明值是否与正则表达式相匹配。The MatchesRegex method checks whether a string claim value matches a regular expression. 谓词元素支持以下参数:The predicate element supports the following parameters:

参数Parameter 必需Required 说明Description
RegularExpressionRegularExpression Yes 要匹配的正则表达式模式。The regular expression pattern to match.

下面的示例说明 MatchesRegex 方法使用参数 RegularExpression 指定正则表达式:The following example shows a MatchesRegex method with the parameter RegularExpression that specifies a regular expression:

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

IncludesCharactersIncludesCharacters

IncludesCharacters 方法检查字符串声明值是否包含字符集。The IncludesCharacters method checks whether a string claim value contains a character set. 谓词元素支持以下参数:The predicate element supports the following parameters:

参数Parameter 必需Required 说明Description
CharacterSetCharacterSet Yes 可输入的字符集。The set of characters that can be entered. 例如,小写字符 a-z、大写字符 A-Z、数字 0-9,或 @#$%^&amp;*\-_+=[]{}|\\:',?/~"();! 等一系列符号。For example, lowercase characters a-z, uppercase characters A-Z, digits 0-9, or a list of symbols, such as @#$%^&amp;*\-_+=[]{}|\\:',?/~"();!.

下面的示例说明 IncludesCharacters 方法使用参数 CharacterSet 指定字符集:The following example shows a IncludesCharacters method with the parameter CharacterSet that specifies the set of characters:

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

IsDateRangeIsDateRange

IsDateRange 方法检查日期声明值是否在指定的最小和最大参数范围内。The IsDateRange method checks whether a date claim value is between a range of minimum and maximum parameters specified. 谓词元素支持以下参数:The predicate element supports the following parameters:

参数Parameter 必需Required 说明Description
最大值Maximum Yes 可输入的最大日期。The largest possible date that can be entered. 日期格式遵循 yyyy-mm-dd 约定或 TodayThe format of the date follows yyyy-mm-dd convention, or Today.
最小值Minimum Yes 可输入的最小日期。The smallest possible date that can be entered. 日期格式遵循 yyyy-mm-dd 约定或 TodayThe format of the date follows yyyy-mm-dd convention, or Today.

下面的示例说明 IsDateRange 方法使用参数 MinimumMaximum 指定格式为 yyyy-mm-ddToday 的日期范围。The following example shows a IsDateRange method with the parameters Minimum and Maximum that specify the date range with a format of yyyy-mm-dd and 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>

PredicateValidationsPredicateValidations

尽管谓词定义了根据声明类型进行检查的验证,但是 PredicateValidations 会对一组谓词进行分组,以构成可应用于声明类型的用户输入验证。While the predicates define the validation to check against a claim type, the PredicateValidations group a set of predicates to form a user input validation that can be applied to a claim type. 每个 PredicateValidation 元素均包含一组 PredicateGroup 元素,其中包含一组指向 Predicate 的 PredicateReference 元素。Each PredicateValidation element contains a set of PredicateGroup elements that contain a set of PredicateReference elements that points to a Predicate. 为了通过验证,声明的值应通过所有 PredicateGroup 下的任何谓词的全部测试,及其包含的一组 PredicateReference 元素。To pass the validation, the value of the claim should pass all of the tests of any predicate under all of the PredicateGroup with their set of PredicateReference elements.

PredicateValidations 元素必须紧跟在 BuildingBlocks 元素中的 Predicates 元素之后。The PredicateValidations element must appear directly following the Predicates element within the BuildingBlocks element.

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

PredicateValidations 元素包含以下元素:The PredicateValidations element contains the following element:

元素Element 出现次数Occurrences 说明Description
PredicateValidationPredicateValidation 1:n1:n 谓词验证列表。A list of predicate validation.

PredicateValidation 元素包含以下属性:The PredicateValidation element contains the following attribute:

属性Attribute 必须Required 说明Description
IDId Yes 用于谓词验证的标识符。An identifier that's used for the predicate validation. ClaimType 元素可以在策略中使用此标识符。The ClaimType element can use this identifier in the policy.

PredicateValidation 元素包含以下元素:The PredicateValidation element contains the following element:

元素Element 出现次数Occurrences 说明Description
PredicateGroupsPredicateGroups 1:n1:n 谓词组列表。A list of predicate groups.

PredicateGroups 元素包含以下元素:The PredicateGroups element contains the following element:

元素Element 出现次数Occurrences 说明Description
PredicateGroupPredicateGroup 1:n1:n 谓词列表。A list of predicates.

PredicateGroup 元素包含以下属性:The PredicateGroup element contains the following attribute:

属性Attribute 必须Required 说明Description
IDId Yes 用于谓词组的标识符。An identifier that's used for the predicate group.

PredicateGroup 元素包含以下元素:The PredicateGroup element contains the following elements:

元素Element 出现次数Occurrences 说明Description
UserHelpTextUserHelpText 0:10:1 谓词的说明,可以帮助用户了解应键入哪些值。A description of the predicate that can be helpful for users to know what value they should type.
PredicateReferencesPredicateReferences 1:n1:n 谓词引用的列表。A list of predicate references.

PredicateReferences 元素包含以下属性:The PredicateReferences element contains the following attributes:

属性Attribute 必须Required 说明Description
MatchAtLeastMatchAtLeast No 指定该值针对要接受的输入必须至少匹配多个谓词定义。Specifies that the value must match at least that many predicate definitions for the input to be accepted. 如果未指定,则该值必须与所有谓词定义匹配。If not specified, the value must match all predicate definitions.

PredicateReferences 元素包含以下元素:The PredicateReferences element contains the following elements:

元素Element 出现次数Occurrences 说明Description
PredicateReferencePredicateReference 1:n1:n 对谓词的引用。A reference to a predicate.

PredicateReference 元素包含以下属性:The PredicateReference element contains the following attributes:

属性Attribute 必须Required 说明Description
IDId Yes 用于谓词验证的标识符。An identifier that's used for the predicate validation.

配置密码复杂性Configure password complexity

使用 Predicates 和 PredicateValidationsInput,可以在创建帐户时控制用户提供的密码的复杂性要求。With Predicates and PredicateValidationsInput you can control the complexity requirements for passwords provided by a user when creating an account. 默认情况下,Azure AD B2C 使用强密码。By default, Azure AD B2C uses strong passwords. 此外,Azure AD B2C 还支持用于控制客户可以使用的密码复杂性的配置选项。Azure AD B2C also supports configuration options to control the complexity of passwords that customers can use. 你可以使用这些谓词元素来定义密码的复杂性:You can define password complexity by using these predicate elements:

  • IsLengthBetween8And64 使用 IsLengthRange 方法,验证密码必须介于 8 到 64 个字符之间。IsLengthBetween8And64 using the IsLengthRange method, validates that the password must be between 8 and 64 characters.
  • Lowercase 使用 IncludesCharacters 方法,验证密码包含一个小写字母。Lowercase using the IncludesCharacters method, validates that the password contains a lowercase letter.
  • Uppercase 使用 IncludesCharacters 方法,验证密码包含一个大写字母。Uppercase using the IncludesCharacters method, validates that the password contains an uppercase letter.
  • Number 使用 IncludesCharacters 方法,验证密码包含一个数字。Number using the IncludesCharacters method, validates that the password contains a digit.
  • Symbol 使用 IncludesCharacters 方法验证密码是否包含几个符号字符之一。Symbol using the IncludesCharacters method, validates that the password contains one of several symbol characters.
  • PIN 使用 MatchesRegex 方法,验证密码仅包含数字。PIN using the MatchesRegex method, validates that the password contains numbers only.
  • AllowedAADCharacters 使用 MatchesRegex 方法,验证提供了仅限密码的无效字符。AllowedAADCharacters using the MatchesRegex method, validates that the password only invalid character was provided.
  • DisallowedWhitespace 使用 MatchesRegex 方法,验证密码不以空格字符开头或结尾。DisallowedWhitespace using the MatchesRegex method, validates that the password doesn't begin or end with a whitespace character.
<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>

定义基本验证后,你可以将它们组合在一起,并创建一组可以在策略中使用的密码策略:After you define the basic validations, you can combine them together and create a set of password policies that you can use in your policy:

  • SimplePassword 验证 DisallowedWhitespace、AllowedAADCharacters 和 IsLengthBetween8And64SimplePassword validates the DisallowedWhitespace, AllowedAADCharacters, and IsLengthBetween8And64
  • StrongPassword 验证 DisallowedWhitespace、AllowedAADCharacters、IsLengthBetween8And64。StrongPassword validates the DisallowedWhitespace, AllowedAADCharacters, IsLengthBetween8And64. 最后一组 CharacterClasses 运行一组额外的谓词,其中 MatchAtLeast 设置为 3。The last group CharacterClasses runs an additional set of predicates with MatchAtLeast set to 3. 用户密码长度必须为 8 到 16 个字符,且必须包含下列其中的三类字符:小写、大写、数字或符号。The user password must be between 8 and 16 characters, and three of the following characters: Lowercase, Uppercase, Number, or Symbol.
  • CustomPassword 仅验证 DisallowedWhitespace 和 AllowedAADCharacters。CustomPassword validates only DisallowedWhitespace, AllowedAADCharacters. 因此,只要字符有效,用户可以提供任意长度的任何密码。So, user can provide any password with any length, as long as the characters are valid.
<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 等谓词验证中的一个。In your claim type, add the PredicateValidationReference element and specify the identifier as one of the predicate validations, such as SimplePassword, StrongPassword, or 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 显示错误消息时元素的组织方式:The following shows how the elements are organized when Azure AD B2C displays the error message:

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

配置日期范围Configure a date range

借助 Predicates 和 PredicateValidations 元素,你可以通过使用 DateTimeDropdown 来控制 UserInputType 的最小和最大日期值。With the Predicates and PredicateValidations elements you can control the minimum and maximum date values of the UserInputType by using a DateTimeDropdown. 如下例所示,可使用 IsDateRange 方法创建 Predicate 并提供最小和最大参数。To do this, create a Predicate with the IsDateRange method and provide the minimum and maximum parameters.

<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。Add a PredicateValidation with a reference to the DateRange predicate.

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

在声明类型中,添加 PredicateValidationReference 元素,并将标识符指定为 CustomDateRangeIn your claim type, add PredicateValidationReference element and specify the identifier as 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>