ClaimsSchema

注意

在 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 元素包含下列屬性：

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

ClaimType 元素包含下列元素：

元素	發生次數	描述
DisplayName	1:1	要在各種畫面上顯示給使用者的標題。 此值可進行當地語系化。
DataType	1:1	宣告的類型。
DefaultPartnerClaimTypes	0:1	要用於指定通訊協定的夥伴預設宣告類型。 此值可以使用 InputClaim 或 OutputClaim 元素中指定的 PartnerClaimType 來覆寫。 使用此元素來指定通訊協定的預設名稱。
Mask	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 表示一年兩個月零五天又八小時五分二十秒。
phoneNumber	表示電話號碼。
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 元素包含下列屬性：

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

在下列範例中，當識別體驗架構與 SAML2 識別提供者或信賴憑證者應用程式進行互動時，會將 surname 宣告對應至 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 名稱 surname。

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

Mask

Mask 元素包含下列屬性：

屬性	必要	描述
Type	是	宣告遮罩的類型。 可能的值：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>

識別體驗架構會呈現電話號碼，同時隱藏前六個數字：

下列範例會使用 Regex 遮罩來設定 AlternateEmail 宣告。 如需更多範例，請查看 Regex 遮罩的即時示範。

<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 元素包含下列元素：

元素	發生次數	Description
列舉型別	1:n	使用者介面中使用者可用來針對宣告進行選取的可用選項，例如下拉式清單中的值。
模式	1:1	要使用的規則運算式。

列舉型別

Enumeration 元素定義使用者介面中可供使用者選取的宣告選項，例如 CheckboxMultiSelect、DropdownSingleSelect 或 RadioSingleSelect 的值。 或者，您也可以使用 LocalizedCollections 元素來定義和當地語系化可用的選項。 若要從宣告 Enumeration 集合中查閱項目，請使用 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>

預設值設為 New York 的城市下拉式清單：

模式

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

屬性	必要	描述
RegularExpression	Yes	此類型的宣告必須符合才能生效的規則運算式。
HelpText	No	如果規則運算式檢查失敗，即為提供給使用者的錯誤訊息。

下列範例會設定 email 宣告，並提供規則運算式輸入驗證和說明文字：

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

識別體驗架構會使用電子郵件格式輸入驗證來呈現電子郵件地址宣告：

UserInputType

Azure AD B2C 支援各種不同的使用者輸入類型 (例如文字方塊、密碼與下拉式清單)，可在手動輸入宣告類型的宣告資料時使用。 當使用自我判斷提示技術設定檔和顯示控制項收集使用者資訊時，必須指定 UserInputType。

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

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

UserInputType	支援的 ClaimType	Description
CheckboxMultiSelect	string	複選下拉式清單方塊。 宣告值會以所選值的逗號分隔字串表示。
DateTimeDropdown	date, dateTime	可選取年月日的下拉式清單。
DropdownSingleSelect	string	單選下拉式清單方塊。 宣告值是選取的值。
EmailBox	string	電子郵件輸入欄位。
Paragraph	boolean, date, dateTime, duration, int, long, string	只在段落標記中顯示文字的欄位。
密碼	string	密碼文字方塊。
RadioSingleSelect	string	選項按鈕集合。 宣告值是選取的值。
Readonly	boolean, date, dateTime, duration, int, long, string	唯讀文字方塊。
TextBox	boolean, int, phoneNumber, string	單行文字方塊。

TextBox

TextBox 使用者輸入類型會用來提供單行文字方塊。

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

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>

密碼

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

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

DateTimeDropdown

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

<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 使用者輸入類型會用來提供可讓使用者選取一個選項的選項按鈕集合。

<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 使用者輸入類型會用來提供可讓使用者選取多個選項的核取方塊集合。

<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

Paragraph 使用者輸入類型會用來提供只能在段落標記中顯示文字的欄位。 例如，<p>text</p>。 自我判斷技術設定檔的段落使用者輸入類型 OutputClaim，Required 屬性必須設為 false (預設值)。

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