使用 API 連接器擴充來自外部來源的宣告的權杖

發行項
11/08/2023

開始之前，請使用 [選擇原則類型 選取器] 來選擇您要設定的原則類型。 Azure Active Directory B2C 提供兩種方法來定義使用者如何與您的應用程式互動：透過預先定義的使用者流程，或透過完全可設定的自訂原則。本文中每個方法所需的步驟都不同。

Azure Active Directory B2C （Azure AD B2C）可讓身分識別開發人員使用 API 連接器，將與 RESTful API 的互動整合到其使用者流程中。它可讓開發人員從外部身分識別來源動態擷取資料。在本逐步解說結束時，您將能夠建立與 API 互動的 Azure AD B2C 使用者流程，以從外部來源擴充權杖。

您可以使用套用至 [傳送權杖之前] 步驟的 API 連接器（預覽） 步驟，透過外部來源的資訊來擴充應用程式的權杖。當使用者登入或註冊時，Azure AD B2C 會呼叫 API 連接器中設定的 API 端點，以查詢下游服務中使用者的相關資訊，例如雲端服務、自訂使用者存放區、自訂許可權系統、舊版身分識別系統等等。

注意

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

您可以使用我們的其中一個範例來建立 API 端點。

必要條件

建立使用者流程，讓使用者可以註冊並登入您的應用程式。
註冊 Web 應用程式。

完成開始使用 Active Directory B2C 中的自訂原則中的步驟
註冊 Web 應用程式。

API 端點。您可以使用我們的其中一個範例來建立 API 端點。

建立 API 連接器

若要使用 API 連接器，請先建立 API 連接器，然後在使用者流程中加以啟用。

登入 Azure 入口網站。
在 [Azure 服務 ] 底下 ，選取 [Azure AD B2C ]。
選取 [API 連接器 ]，然後選取 [ 新增 API 連接器 ]。
提供呼叫的顯示名稱。例如， 從外部來源 擴充權杖。
提供 API 呼叫的端點 URL 。
選擇 [ 驗證類型 ]，並設定用來呼叫 API 的驗證資訊。瞭解如何保護您的 API 連線or 。
選取 [儲存]。

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

請遵循下列步驟，將 API 連接器新增至註冊使用者流程。

登入 Azure 入口網站。
在 [Azure 服務 ] 底下 ，選取 [Azure AD B2C ]。
選取 [ 使用者流程 ]，然後選取您要新增 API 連接器的使用者流程。
選取 [API 連接器 ]，然後選取您要在使用者流程中 傳送權杖（預覽） 步驟之前叫用的 API 端點：
選取 [儲存]。

此步驟僅適用于 註冊和登入（建議） 、 註冊（建議） 和 登入（建議） 使用者流程。

在此步驟中傳送至 API 的範例要求

當令牌即將在登入和註冊期間發出時，會叫用此步驟中的 API 連接器。 API 連接器會具體化為 HTTP POST 要求，以 JSON 主體中的索引鍵/值組形式傳送使用者屬性（'claims'）。屬性會與 Microsoft Graph 使用者屬性類似序列化。

POST <API-endpoint>
Content-type: application/json
{
 "email": "johnsmith@fabrikam.onmicrosoft.com",
 "identities": [
     {
     "signInType":"federated",
     "issuer":"facebook.com",
     "issuerAssignedId":"0123456789"
     }
 ],
 "displayName": "John Smith",
 "objectId": "ab3ec3b2-a435-45e4-b93a-56a005e88bb7",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "231c70e8-8424-48ac-9b5d-5623b9e4ccf3",
 "step": "PreTokenIssuance",
 "ui_locales":"en-US"
}

傳送至 API 的宣告取決於使用者定義的資訊。只有 Azure AD B2C 使用者屬性體驗中列出的 使用者屬性和自訂屬性 ，才能在要求中傳送。 > 自訂屬性存在於 目錄中的 extension_ < extensions-app-id > _CustomAttribute 格式中。您的 API 應該預期會收到這個相同序列化格式的宣告。如需自訂屬性的詳細資訊，請參閱在 Azure AD B2C 中定義自訂屬性。此外，這些宣告通常會在此步驟的所有要求中傳送：

UI 地區設定（'ui_locales'） - 使用者的地區設定在其裝置上設定。這可供您的 API 用來傳回國際化的回應。
步驟（'step'） - 叫用 API 連接器的使用者流程上的步驟或點。此步驟的值是 '
用戶端識別碼（'client_id'） - appId 終端使用者在使用者流程中驗證的應用程式值。這不是存取權杖中的資源應用程式 appId 。
objectId - 使用者的識別碼。您可以使用此專案來查詢下游服務，以取得使用者的相關資訊。

