使用 API 連接器，透過外部身分識別數據源自定義和擴充註冊使用者流程和自定義原則

這很重要

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

開始之前，請使用此頁面頂端的 [選擇原則類型] 選取器，選擇您要設定的原則類型。 Azure Active Directory B2C 提供兩種方法來定義使用者如何與您的應用程式互動：透過預先定義的使用者流程，或透過完全可設定的自訂原則。 此文章中所需的步驟隨各方法而異。

概觀

身為開發人員或 IT 系統管理員，您可以使用 API 連接器，將註冊使用者流程與 REST API 整合，以自定義註冊體驗，並與外部系統整合。 例如，使用 API 連接器，您可以：

• 驗證使用者輸入數據。 針對格式不正確或無效的用戶數據進行驗證。 例如，您可以針對外部資料存放區中的現有數據或允許值清單，驗證使用者提供的數據。 如果無效，您可以要求使用者提供有效的數據，或封鎖用戶繼續註冊流程。
• 確認使用者身分識別。 使用身分識別驗證服務或外部身分識別數據源，將額外的安全性層級新增至帳戶建立決策。
• 與自定義核准工作流程整合。 連接到自訂化審批系統，以便於管理及限制帳戶的創建。
• 使用來自外部來源的屬性來增強令牌。 使用來自 Azure AD B2C 外部來源的使用者屬性擴充令牌，例如雲端系統、自定義使用者存放區、自定義許可權系統、舊版身分識別服務等等。
• 覆寫用戶屬性。 重新格式化或指派值給從使用者收集的屬性。 例如，如果使用者在所有小寫或全部大寫字母中輸入名字，您可以只使用第一個字母大寫來格式化名稱。
• 執行自定義商業規則。 您可以觸發雲端系統中的下游事件，以傳送推播通知、更新公司資料庫、管理許可權、稽核資料庫，以及執行其他自定義動作。

API 連接器藉由定義 API 呼叫的 HTTP 端點 URL 和驗證，為 Azure AD B2C 提供呼叫 API 端點所需的資訊。 設定 API 連接器之後，您可以針對使用者流程中的特定步驟加以啟用。 當用戶在註冊流程中達到該步驟時，API 連接器會被啟動，並轉化為向您的 API 發出的 HTTP POST 請求，將使用者資訊（「claims」）以鍵值對形式包含在 JSON 主體中傳送。 API 回應可能會影響使用者流程的執行。 例如，API 回應可以封鎖用戶註冊、要求使用者重新輸入資訊，或覆寫用戶屬性。

在使用者流程中啟用 API 連接器的地方

使用者流程中有三個地方可讓您啟用 API 連接器：

• 在註冊過程中與身份提供者整合之後 - 僅適用於註冊體驗
• 建立使用者之前 - 僅適用於註冊體驗
• 傳送令牌之前 （預覽） - 適用於註冊和登入

在註冊期間與識別提供者建立同盟之後

註冊程式中此步驟中的 API 連接器會在使用者向身分識別提供者進行驗證之後立即叫用（例如 Google、Facebook 和 Microsoft Entra ID）。 此步驟會在屬性集合頁面之前進行，該頁面是向使用者顯示以收集使用者屬性的表單。 如果使用者註冊本機帳戶，這個步驟就不會被執行。 以下是您可以在此步驟中啟用的 API 連接器案例範例：

• 使用使用者提供的電子郵件或聯合身分識別來查閱現有系統中的憑證。 從現有的系統傳回這些宣告、預先填入屬性集合頁面，並讓這些宣告可在令牌中傳回。
• 根據社交身分識別實作允許或封鎖清單。

建立使用者之前

在屬性集合頁面 (若有) 之後，系統會在註冊流程的這個步驟叫用 API 連接器。 建立用戶帳戶之前，一律會叫用此步驟。 以下是您在註冊的這個階段可能啟用的情境：

• 驗證使用者輸入數據，並要求使用者重新提交數據。
• 根據使用者輸入的數據封鎖用戶註冊。
• 驗證使用者識別。
• 查詢外部系統以獲得使用者的現有數據，然後將這些數據返回至應用程式憑證或儲存在 Microsoft Entra ID 中。

傳送權杖之前 （預覽）

備註

這項功能處於公開預覽狀態。

在發行令牌之前，會叫用註冊或登入程式中此步驟中的 API 連接器。 以下是在此步驟中您可能會啟用的情況：

• 使用與目錄不同之來源的使用者屬性來擴充令牌，包括舊版身分識別系統、HR 系統、外部使用者存放區等等。
• 使用您在自己的許可權系統中儲存和管理的群組或角色屬性來擴充令牌。
• 對目錄中宣告的值進行轉換或操作。

