Predicates 和 PredicateValidations

這很重要

自 2025 年 5 月 1 日起，Azure AD B2C 將不再可供新客戶購買。 在我們的常見問題中深入瞭解。

備註

在 Azure Active Directory B2C 中， 自定義原則 的設計主要是為了解決複雜的案例。 在大部分情況下，我們建議您使用內 建的使用者流程。 如果您尚未這麼做，請了解開始使用 Active Directory B2C 中的自定義原則入門套件。

的 Predicates 和 PredicateValidations 元素使您能夠執行驗證過程，以確保僅將格式正確的數據輸入到 Azure Active Directory B2C （Azure AD B2C） 租戶中。

下圖顯示了元素之間的關係：

謂詞

Predicate 元素定義基本驗證以檢查聲明類型的值，並傳回 true or false。 驗證是使用指定的 Method 元素和一組與方法相關的 Parameter 元素來完成的。 例如，謂詞可以檢查字串聲明值的長度是否在指定的最小和最大參數範圍內，或者字串聲明值是否包含字元集。 如果檢查失敗， UserHelpText 元素會向使用者提供錯誤消息。 UserHelpText 元素的值可以使用語言自定義進行當地語系化。

Predicates 元素必須直接出現在 BuildingBlocks 元素中的 ClaimsSchema 元素之後。

Predicates 元素包含以下元素：

元素	發生次數	說明
謂語	1：n	述詞的清單。

Predicate 元素包含以下屬性：

屬性	為必填項目	說明
身份識別碼	是的	用於謂詞的標識碼。 其他元素可以在原則中使用這個標識碼。
方法	是的	用於驗證的方法類型。 可能的值： IsLengthRange、 MatchesRegex、 IncludesCharacters 或 IsDateRange。
説明文本	否	檢查失敗時向用戶顯示錯誤訊息。 此字串可以使用語言自定義進行當地語系化

Predicate 元素包含以下元素：

元素	發生次數	說明
UserHelpText （使用者説明文字）	0:1	（已棄用）檢查失敗時向用戶顯示錯誤訊息。
參數	1:1	字串驗證的方法類型的參數。

Parameters 元素包含以下元素：

元素	發生次數	說明
參數	1：n	字串驗證的方法類型的參數。

Parameter 元素包含以下屬性：

元素	發生次數	說明
身份識別碼	1:1	參數的標識碼。

謂詞方法

IsLengthRange

IsLengthRange 方法檢查字串聲明值的長度是否在指定的最小和最大參數範圍內。 查看此謂詞方法的 Live 演示 。 predicate 元素支援以下參數：

參數	為必填項目	說明
最大值	是的	可輸入的最大字元數。
最小值	是的	必須輸入的最小字元數。

以下示例顯示了一個 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 方法檢查字串聲明值是否與正則表示式匹配。 查看此謂詞方法的 Live 演示 。 predicate 元素支援以下參數：

參數	為必填項目	說明
正則表達式	是的	要匹配的正則表示式模式。

以下範例顯示了一個 MatchesRegex 方法，該方法的參數 RegularExpression 指定了正則表示式：

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

包含角色

IncludesCharacters 方法檢查字串聲明值是否包含字元集。 查看此謂詞方法的 Live 演示 。 predicate 元素支援以下參數：

參數	為必填項目	說明
字元集	是的	可以輸入的字元集。 例如， lowercase characters a-z、 uppercase characters A-Z、 digits 0-9或符號列表，如 @#$%^&*\-_+=[]{}|\\:',?/~"();!.

以下範例顯示了一個 IncludesCharacters 方法，該方法的參數 CharacterSet 用於指定字元集：

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

IsDateRange

IsDateRange 方法檢查日期聲明值是否介於指定的最小和最大參數範圍之間。 查看此謂詞方法的 Live 演示 。 predicate 元素支援以下參數：

參數	為必填項目	說明
最大值	是的	可以輸入的最大可能日期。 日期的格式遵循 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 元素包含以下屬性：

屬性	為必填項目	說明
身份識別碼	是的	用於謂詞驗證的標識碼。 ClaimType 元素可以在策略中使用此標識符。

PredicateValidation 元素包含以下元素：

元素	發生次數	說明
謂詞組	1：n	謂片語的清單。

PredicateGroups 元素包含以下元素：

元素	發生次數	說明
PredicateGroup	1：n	述詞的清單。

PredicateGroup 元素包含以下屬性：

屬性	為必填項目	說明
身份識別碼	是的	用於謂片語的標識碼。

PredicateGroup 元素包含以下元素：

元素	發生次數	說明
UserHelpText （使用者説明文字）	0:1	謂詞的描述，有助於使用者了解他們應該鍵入的值。
PredicateReferences	1：n	謂詞引用清單。

PredicateReferences 元素包含以下屬性：

屬性	為必填項目	說明
MatchAtLeast （匹配最小）	否	指定該值必須至少與該數量的謂詞定義匹配，才能接受輸入。 如果未指定，則該值必須與所有謂詞定義匹配。

PredicateReferences 元素包含以下元素：

元素	發生次數	說明
PredicateReference （謂詞引用）	1：n	對謂詞的引用。

PredicateReference 元素包含以下屬性：

屬性	為必填項目	說明
身份識別碼	是的	用於謂詞驗證的標識碼。

設定密碼複雜度

使用 Predicates 和 PredicateValidationsInput ，您可以控制使用者在創建帳戶時提供的密碼的複雜性要求。 默認情況下，Azure AD B2C 使用強密碼。 Azure AD B2C 也支援組態選項，以控制客戶可以使用的密碼複雜度。 您可以使用以下謂詞元素定義密碼複雜性：

• IsLengthBetween8And64 驗證 IsLengthRange 密碼是否必須介於 8 到 64 個字元之間。
• 使用該方法IncludesCharacters 驗證密碼是否包含小寫字母。
• Uppercase 使用該方法 IncludesCharacters ，驗證密碼是否包含大寫字母。
• Number 使用該方法 IncludesCharacters 驗證密碼是否包含數位。
• Symbol 使用該方法 IncludesCharacters ，驗證密碼是否包含多個 symbol 字元之一。
• 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 運行一組設置為 3 的附加謂詞 MatchAtLeast 。 用戶密碼必須介於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 顯示錯誤訊息時如何組織元素：

配置日期範圍

使用 Predicates 和 PredicateValidations 元素，您可以使用 .DateTimeDropdown 為此，請使用該方法創建 IsDateRange 並提供 minimum 和 maximum 參數。

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

添加一個 PredicateValidation 並引用該 DateRange 謂詞。

<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 中使用自定義策略配置密碼複雜性 。