關於 Azure AD B2C 中的 API 連接器

發行項
01/11/2024

開始之前，請使用此頁面頂端的 [選擇原則類型] 選取器，選擇您要設定的原則類型。 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 要求，將使用者資訊 (「宣告」) 以 JSON 主體中的金鑰/值組傳送。 API 回應可能會影響使用者流程的執行。例如，API 回應可能會封鎖使用者註冊、要求使用者重新輸入資訊，或覆寫使用者屬性。

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

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

在註冊期間與識別提供者建立同盟之後 - 僅適用於註冊體驗
建立使用者之前 - 僅適用於註冊體驗
傳送權杖之前 (預覽) - 適用於註冊和登入

在使用者利用身分識別提供者 (如 Google、Facebook 與 Microsoft Entra ID) 進行驗證之後，系統會立即在註冊流程的這個步驟叫用 API 連接器。此步驟會在屬性集合頁面之前進行，該頁面是向使用者顯示以收集使用者屬性的表單。如果使用者利用本機帳戶進行註冊，系統不會叫用此步驟。下列是您可能會在此步驟啟用的 API 連接器情節範例：

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

建立使用者之前

在屬性集合頁面 (若有) 之後，系統會在註冊流程的這個步驟叫用 API 連接器。在建立使用者帳戶之前，系統會一律叫用此步驟。下列是您在註冊期間的這個時間點，可能會啟用的情節範例：

驗證使用者輸入資料，並要求使用者重新提交資料。
根據使用者輸入的資料，封鎖使用者註冊。
驗證使用者識別。
查詢外部系統以取得使用者的現有資料，在應用程式權杖中傳回該資料，或將該資料儲存在 Microsoft Entra ID 中。

傳送權杖之前 (預覽)

注意

此功能處於公開預覽狀態。

在發出權杖之前，系統會在註冊或登入程序的這個步驟叫用 API 連接器。下列是您可能會在此步驟啟用的情節範例：

使用與目錄不同的來源 (包括舊版身分識別系統、HR 系統、外部使用者存放區等) 的使用者相關屬性來擴充權杖。
使用您在自己的權限系統中儲存和管理的群組或角色屬性來擴充權杖。
將宣告轉換或操作套用至目錄中的宣告值。

構成 Azure Active Directory B2C (Azure AD B2C) 基礎的 Identity Experience Framework，可與使用者旅程圖中的 RESTful API 整合。本文說明如何使用 RESTful 技術設定檔，建立與 RESTful 服務互動的使用者旅程圖。

您可以使用 Azure AD B2C，呼叫自己的 RESTful 服務，將自己的商務邏輯新增至使用者旅程圖。 Identity Experience Framework 可以從您的 RESTful 服務傳送和接收資料，以交換宣告。例如，您可以：

使用外部身分識別資料來源來驗證使用者輸入資料。例如，您可能會驗證使用者提供的電子郵件地址是否存在於客戶資料庫中；如果不存在，則顯示錯誤。您也可以將 API 連接器視為支援輸出 Webhook 的方式，因為在事件發生時 (例如註冊) 會發出呼叫。
處理宣告。如果使用者輸入全部小寫或全部大寫的名字，您的 REST API 可以將名稱格式設定為只有第一個字母大寫，並傳回 Azure AD B2C。不過，使用自訂原則時，建議使用 ClaimsTransformations，而不是呼叫 RESTful API。
與公司的企業營運應用程式進一步整合來動態擴充使用者資料。您的 RESTful 服務可以接收使用者的電子郵件地址、查詢客戶的資料庫，以及將使用者的忠誠度號碼傳回給 Azure AD B2C。傳回宣告可能會儲存在使用者的 Microsoft Entra 帳戶中，於下一個協調流程步驟中評估，或包含在存取權杖中。
執行自訂商務邏輯。您可以傳送推播通知、更新公司資料庫、執行使用者移轉程序、管理權限、稽核資料庫，以及執行其他工作流程。

Diagram of a RESTful service claims exchange

注意

如果 RESTful 服務對於 Azure AD B2C 的回應速度很慢或沒有回應，則逾時為 30 秒，且重試計數為兩倍 (表示總計有 3 次嘗試)。目前您無法設定逾時和重試計數設定。

呼叫 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 宣告提供者。可能的值是：

主體，以 JSON 格式在 HTTP POST 要求本文中傳送。
表單，以符號 '&' 分隔的金鑰值格式在 HTTP POST 要求本文中傳送。
標題，在 HTTP GET 要求標題中傳送。
QueryString，會在 HTTP GET 要求查詢字串中傳送。

設定主體選項時，REST API 技術設定檔可讓您將複雜的 JSON 承載傳送至端點。如需相關資訊，請參閱傳送 JSON 承載。

接收資料

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

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 資料類型，則傳回最小值 1970-00-00T00: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 和加密套件需求。

下一步

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

了解如何在與外部程序連接時打造復原能力
了解如何透過開發人員最佳做法進行復原。

使用 API 連接器搭配外部身分識別資料來源，自訂和擴充註冊使用者流程與自訂原則

概觀