重要

如果宣告在呼叫 API 端點時沒有值，則不會將宣告傳送至 API。您的 API 應該設計成明確檢查和處理宣告不在要求中的案例。

此步驟中來自 Web API 的預期回應類型

當 Web API 在使用者流程期間收到來自 Microsoft Entra ID 的 HTTP 要求時，它可以傳回「接續回應」。

接續回應

接續回應表示使用者流程應該繼續下一個步驟：發出權杖。在接續回應中，API 可以傳回其他宣告。您想要在權杖中傳回的 API 所傳回的宣告必須是內建宣告，或定義為自訂屬性，而且必須在使用者流程的 Application 宣告 組態中 選取。權杖中的宣告值將會由 API 傳回，而不是目錄中的值。 API 回應無法覆寫某些宣告值。 API 可以傳回的宣告會對應至 User 屬性下找到的集合，但例外 email 。

注意

API 只會在初始驗證期間叫用。使用重新整理權杖以無訊息方式取得新的存取或識別碼權杖時，權杖會包含初始驗證期間評估的值。

範例回應

接續回應的範例

HTTP/1.1 200 OK
Content-type: application/json
{
    "version": "1.0.0",
    "action": "Continue",
    "postalCode": "12349", // return claim
    "extension_<extensions-app-id>_CustomAttribute": "value" // return claim
}

參數	類型	必要	描述
version	String	Yes	API 的版本。
action	String	Yes	值必須是 `Continue` 。
<builtInUserAttribute>	<attribute-type>	No	如果選取為應用程式宣告，則可以在權杖中傳回它們。
<extension_{extensions-app-id}_CustomAttribute>	<attribute-type>	No	宣告不需要包含 `_<extensions-app-id>_` ，這是選擇性的。如果選取為應用程式宣告，則可以在權杖中傳回它們。

在此案例中，我們會整合公司企業營運工作流程來擴充使用者的權杖資料。使用本機或同盟帳戶註冊或登入期間，Azure AD B2C 會叫用 REST API，以從遠端資料源取得使用者的擴充設定檔資料。在此範例中，Azure AD B2C 會傳送使用者的唯一識別碼 objectId。然後，REST API 會傳回使用者帳戶餘額（亂數）。使用此範例作為起點，與您自己的 CRM 系統、行銷資料庫或任何企業營運工作流程整合。您也可以將互動設計為驗證技術設定檔。當 REST API 在畫面上驗證資料並傳回宣告時，這很適合。如需詳細資訊，請參閱逐步解說：將 API 連接器新增至註冊使用者流程。

必要條件

完成開始使用自訂原則中的步驟。您應該有使用本機帳戶註冊和登入的工作自訂原則。
瞭解如何在 Azure AD B2C 自訂原則中整合 REST API 宣告交換。

準備 REST API 端點

在本逐步解說中，您應該有 REST API 來驗證使用者的 Azure AD B2C objectId 是否已在後端系統中註冊。如果已註冊，REST API 會傳回使用者帳戶餘額。否則，REST API 會在目錄中註冊新帳戶，並傳回起始餘額 50.00 。下列 JSON 程式碼說明 Azure AD B2C 將傳送至 REST API 端點的資料。

{
    "objectId": "User objectId",
    "lang": "Current UI language"
}

一旦 REST API 驗證資料，它必須傳回 HTTP 200 （確定），並具有下列 JSON 資料：

{
    "balance": "760.50"
}

REST API 端點的設定超出本文的範圍。我們已建立 Azure Functions 範例。您可以在 GitHub 存取完整的 Azure 函式程式碼。

定義宣告

宣告會在 Azure AD B2C 原則執行期間提供資料的暫存儲存體。您可以在宣告架構區段中宣告宣告。

開啟原則的延伸模組檔案。例如： SocialAndLocalAccounts/TrustFrameworkExtensions.xml 。
搜尋 BuildingBlocks 元素。如果專案不存在，請加以新增。
找出 ClaimsSchema 元素。如果專案不存在，請加以新增。
將下列宣告新增至 ClaimsSchema 元素。

<ClaimType Id="balance">
  <DisplayName>Your Balance</DisplayName>
  <DataType>string</DataType>
</ClaimType>
<ClaimType Id="userLanguage">
  <DisplayName>User UI language (used by REST API to return localized error messages)</DisplayName>
  <DataType>string</DataType>
</ClaimType>

新增 RESTful API 技術配置檔

Restful 技術配置檔支援與您自己的 RESTful 服務互動。 Azure AD B2C 會將數據傳送至集合中的 InputClaims RESTful 服務，並接收集合中的數據 OutputClaims 。 在您的檔案中TrustFrameworkExtensions.xml尋找 ClaimsProviders 元素，並新增新的宣告提供者，如下所示：

