ClaimsSchema

文章
07/17/2024

注意

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

ClaimsSchema 元素會定義可當作原則一部分進行參考的宣告類型。宣告結構描述是可在其中宣告您的宣告的位置。宣告可以是名字、姓氏、顯示名稱、電話號碼等等。 ClaimsSchema 元素包含 ClaimType 元素的清單。 ClaimType 元素包含Id屬性，也就是宣告名稱。

<BuildingBlocks>
  <ClaimsSchema>
    <ClaimType Id="Id">
      <DisplayName>Surname</DisplayName>
      <DataType>string</DataType>
      <DefaultPartnerClaimTypes>
        <Protocol Name="OAuth2" PartnerClaimType="family_name" />
        <Protocol Name="OpenIdConnect" PartnerClaimType="family_name" />
        <Protocol Name="SAML2" PartnerClaimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" />
      </DefaultPartnerClaimTypes>
      <UserHelpText>Your surname (also known as family name or last name).</UserHelpText>
      <UserInputType>TextBox</UserInputType>

ClaimType

ClaimType 元素包含下列屬性：

屬性	必要	描述
Id	Yes	用於宣告類型的識別碼。其他元素可以在原則中使用這個標識碼。

ClaimType 元素包含下列元素：

元素	發生次數	描述
DisplayName	1:1	在各種畫面上向用戶顯示的標題。此值可以當地語系化。
DataType	1:1	宣告的類型。
DefaultPartnerClaimTypes	0:1	要用於指定通訊協議的夥伴預設宣告類型。您可以在 InputClaim 或 OutputClaim 元素中指定的 PartnerClaimType 中覆寫此值。使用這個專案來指定通訊協議的預設名稱。
遮罩	0:1	顯示宣告時可以套用的選擇性遮罩字元字串。例如，電話號碼 324-232-4343 可以遮罩為 XXX-XXX-4343。
UserHelpText	0:1	宣告類型的描述，可協助用戶瞭解其用途。此值可以當地語系化。
UserInputType	0:1	手動輸入宣告類型的宣告數據時，用戶應該可以使用的輸入控件類型。請參閱此頁面稍後定義的使用者輸入類型。
AdminHelpText	0:1	宣告類型的描述，可讓系統管理員瞭解其用途。
限制	0:1	此宣告的值限制，例如正則表達式（Regex）或可接受的值清單。此值可以當地語系化。
PredicateValidationReference	0:1	PredicateValidationsInput 元素的參考。 PredicateValidationReference 元素可讓您執行驗證程式，以確保只輸入正確的格式數據。如需詳細資訊，請參閱述詞。

DataType

DataType 元素支援下列值：

類型	描述
boolean	代表布林值 (`true` 或 `false`)。
date	表示時間的瞬間，通常以一天的日期表示。日期的值遵循 ISO 8601 慣例。
dateTime	表示時間的瞬間，通常以一天的日期和時間表示。在運行時間期間，日期的值會遵循 ISO 8601 慣例，並轉換成 UNIX epoch 時間，當做宣告發行至令牌時。
duration	表示以年、月、天、小時、分鐘和秒為單位的時間間隔。的格式為 `PnYnMnDTnHnMnS`，其中 `P` 表示正值或 `N` 負值。 `nY` 是後面接著常值 `Y`的年數。 `nMo` 是後面接著常值 `Mo`的月份數。 `nD` 是後面接著常值 `D`的天數。範例： `P21Y` 代表 21 年。 `P1Y2Mo` 代表一年和兩個月。 `P1Y2Mo5D` 代表一年、兩個月和五天。 `P1Y2M5DT8H5M20S` 代表一年、兩個月、五天、八小時、五分鐘和二十秒。
電話號碼	表示電話號碼。
int	表示介於 -2,147,483,648 和 2,147,483,647 之間的數位
long	代表介於 -9,223,372,036,854,775,808 到 9,223,372,036,854,775,807 之間的數位
字串	以一連串的 UTF-16 字碼單位表示文字。
stringCollection	代表 `string` 的集合。
userIdentity	表示使用者身分識別。
userIdentityCollection	代表 `userIdentity` 的集合。

DefaultPartnerClaimTypes

DefaultPartnerClaimTypes 可能包含下列元素：

元素	發生次數	描述
通訊協定	1：n	具有預設夥伴宣告類型名稱的通訊協定清單。

