述詞和述詞Validations

發行項
05/24/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 元素包含下列元素：

元素	發生次數	描述
述詞	1：n	述詞的清單。

Predicate 元素包含下列屬性：

屬性	必要	描述
Id	Yes	用於述詞的標識碼。其他元素可以在原則中使用這個標識碼。
方法	Yes	要用於驗證的方法型別。可能的值：IsLengthRange、MatchesRegex 、IncludesCharacters 或 IsDateRange。
HelpText	No	檢查失敗時，使用者會收到錯誤訊息。此字串可以使用語言自定義進行當地語系化

Predicate 元素包含下列元素：

元素	發生次數	描述
UserHelpText	0:1	（已淘汰）檢查失敗時，使用者會收到錯誤訊息。
參數	1:1	字串驗證之方法類型的參數。

Parameters 元素包含下列元素：

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

Parameter 元素包含下列屬性：

元素	發生次數	描述
Id	1:1	參數的標識碼。

述詞方法

IsLengthRange

IsLengthRange 方法會檢查字串宣告值的長度是否在指定的最小和最大參數範圍內。請查看這個述詞方法的 Live 示範。述字項目支援下列參數：

參數	必要	描述
最大值	Yes	可以輸入的最大字元數。
最小值	Yes	必須輸入的字元數下限。

下列範例顯示具有參數 Minimum 的IsLengthRange方法，並 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 示範。述字項目支援下列參數：

參數	必要	描述
RegularExpression	Yes	要比對的規則運算式模式。

下列範例顯示 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 方法會檢查字串宣告值是否包含字元集。請查看這個述詞方法的 Live 示範。述字項目支援下列參數：

參數	必要	描述
CharacterSet	Yes	可以輸入的字元集。例如，小寫字元、大寫字元`a-zA-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 方法會檢查日期宣告值是否介於指定之最小和最大參數的範圍之間。請查看這個述詞方法的 Live 示範。述字項目支援下列參數：

參數	必要	描述
最大值	Yes	可輸入的最大可能日期。日期格式遵循 `yyyy-mm-dd` 慣例或 `Today`。
最小值	Yes	可輸入的最小可能日期。日期格式遵循 `yyyy-mm-dd` 慣例或 `Today`。

下列範例顯示IsDateRange具有參數Minimum的方法，並Maximum指定具有和 Today格式的yyyy-mm-dd日期範圍。

<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 元素。若要通過驗證，宣告的值應該會使用其一組 PredicateReference 元素，在所有 PredicateGroup 下傳遞所有述詞的所有測試。

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	Yes	用於述詞驗證的標識碼。 ClaimType 元素可以在原則中使用這個標識符。

PredicateValidation 元素包含下列元素：

元素	發生次數	描述
PredicateGroups	1：n	述詞群組的清單。

PredicateGroups 元素包含下列元素：

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

PredicateGroup 元素包含下列屬性：

屬性	必要	描述
Id	Yes	用於述詞群組的標識碼。

PredicateGroup 元素包含下列元素：

元素	發生次數	描述
UserHelpText	0:1	述詞的描述，可協助使用者知道他們應該輸入的值。
PredicateReferences	1：n	述詞參考的清單。

PredicateReferences 元素包含下列屬性：

屬性	必要	描述
MatchAtLeast	No	指定值必須至少符合要接受輸入的許多述詞定義。如果未指定，值必須符合所有述詞定義。

PredicateReferences 元素包含下列元素：

元素	發生次數	描述
PredicateReference	1：n	述詞的參考。

PredicateReference 元素包含下列屬性：

屬性	必要	描述
Id	Yes	用於述詞驗證的標識碼。

設定密碼複雜度

使用 Predicates 和 PredicateValidationsInput ，您可以在建立帳戶時控制使用者提供之密碼的複雜度需求。根據預設，Azure AD B2C 會使用強密碼。 Azure AD B2C 也支援組態選項，以控制客戶可以使用的密碼複雜度。您可以使用下列述字元素來定義密碼複雜性：

IsLengthBetween8And64 使用 IsLengthRange 方法，驗證密碼必須介於 8 到 64 個字元之間。
使用方法小IncludesCharacters寫，驗證密碼是否包含小寫字母。
使用方法的大IncludesCharacters寫，驗證密碼是否包含大寫字母。
使用 IncludesCharacters 方法的數字，驗證密碼是否包含數位。
使用方法的IncludesCharacters符號，驗證密碼是否包含數個符號字元之一。
使用方法的 MatchesRegex PIN，驗證密碼是否只包含數位。
AllowedAADCharacters 使用 MatchesRegex 方法，驗證密碼只提供無效的字元。
不允許使用 MatchesRegex 方法的Whitespace，驗證密碼不是以空格符開頭或結尾。

<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 元素，您可以使用來控制 UserInputType DateTimeDropdown的最小值和最大值。若要這樣做，請使用 IsDateRange 方法建立述詞，並提供最小和最大參數。

<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 中使用自定義原則設定密碼複雜度。

共用方式為