<ClaimsProvider>
  <DisplayName>REST APIs</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="REST-GetProfile">
      <DisplayName>Get user extended profile Azure Function web hook</DisplayName>
      <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <Metadata>
        <!-- Set the ServiceUrl with your own REST API endpoint -->
        <Item Key="ServiceUrl">https://your-account.azurewebsites.net/api/GetProfile?code=your-code</Item>
        <Item Key="SendClaimsIn">Body</Item>
        <!-- Set AuthenticationType to Basic or ClientCertificate in production environments -->
        <Item Key="AuthenticationType">None</Item>
        <!-- REMOVE the following line in production environments -->
        <Item Key="AllowInsecureAuthInProduction">true</Item>
      </Metadata>
      <InputClaims>
        <!-- Claims sent to your REST API -->
        <InputClaim ClaimTypeReferenceId="objectId" />
        <InputClaim ClaimTypeReferenceId="userLanguage" PartnerClaimType="lang" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
      </InputClaims>
      <OutputClaims>
        <!-- Claims parsed from your REST API -->
        <OutputClaim ClaimTypeReferenceId="balance" />
      </OutputClaims>
      <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

在此範例中， userLanguage 會將傳送至 REST 服務，如同 JSON 承載中一樣 lang 。宣告的值 userLanguage 包含目前的用戶語言識別碼。如需詳細資訊，請參閱宣告解析程式。

設定 RESTful API 技術配置檔

部署 REST API 之後，請設定技術設定檔的 REST-GetProfile 元數據以反映您自己的 REST API，包括：

ServiceUrl。設定 REST API 端點的 URL。
SendClaimsIn。指定如何將輸入宣告傳送至 RESTful 宣告提供者。
AuthenticationType。設定 RESTful 宣告提供者所執行的驗證類型，例如 Basic 或 ClientCertificate
AllowInsecureAuthInProduction。在生產環境中，請務必將此元數據設定為 false。

如需更多設定，請參閱 RESTful 技術配置檔元數據。上述 AuthenticationType 批注，並 AllowInsecureAuthInProduction 指定移至生產環境時應該進行的變更。若要瞭解如何保護生產環境的 RESTful API，請參閱保護您的 RESTful API。

新增協調流程步驟

使用者旅程圖會指定明確的路徑，原則可透過這類路徑來讓信賴憑證者應用程式取得使用者所需的宣告。使用者旅程圖會以協調流程順序表示，必須遵循才能成功交易。您可以新增或減去協調流程步驟。在此情況下，您將新增協調流程步驟，以在使用者透過 REST API 呼叫註冊或登入之後，用來增強提供給應用程式的資訊。

開啟原則的基底檔案。例如： SocialAndLocalAccounts/TrustFrameworkBase.xml 。
<UserJourneys>搜尋專案。複製整個專案，然後刪除它。
開啟原則的延伸模組檔案。例如： SocialAndLocalAccounts/TrustFrameworkExtensions.xml 。
將 <UserJourneys> 貼到延伸模組檔案中，在專案關閉 <ClaimsProviders> 之後。

<UserJourney Id="SignUpOrSignIn">找出，並在最後一個步驟之前新增下列協調流程步驟。

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>

將變更 Order 為 8，以重構最後一個協調流程步驟。最後兩個協調流程步驟看起來應該如下所示：

<OrchestrationStep Order="7" Type="ClaimsExchange">
  <ClaimsExchanges>
    <ClaimsExchange Id="RESTGetProfile" TechnicalProfileReferenceId="REST-GetProfile" />
  </ClaimsExchanges>
</OrchestrationStep>
<OrchestrationStep Order="8" Type="SendClaims" CpimIssuerTechnicalProfileReferenceId="JwtIssuer" />

針對 ProfileEdit 和 PasswordReset 使用者旅程圖重複最後兩個步驟。

在令牌中包含宣告

若要將 balance 宣告傳回信賴憑證者應用程式，請將輸出宣告新增至 SocialAndLocalAccounts/SignUpOrSignIn.xml 檔案。在成功使用者旅程圖之後，新增輸出宣告會將宣告發出至令牌，並將傳送至應用程式。修改信賴憑證者區段中的技術配置文件專案，以新增 balance 為輸出宣告。

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
      <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
      <OutputClaim ClaimTypeReferenceId="balance" DefaultValue="" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

針對 ProfileEdit.xml 和 PasswordReset.xml 使用者旅程圖重複此步驟。儲存您變更的檔案：TrustFrameworkBase.xml 和 TrustFrameworkExtensions.xml、SignUpOrSignin.xml、ProfileEdit.xml 和 PasswordReset.xml。