身份識別體驗框架是 Azure Active Directory B2C（Azure AD B2C）的基礎，可在使用者體驗旅程中與 RESTful API 整合。 本文說明如何使用 RESTful 技術配置檔建立與 RESTful 服務互動的使用者旅程圖。

使用 Azure AD B2C，您可以呼叫自己的 RESTful 服務，將自己的商業規則新增至使用者旅程圖。 身分識別體驗架構可以從 RESTful 服務傳送和接收數據，以交換宣告。 例如，您可以：

• 使用外部身分識別數據源來驗證使用者輸入數據。 例如，您可以確認使用者提供的電子郵件位址存在於您客戶的資料庫中，如果不存在，則會出現錯誤。 您也可以將 API 連接器視為支持輸出 Webhook 的一種方式，因為事件發生時會進行呼叫，例如註冊。
• 處理索賠。 如果使用者在所有小寫或全部大寫字母中輸入其名字，您的 REST API 只能使用第一個字母大寫來格式化名稱，並將其傳回至 Azure AD B2C。 不過，使用自定義原則時，應優先選擇 ClaimsTransformations，而不是呼叫 RESTful API。
• 藉由進一步整合公司企業營運應用程式，以動態擴充用戶數據。 您的 RESTful 服務可以接收使用者的電子郵件地址、查詢客戶的資料庫，並將使用者的忠誠度號碼傳回 Azure AD B2C。 接著，傳回的宣告可以儲存在使用者的 Microsoft Entra 帳戶中，在下一個協調流程步驟中進行評估，或包含在存取令牌內。
• 執行自定義商業規則。 您可以傳送推播通知、更新公司資料庫、執行使用者移轉程式、管理許可權、稽核資料庫，以及執行任何其他工作流程。

備註

如果 RESTful 服務對 Azure AD B2C 的回應緩慢或沒有回應，可能會取消 HTTP 要求。 默認逾時為 10 秒，預設重試計數為一次（表示總共有 2 次嘗試）。

呼叫 RESTful 服務

這個互動包括 REST API 聲明和 Azure AD B2C 之間的信息交換。 您可以透過下列方式設計與 RESTful 服務的整合：

• 驗證技術設定檔。 RESTful 服務的呼叫會在指定的驗證技術配置檔的自我判斷技術配置檔內發生，或在顯示控制的驗證顯示控制中。 驗證技術配置檔會在使用者旅程向前移動之前驗證使用者提供的數據。 使用驗證技術屬性設定，您可以：

  • 將宣告傳送至您的 REST API。
  • 驗證索賠，並拋出向用戶顯示的自定義錯誤訊息。
  • 將來自 REST API 的宣告傳回至下一個協調流程步驟。

• 理賠交換。 直接從 使用者旅程的協調步驟中呼叫 REST API 技術設定，即可設定直接要求交換。 此定義僅限於：

  • 將宣告傳送至您的 REST API。
  • 驗證宣告，並擲回傳回至應用程式的自定義錯誤訊息。
  • 將來自 REST API 的宣告傳回至下一個協調流程步驟。

您可以在自訂原則所定義之使用者旅程圖的任何步驟新增 REST API 呼叫。 例如，您可以呼叫 REST API：

• 登入時，緊接在 Azure AD B2C 驗證使用者憑證之前。
• 登入后立即。
• 在 Azure AD B2C 在目錄中建立新帳戶之前。
• 在 Azure AD B2C 在目錄中建立新的帳戶之後。
• 在 Azure AD B2C 發出存取令牌之前。

傳送數據

在 RESTful 技術配置檔中，InputClaims元素包含要傳送至 RESTful 服務的宣稱清單。 您可以將宣告的名稱對應至 RESTful 服務中定義的名稱、設定預設值，以及使用 宣告解析程式。

您可以使用 SendClaimsIn 屬性，設定輸入宣告如何傳送至 RESTful 宣告提供者。 可能的值為：

• 本文，在 HTTP POST 要求的內容中以 JSON 格式傳送。
• 表單，在 HTTP POST 要求本文中以 '&' 和號分隔的索引鍵值格式傳送。
• 標頭，在 HTTP GET 要求標頭中傳送。
• QueryString，在 HTTP GET 要求查詢字串中傳送。

設定Body選項時，REST API 技術概況允許您將複雜的 JSON 承載傳送至端點。 如需詳細資訊，請參閱 傳送 JSON 承載。

接收資料

OutputClaims RESTful 技術配置檔的 元素包含 REST API 所傳回的宣告清單。 您可能需要將原則中定義的宣告名稱對應至 REST API 中定義的名稱。 您也可以包含 REST API 識別提供者未傳回的宣告，只要您設定 DefaultValue 屬性即可。