Protocol 元素包含下列屬性：

屬性	必要	描述
姓名	Yes	Azure AD B2C 支援的有效通訊協定名稱。可能的值為：OAuth1、OAuth2、SAML2、OpenIdConnect。
PartnerClaimType	Yes	要使用的宣告類型名稱。

在下列範例中，當 Identity Experience Framework 與 SAML2 識別提供者或信賴憑證者應用程式互動時，姓氏宣告會對應至 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname，而 OpenIdConnect 和 OAuth2 則宣告會對應至 family_name。

<ClaimType Id="surname">
  <DisplayName>Surname</DisplayName>
  <DataType>string</DataType>
  <DefaultPartnerClaimTypes>
    <Protocol Name="OAuth2" PartnerClaimType="family_name" />
    <Protocol Name="OpenIdConnect" PartnerClaimType="family_name" />
    <Protocol Name="SAML2" PartnerClaimType="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" />
  </DefaultPartnerClaimTypes>
</ClaimType>

因此，Azure AD B2C 所發出的 JWT 令牌會發出 family_name ，而不是 ClaimType 名稱姓氏。

{
  "sub": "6fbbd70d-262b-4b50-804c-257ae1706ef2",
  "auth_time": 1535013501,
  "given_name": "David",
  "family_name": "Williams",
  "name": "David Williams",
}

遮罩

Mask 元素包含下列屬性：

屬性	必要	描述:
`Type`	Yes	宣告遮罩的類型。可能的值： `Simple` 或 `Regex`。值 `Simple` 表示簡單的文字遮罩會套用至字串宣告的前置部分。值 `Regex` 表示正則表達式會套用至整個字串宣告。如果指定了 `Regex` 值，也必須使用正則表達式來定義選擇性屬性。
`Regex`	No	如果 `Type` 設定為 `Regex`，請指定要使用的正則表示式。

下列範例會設定具有遮罩的 Simple PhoneNumber 宣告。如需更多範例，請參閱宣告簡單遮罩實時示範。

<ClaimType Id="PhoneNumber">
  <DisplayName>Phone Number</DisplayName>
  <DataType>string</DataType>
  <Mask Type="Simple">XXX-XXX-</Mask>
  <UserHelpText>Your telephone number.</UserHelpText>
</ClaimType>

身分識別體驗架構會在隱藏前六位數時轉譯電話號碼：

瀏覽器中顯示的電話號碼宣告，前六個數位被 X 遮罩

下列範例會設定具有遮罩的 Regex AlternateEmail 宣告。如需更多範例，請參閱 Regex mask 實時示範。

<ClaimType Id="AlternateEmail">
  <DisplayName>Please verify the secondary email linked to your account</DisplayName>
  <DataType>string</DataType>
  <Mask Type="Regex" Regex="(?&lt;=.).(?=.*@)">*</Mask>
  <UserInputType>Readonly</UserInputType>
</ClaimType>

身分辨識體驗架構只會轉譯電子郵件位址的第一個字母和電子郵件功能變數名稱：

瀏覽器中顯示的電子郵件宣告，其中包含以星號遮罩的字元

限制

Restriction 元素可能包含下列屬性：

屬性	必要	描述
MergeBehavior	No	方法，用來將列舉值與具有相同標識符之父原則中的 ClaimType 合併。當您覆寫基底原則中指定的宣告時，請使用這個屬性。可能的值：`Append`、`Prepend` 或 `ReplaceAll`。值 `Append` 是應該附加至父原則中所指定集合結尾的數據集合集合。值 `Prepend` 是應該在父原則中指定的集合之前加入的數據集合。值 `ReplaceAll` 是父原則中指定的數據集合，應該予以忽略。

Restriction 元素包含下列元素：

元素	發生次數	描述
列舉型別	1：n	使用者介面中可供用戶選取宣告的選項，例如下拉式清單中的值。
模式	1:1	要使用的正則表達式。

列舉型別

Enumeration 元素會定義使用者為使用者介面中宣告選取的可用選項，例如、 DropdownSingleSelect或RadioSingleSelect中的CheckboxMultiSelect值。或者，您可以使用 LocalizedCollections 元素來定義和當地語系化可用的選項。若要從宣告列舉集合查閱專案，請使用 GetMappedValueFromLocalizedCollection 宣告轉換。

Enumeration 元素包含下列屬性：

