在 Azure Active Directory B2C 自訂原則中定義 Microsoft Entra 技術設定檔

發行項
01/11/2024

注意

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

Azure Active Directory B2C （Azure AD B2C）提供 Microsoft Entra 使用者管理的支援。本文說明與支援此標準化通訊協定之宣告提供者互動的技術設定檔細節。

通訊協定

Protocol 元素的 Name 屬性必須設定為 Proprietary 。 處理常式 屬性必須包含通訊協定處理常式元件 Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null 的完整名稱。

遵循自訂原則入門套件 Microsoft Entra 技術設定檔包含 AAD-Common 技術設定檔。 Microsoft Entra 技術設定檔不會指定通訊協定，因為通訊協定是在 AAD-Common 技術設定檔中 設定：

AAD-UserReadUsingAlternativeSecurityId 和 AAD-UserReadUsingAlternativeSecurityId-NoError - 在目錄中查閱社交帳戶。
AAD-UserWriteUsingAlternativeSecurityId - 建立新的社交帳戶。
AAD-UserReadUsingEmailAddress - 在目錄中查閱本機帳戶。
AAD-UserWriteUsingLogonEmail - 建立新的本機帳戶。
AAD-UserWritePasswordUsingObjectId - 更新本機帳戶的密碼。
AAD-UserWriteProfileUsingObjectId - 更新本機或社交帳戶的使用者設定檔。
AAD-UserReadUsingObjectId - 讀取本機或社交帳戶的使用者設定檔。
AAD-UserWrite電話NumberUsingObjectId - 寫入本機或社交帳戶的 MFA 電話號碼

下列範例顯示 AAD-Common 技術設定檔：

<TechnicalProfile Id="AAD-Common">
  <DisplayName>Azure Active Directory</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureActiveDirectoryProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

  <CryptographicKeys>
    <Key Id="issuer_secret" StorageReferenceId="B2C_1A_TokenSigningKeyContainer" />
  </CryptographicKeys>

  <!-- We need this here to suppress the SelfAsserted provider from invoking SSO on validation profiles. -->
  <IncludeInSso>false</IncludeInSso>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

InputClaims

InputClaims 元素包含宣告，用來查閱目錄中的帳戶，或建立新的帳戶。所有 Microsoft Entra 技術設定檔的輸入宣告集合中必須只有一個 InputClaim 元素。您可能需要將原則中定義的宣告名稱對應至 Microsoft Entra ID 中定義的名稱。

若要讀取、更新或刪除現有的使用者帳戶，輸入宣告是可唯一識別 Microsoft Entra 目錄中帳戶的索引鍵。例如 ，objectId 、 userPrincipalName、 signInNames.emailAddress 、 signInNames.userName 或 alternativeSecurityId 。

若要建立新的使用者帳戶，輸入宣告是可唯一識別本機或同盟帳戶的金鑰。例如，本機帳戶： signInNames.emailAddress 或 signInNames.userName 。針對同盟帳戶： alternativeSecurityId 。

InputClaimsTransformations 元素可能包含用來修改輸入宣告或產生新宣告的輸入宣告轉換元素集合。

OutputClaims

OutputClaims 元素包含 Microsoft Entra 技術設定檔所傳回的宣告清單。您可能需要將原則中定義的宣告名稱對應至 Microsoft Entra ID 中定義的名稱。您也可以包含 Microsoft Entra 識別碼未傳回的宣告，只要您設定 DefaultValue 屬性即可。

OutputClaimsTransformations 元素可能包含 OutputClaimsTransformation 元素的 集合，這些元素可用來修改輸出宣告或產生新的宣告。

例如， AAD-UserWriteUsingLogonEmail 技術設定檔會建立本機帳戶，並傳回下列宣告：

objectId ，這是新帳戶的識別碼
newUser ，指出使用者是否為新使用者
authenticationSource ，將驗證設定為 localAccountAuthentication
userPrincipalName ，這是新帳戶的使用者主體名稱
signInNames.emailAddress ，這是帳戶登入名稱，類似于 電子郵件 輸入宣告

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="objectId" />
  <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
  <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="localAccountAuthentication" />
  <OutputClaim ClaimTypeReferenceId="userPrincipalName" />
  <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
</OutputClaims>

PersistedClaims

PersistedClaims 元素包含 Microsoft Entra ID 應該保存的所有值，這些值在原則的 ClaimsSchema 區段和 Microsoft Entra 屬性名稱中已經定義的宣告類型之間可能對應的資訊。

建立新本機帳戶的 AAD-UserWriteUsingLogonEmail 技術設定檔會保存下列宣告：

  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="email" PartnerClaimType="signInNames.emailAddress" />
    <PersistedClaim ClaimTypeReferenceId="newPassword" PartnerClaimType="password"/>
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="passwordPolicies" DefaultValue="DisablePasswordExpiration" />

    <!-- Optional claims. -->
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>

宣告的名稱是 Microsoft Entra 屬性的名稱，除非 指定 PartnerClaimType 屬性，其中包含 Microsoft Entra 屬性名稱。

作業的需求

所有 Microsoft Entra 技術設定檔的宣告包中必須只有一個 InputClaim 元素。
使用者設定檔屬性一文說明您可以在輸入宣告、輸出宣告和保存宣告中使用的支援的 Azure AD B2C 使用者設定檔屬性。
如果作業為 Write 或 DeleteClaims ，則它也必須出現在 PersistedClaims 元素中 。
userPrincipalName 宣告的值 必須格式為 user@tenant.onmicrosoft.com 。
displayName 宣告是必要的，而且不能是空字串。

Microsoft Entra 技術設定檔作業

參閱

讀取作業會讀取單一使用者帳戶的相關資料。下列技術設定檔會使用使用者的 objectId 讀取使用者帳戶的相關資料：