被 RESTful 宣告提供者剖析的輸出宣告一律預期剖析扁平化 JSON 主體回應，例如：

{
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "loyaltyNumber":  1234
}

輸出宣告看起來應該像下列 xml 代碼段：

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="name" />
  <OutputClaim ClaimTypeReferenceId="email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" />
</OutputClaims>

處理 Null 值

當數據行中的值未知或遺失時，會使用資料庫中的 Null 值。 請勿包含 null 具有 值的 JSON 索引鍵。 在下列範例中，電子郵件會傳 null 回值：

{
  "name": "Emily Smith",
  "email": null,
  "loyaltyNumber":  1234
}

當元素為 null 時，請選擇以下其中一項：

• 省略 JSON 中的鍵值對。
• 傳回與 Azure AD B2C 該宣告的資料類型相對應的值。 例如，針對 string 資料類型，傳回空字串 ""。 integer針對資料類型，傳回零值 0。 dateTime針對資料類型，傳回最小值 0001-01-01T00:00:00.0000000Z。

下列範例示範如何處理 Null 值。 電子郵件會從 JSON 中省略：

{
  "name": "Emily Smith",
  "loyaltyNumber":  1234
}

解析巢狀 JSON 主體

若要剖析巢狀 JSON 主體回應，請將 ResolveJsonPathsInJsonTokens 元數據設定為 true。 在輸出宣告中，將 PartnerClaimType 設定為您要輸出的 JSON 路徑元素。

"contacts": [
  {
    "id": "MAINCONTACT_1",
    "person": {
      "name": "Emily Smith",
      "loyaltyNumber":  1234,
      "emails": [
        {
          "id": "EMAIL_1",
          "type": "WORK",
          "email": "email@domain.com"
        }
      ]
    }
  }
],

輸出宣告看起來應該像下列 xml 代碼段：

<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="displayName" PartnerClaimType="contacts[0].person.name" />
  <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="contacts[0].person.emails[0].email" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="contacts[0].person.loyaltyNumber" />
</OutputClaims>

將 REST API 本地化

在 RESTful 技術設定檔中，您可能會想要傳送目前會話的語言/地區設定，並視需要顯示本地化的錯誤訊息。 使用 宣告解析程式，您可以傳送背景宣告，例如使用者語言。 下列範例展示此情境的 RESTful 技術配置檔。

<TechnicalProfile Id="REST-ValidateUserData">
  <DisplayName>Validate user input data</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="emailAddress" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

處理錯誤訊息

您的 REST API 可能需要傳回錯誤訊息，例如「在 CRM 系統中找不到使用者」。如果發生錯誤，REST API 應該會傳回 HTTP 409 錯誤訊息（衝突響應狀態代碼）。 如需詳細資訊，請參閱 RESTful 技術配置檔。

只有從驗證技術配置檔呼叫 REST API 技術配置檔，才能達成此行為。 讓使用者更正頁面上的數據，並在頁面提交時再次執行驗證。

如果您直接從使用者旅程中參考 REST API 技術設定檔，則會以相關的錯誤訊息將使用者重新導向回信賴方應用程式。

開發您的 REST API

您的 REST API 可以在任何平台上開發，並以任何程式設計語言撰寫，只要它是安全的，就可以以 JSON 格式傳送和接收宣告。

對 REST API 服務的要求來自 Azure AD B2C 伺服器。 REST API 服務必須發佈至可公開存取的 HTTPS 端點。 REST API 呼叫會從 Azure 資料中心 IP 位址抵達。

您可以使用無伺服器雲端函式，例如 Azure Functions 中的 HTTP 觸發程式 ，以方便開發。

您應該將 REST API 服務及其基礎元件（例如資料庫和檔案系統）設計為高可用性。

這很重要

您的端點必須符合 Azure AD B2C 安全性需求規範。 已淘汰舊版 TLS 和加密。 如需詳細資訊，請參閱 Azure AD B2C TLS 和加密套件需求。

後續步驟

• 瞭解如何 新增 API 連接器以修改註冊體驗
• 瞭解如何 新增 API 連接器，以使用外部宣告擴充令牌
• 瞭解如何 保護您的 API 連接器
• 開始使用我們的 範例

如需使用 RESTful 技術配置檔的範例，請參閱下列文章：

• 操作指南：將 API 連接器新增至使用者註冊流程
• 逐步解說：將 REST API 宣告交換新增至 Azure Active Directory B2C 中的自定義原則
• 保護您的 REST API 服務
• 使用 Azure Active Directory B2C 自定義原則呼叫 REST API

• 瞭解如何在與外部進程互動時建立復原能力
• 了解如何透過開發人員最佳做法進行復原。