屬性	必要	描述
Text	Yes	這個選項的使用者介面中向用戶顯示的顯示字串。
值	Yes	與選取此選項相關聯的宣告值。
SelectByDefault	No	指出是否應該在UI中預設選取此選項。可能的值：True 或 False。

下列範例會 設定城市 下拉式清單宣告，並將預設值設定為 New York。如需更多範例，請參閱宣告限制列舉實時示範。

<ClaimType Id="city">
  <DisplayName>city where you work</DisplayName>
  <DataType>string</DataType>
  <UserInputType>DropdownSingleSelect</UserInputType>
  <Restriction>
    <Enumeration Text="Bellevue" Value="bellevue" SelectByDefault="false" />
    <Enumeration Text="Redmond" Value="redmond" SelectByDefault="false" />
    <Enumeration Text="New York" Value="new-york" SelectByDefault="true" />
  </Restriction>
</ClaimType>

下拉式清單，預設值設定為紐約：

在瀏覽器中呈現的下拉式控制項，並顯示預設值

模式

Pattern 元素可以包含下列屬性：

屬性	必要	描述
RegularExpression	Yes	這個型別宣告的正則表達式必須符合才能有效。
HelpText	No	如果正則表達式檢查失敗，使用者會收到錯誤訊息。

下列範例會 使用正規表示式輸入驗證和說明文字來設定電子郵件 宣告：

<ClaimType Id="email">
  <DisplayName>Email Address</DisplayName>
  <DataType>string</DataType>
  <DefaultPartnerClaimTypes>
  <Protocol Name="OpenIdConnect" PartnerClaimType="email" />
  </DefaultPartnerClaimTypes>
  <UserHelpText>Email address that can be used to contact you.</UserHelpText>
  <UserInputType>TextBox</UserInputType>
  <Restriction>
    <Pattern RegularExpression="^[a-zA-Z0-9.+!#$%&amp;'+^_`{}~-]+(?:\.[a-zA-Z0-9!#$%&amp;'+^_`{}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$" HelpText="Please enter a valid email address." />
  </Restriction>
</ClaimType>

身分辨識體驗架構會使用電子郵件格式輸入驗證來轉譯電子郵件位址宣告：

TextBox 顯示由 regex 限制觸發的錯誤訊息

UserInputType

Azure AD B2C 支援各種不同的使用者輸入類型，例如文本框、密碼和下拉式清單，可在手動輸入宣告類型的宣告數據時使用。當您使用自我判斷技術配置檔和顯示控件，從使用者收集資訊時，您必須指定 UserInputType。

查看使用者輸入類型的實時示範。

UserInputType 元素可用的使用者輸入類型：

UserInputType	支援的 ClaimType	描述
CheckboxMultiSelect	`string`	多重選取下拉式方塊。宣告值會以所選值的逗號分隔符字串表示。
DateTimeDropdown	`date`, `dateTime`	下拉式清單以選取一天、月和年。
DropdownSingleSelect	`string`	單一選取下拉式方塊。宣告值是選取的值。
EmailBox	`string`	電子郵件輸入欄位。
段落	`boolean`、`date`、、`durationdateTime`、`int`、、、 `longstring`	只顯示段落標記中文字的欄位。
密碼	`string`	密碼文字框。
RadioSingleSelect	`string`	單選按鈕的集合。宣告值是選取的值。
唯讀	`boolean`、`date`、、`durationdateTime`、`int`、、、 `longstring`	唯讀文字框。
TextBox	`boolean`、、 `int`、 `phoneNumberstring`	單行文字框。

TextBox

TextBox 使用者輸入類型可用來提供單行文本框。

TextBox 顯示宣告類型中指定的屬性

<ClaimType Id="displayName">
  <DisplayName>Display Name</DisplayName>
  <DataType>string</DataType>
  <UserHelpText>Your display name.</UserHelpText>
  <UserInputType>TextBox</UserInputType>
</ClaimType>

EmailBox

EmailBox 使用者輸入類型可用來提供基本電子郵件輸入欄位。

EmailBox 顯示宣告類型中指定的屬性

<ClaimType Id="email">
  <DisplayName>Email Address</DisplayName>
  <DataType>string</DataType>
  <UserHelpText>Email address that can be used to contact you.</UserHelpText>
  <UserInputType>EmailBox</UserInputType>
  <Restriction>
    <Pattern RegularExpression="^[a-zA-Z0-9.+!#$%&amp;'+^_`{}~-]+(?:\.[a-zA-Z0-9!#$%&amp;'+^_`{}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$" HelpText="Please enter a valid email address." />
  </Restriction>