<TechnicalProfile Id="AAD-UserReadUsingObjectId">
  <Metadata>
    <Item Key="Operation">Read</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalDoesNotExist">true</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims>

    <!-- Required claims -->
    <OutputClaim ClaimTypeReferenceId="strongAuthenticationPhoneNumber" />

    <!-- Optional claims -->
    <OutputClaim ClaimTypeReferenceId="signInNames.emailAddress" />
    <OutputClaim ClaimTypeReferenceId="displayName" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
    <OutputClaim ClaimTypeReferenceId="givenName" />
    <OutputClaim ClaimTypeReferenceId="surname" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

寫入

寫入作業會建立或更新單一使用者帳戶。下列技術設定檔會建立新的社交帳戶：

<TechnicalProfile Id="AAD-UserWriteUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">Write</Item>
    <Item Key="RaiseErrorIfClaimsPrincipalAlreadyExists">true</Item>
    <Item Key="UserMessageIfClaimsPrincipalAlreadyExists">You are already registered, please press the back button and sign in instead.</Item>
  </Metadata>
  <IncludeInSso>false</IncludeInSso>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="CreateOtherMailsFromEmail" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="AlternativeSecurityId" PartnerClaimType="alternativeSecurityId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <!-- Required claims -->
    <PersistedClaim ClaimTypeReferenceId="alternativeSecurityId" />
    <PersistedClaim ClaimTypeReferenceId="userPrincipalName" />
    <PersistedClaim ClaimTypeReferenceId="mailNickName" DefaultValue="unknown" />
    <PersistedClaim ClaimTypeReferenceId="displayName" DefaultValue="unknown" />

    <!-- Optional claims -->
    <PersistedClaim ClaimTypeReferenceId="otherMails" />
    <PersistedClaim ClaimTypeReferenceId="givenName" />
    <PersistedClaim ClaimTypeReferenceId="surname" />
  </PersistedClaims>
  <OutputClaims>
    <OutputClaim ClaimTypeReferenceId="objectId" />
    <OutputClaim ClaimTypeReferenceId="newUser" PartnerClaimType="newClaimsPrincipalCreated" />
    <OutputClaim ClaimTypeReferenceId="otherMails" />
  </OutputClaims>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-AAD" />
</TechnicalProfile>

DeleteClaims

DeleteClaims 作業會從提供的宣告清單中清除資訊。下列技術設定檔會刪除宣告：

<TechnicalProfile Id="AAD-DeleteClaimsUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaims</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <PersistedClaims>
    <PersistedClaim ClaimTypeReferenceId="objectId" />
    <PersistedClaim ClaimTypeReferenceId="Verified.strongAuthenticationPhoneNumber" PartnerClaimType="strongAuthenticationPhoneNumber" />
  </PersistedClaims>
  <OutputClaims />
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

DeleteClaimsPrincipal

DeleteClaimsPrincipal 作業會從目錄刪除單一使用者帳戶。下列技術設定檔會使用使用者主體名稱，從目錄中刪除使用者帳戶：

<TechnicalProfile Id="AAD-DeleteUserUsingObjectId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="objectId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

下列技術設定檔會使用 alternativeSecurityId 刪除社交使用者帳戶：

<TechnicalProfile Id="AAD-DeleteUserUsingAlternativeSecurityId">
  <Metadata>
    <Item Key="Operation">DeleteClaimsPrincipal</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="alternativeSecurityId" Required="true" />
  </InputClaims>
  <OutputClaims/>
  <IncludeTechnicalProfile ReferenceId="AAD-Common" />
</TechnicalProfile>

中繼資料

屬性	必要	描述
作業	Yes	要執行的作業。可能的值： `Read` 、 `Write` 、 `DeleteClaims` 或 `DeleteClaimsPrincipal` 。
RaiseErrorIfClaimsPrincipalDoesNotExist	No	如果使用者物件不存在於目錄中，則引發錯誤。可能的值： `true` 或 `false` 。
RaiseErrorIfClaimsPrincipalAlreadyExists	No	如果使用者物件已經存在，則引發錯誤。可能的值： `true` 或 `false` 。此中繼資料僅適用于寫入作業。
ApplicationObjectId	No	擴充屬性的應用程式物件識別碼。值：應用程式的 ObjectId。如需詳細資訊，請參閱使用自訂屬性。
ClientId	No	作為協力廠商存取租使用者的用戶端識別碼。如需詳細資訊，請參閱在自訂設定檔編輯原則中使用自訂屬性
IncludeClaimResolvingInClaimsHandling	No	針對輸入和輸出宣告，指定宣告解析是否包含在技術設定檔中。可能的值： `true` 、或 `false` （預設值）。如果您想要在技術設定檔中使用宣告解析程式，請將此設定為 `true` 。

UI 元素

下列設定可用來設定失敗時顯示的錯誤訊息。中繼資料應該在自我判斷技術設定檔中設定。錯誤訊息可以當地語系化。

屬性	必要	描述
UserMessageIfClaimsPrincipalAlreadyExists	No	如果要引發錯誤（請參閱 RaiseErrorIfClaimsPrincipalAlreadyExists 屬性描述），請在使用者物件已經存在時指定要向使用者顯示的訊息。
UserMessageIfClaimsPrincipalDoesNotExist	No	如果要引發錯誤（請參閱 RaiseErrorIfClaimsPrincipalDoesNotExist 屬性描述），請指定使用者物件不存在時向使用者顯示的訊息。

下一步

如需使用 Microsoft Entra 技術設定檔的範例，請參閱下列文章：

在 Azure Active Directory B2C 中使用自訂原則新增宣告和自訂使用者輸入

共用方式為