共用方式為

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

這很重要

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

備註

在 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-UserWritePhoneNumberUsingObjectId - 寫入本機或社交帳戶的 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 元素包含宣告，用來查閱目錄中的帳戶，或建立新的帳戶。 所有Microsoft Entra 技術配置文件的輸入宣告集合中必須只有一個 InputClaim 元素。 您可能需要將原則中定義的宣告名稱對應至 Microsoft Entra ID 中定義的名稱。

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

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

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

輸出聲明

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 元素包含所有值，這些值應該由 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 作業會從提供的宣告清單中清除資訊。 下列技術設定檔會刪除宣告：

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

後設資料

屬性 為必填項目 說明
行動 是的 要執行的作業。 可能的值： Read、 Write、 DeleteClaims或 DeleteClaimsPrincipal。
RaiseErrorIfClaimsPrincipalDoesNotExist 否 如果用戶物件不存在於目錄中，則引發錯誤。 可能的值： true 或 false。
RaiseErrorIfClaimsPrincipalAlreadyExists 否 如果用戶物件已經存在，則引發錯誤。 可能的值： true 或 false。 此元數據僅適用於寫入作業。
ApplicationObjectId 應用程式物件ID 否 擴充屬性的應用程式物件識別碼。 值：應用程式的 ObjectId。 如需詳細資訊，請參閱 使用自定義屬性。
用戶端ID 否 作為第三方存取租使用者的用戶端標識碼。 如需詳細資訊，請參閱 在自定義配置檔編輯原則中使用自定義屬性
IncludeClaimResolvingInClaimsHandling 否 針對輸入和輸出宣告，指定宣告解析是否包含在技術配置檔中。 可能的值： true、 或 false （預設值）。 如果您要在技術設定檔中使用宣告解析程式，請將此設定為 true。

UI 元素

下列設定可用來設定失敗時顯示的錯誤訊息。 元數據應在 自斷言 技術配置檔中配置。 錯誤訊息可以 當地語系化。

屬性 為必填項目 說明
UserMessageIfClaimsPrincipalAlreadyExists 否 如果要引發錯誤（請參閱 RaiseErrorIfClaimsPrincipalAlreadyExists 屬性描述），請在用戶對象已經存在時指定要向使用者顯示的訊息。
UserMessageIfClaimsPrincipalDoesNotExist 否 如果要引發錯誤（請參閱 RaiseErrorIfClaimsPrincipalDoesNotExist 屬性描述），請指定用戶物件不存在時向用戶顯示的訊息。

後續步驟

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

  • Last updated on