</ClaimType>

密碼

密碼使用者輸入類型用來記錄使用者輸入的密碼。

搭配密碼使用宣告類型

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

DateTimeDropdown

DateTimeDropdown 使用者輸入類型可用來提供一組下拉式清單來選取一天、月和年。您可以使用 Predicates 和 PredicateValidations 元素來控制最小和最大日期值。如需詳細資訊，請參閱 Predicates 和 PredicateValidations 的設定日期範圍一節。

搭配 datetimedropdown 使用宣告類型

<ClaimType Id="dateOfBirth">
  <DisplayName>Date Of Birth</DisplayName>
  <DataType>date</DataType>
  <UserHelpText>The date on which you were born.</UserHelpText>
  <UserInputType>DateTimeDropdown</UserInputType>
</ClaimType>

RadioSingleSelect

RadioSingleSelect 使用者輸入類型可用來提供單選按鈕集合，讓用戶選取一個選項。

搭配 radiodsingleselect 使用宣告類型

<ClaimType Id="color">
  <DisplayName>Preferred color</DisplayName>
  <DataType>string</DataType>
  <UserInputType>RadioSingleSelect</UserInputType>
  <Restriction>
    <Enumeration Text="Blue" Value="Blue" SelectByDefault="false" />
    <Enumeration Text="Green " Value="Green" SelectByDefault="false" />
    <Enumeration Text="Orange" Value="Orange" SelectByDefault="true" />
  </Restriction>
</ClaimType>

DropdownSingleSelect

DropdownSingleSelect 使用者輸入類型可用來提供一個下拉式方塊，讓用戶選取一個選項。

搭配下拉式清單選取使用宣告類型

<ClaimType Id="city">
  <DisplayName>City where you work</DisplayName>
  <DataType>string</DataType>
  <UserInputType>DropdownSingleSelect</UserInputType>
  <Restriction>
    <Enumeration Text="Bellevue" Value="bellevue" SelectByDefault="false" />
    <Enumeration Text="Redmond" Value="redmond" SelectByDefault="false" />
    <Enumeration Text="New York" Value="new-york" SelectByDefault="true" />
  </Restriction>
</ClaimType>

CheckboxMultiSelect

CheckboxMultiSelect 使用者輸入類型可用來提供複選框集合，讓用戶選取多個選項。

搭配使用宣告類型搭配 checkboxmultiselect

<ClaimType Id="languages">
  <DisplayName>Languages you speak</DisplayName>
  <DataType>string</DataType>
  <UserInputType>CheckboxMultiSelect</UserInputType>
  <Restriction>
    <Enumeration Text="English" Value="English" SelectByDefault="true" />
    <Enumeration Text="France " Value="France" SelectByDefault="false" />
    <Enumeration Text="Spanish" Value="Spanish" SelectByDefault="false" />
  </Restriction>
</ClaimType>

唯讀

Readonly 使用者輸入類型可用來提供唯讀字段來顯示宣告和值。

搭配 readonly 使用宣告類型

<ClaimType Id="membershipNumber">
  <DisplayName>Membership number</DisplayName>
  <DataType>string</DataType>
  <UserHelpText>Your membership number (read only)</UserHelpText>
  <UserInputType>Readonly</UserInputType>
</ClaimType>

段落

Paragraph 使用者輸入類型可用來提供欄位，只顯示段落標記中的文字。例如， <p>text</p>。自我 判斷技術配置檔的Paragraph 使用者輸入類型 OutputClaim ，必須設定 Required 屬性 false （預設值）。只有自我判斷的頁面版面配置才支援此使用者輸入類型。整合登入和註冊頁面（unifiedssp）可能無法正確顯示。

搭配段落使用宣告類型

<ClaimType Id="responseMsg">
  <DisplayName>Error message: </DisplayName>
  <DataType>string</DataType>
  <AdminHelpText>A claim responsible for holding response messages to send to the relying party</AdminHelpText>
  <UserHelpText>A claim responsible for holding response messages to send to the relying party</UserHelpText>
  <UserInputType>Paragraph</UserInputType>
</ClaimType>

分享方式：