測試自定義原則

登入 Azure 入口網站。
如果您有多個租使用者的存取權，請選取頂端功能表中的 [設定] 圖示，從 [目錄 + 訂用帳戶] 功能表切換至您的 Azure AD B2C 租使用者。
選擇 Azure 入口網站左上角的 [所有服務]，然後搜尋並選取 [應用程式註冊]。
選取 [ 身分識別體驗架構]。
選取 [上傳自定義原則]，然後上傳您變更的原則檔案：TrustFrameworkBase.xml 和 TrustFrameworkExtensions.xml、SignUpOrSignin.xml、ProfileEdit.xml 和 PasswordReset.xml。
選取您上傳的註冊或登入原則，然後按兩下 [ 立即執行] 按鈕。
您應該能夠使用電子郵件位址或 Facebook 帳戶註冊。
傳回至應用程式的令牌包含 balance 宣告。

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/f06c2fe8-709f-4030-85dc-38a4bfd9e82d/v2.0/",
  "aud": "e1d2612f-c2bc-4599-8e7b-d874eaca1ee1",
  "acr": "b2c_1a_signup_signin",
  "nonce": "defaultNonce",
  "iat": 1584957916,
  "auth_time": 1584957916,
  "name": "Emily Smith",
  "email": "emily@outlook.com",
  "given_name": "Emily",
  "family_name": "Smith",
  "balance": "202.75"
  ...
}

最佳做法和如何進行疑難解答

使用無伺服器雲端函式

無伺服器函式，例如 Azure Functions 中的 HTTP 觸發程式，提供建立 API 端點以搭配 API 連接器使用的方式。無伺服器雲端函式也可以針對複雜案例呼叫及叫用其他 Web API、數據存放區和其他雲端服務。

最佳作法

請確定：

您的 API 會遵循上述的 API 要求和回應合約。
API 連接器的端點 URL 會指向正確的 API 端點。
您的 API 會明確檢查所接收宣告的 Null 值，視其而定。
您的 API 會實作安全 API 連接器中所述的驗證方法。
您的 API 會儘快回應，以確保流暢的用戶體驗。
- Azure AD B2C 將等候最多 20 秒 以接收回應。如果未收到任何訊息，則會在呼叫您的 API 時再嘗試一次（重試）。
- 如果您使用無伺服器函式或可調整的 Web 服務，請使用裝載方案，讓 API 在生產環境中保持「清醒」或「暖」。針對 Azure Functions，建議您至少在生產環境中使用進階版計劃。
確定 API 的高可用性。
監視和優化下游 API、資料庫或其他 API 相依性的效能。

重要

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

使用記錄

使用無伺服器雲端函式

使用記錄

一般而言，使用 Web API 服務所啟用的記錄工具，例如 Application Insights，監視 API 是否有非預期的錯誤碼、例外狀況和效能不佳很有説明。

監視不是 HTTP 200 或 400 的 HTTP 狀態代碼。
401 或 403 HTTP 狀態代碼通常表示您的驗證發生問題。在 API 連接器中，仔細檢查 API 的驗證層和對應的組態。
視需要，在開發中使用更積極的記錄層級（例如「追蹤」或「偵錯」。
監視 API 的回應時間很長。此外，Azure AD B2C 會記錄透過使用者流程在使用者驗證期間發生的 API 交易元數據。若要尋找下列資訊：

移至 Azure AD B2C
在 [活動] 底下，選取 [稽核記錄]。
篩選清單檢視：針對 [日期]，選取您想要的時間間隔，針對 [活動]，選取 [API 已呼叫為使用者流程的一部分]。
檢查個別記錄。每個數據列都代表在使用者流程期間嘗試呼叫的 API 連接器。如果 API 呼叫失敗，而且發生重試，它仍會以單一數據列表示。 numberOfAttempts表示呼叫 API 的次數。這個值可以是 1或 2。關於 API 呼叫的其他資訊會在記錄中詳述。

下一步

開始使用我們的範例。
保護您的 API 連線 or

若要瞭解如何保護您的 API，請參閱下列文章：

使用 API 連接器擴充來自外部來源的宣告的權杖

必要條件

建立 API 連接器

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

在此步驟中傳送至 API 的範例要求

此步驟中來自 Web API 的預期回應類型

接續回應

範例回應

接續回應的範例

必要條件

準備 REST API 端點

定義宣告

新增 RESTful API 技術配置檔

設定 RESTful API 技術配置檔

新增協調流程步驟

在令牌中包含宣告

測試自定義原則

最佳做法和如何進行疑難解答

使用無伺服器雲端函式

最佳作法

使用記錄

使用無伺服器雲端函式

使用記錄

下一步

其他資源