使用 API 連接器從外部來源擴充令牌的聲明

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

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

先決條件

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

建立 API 連接器

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

1. 登入 Azure 入口網站。

2. 在 [Azure 服務] 底下，選取 [Azure AD B2C]。

3. 選取 [API 連接器]，然後選取 [ 新增 API 連接器]。

   

4. 提供呼叫的顯示名稱。 例如， 從外部來源擴充令牌。

5. 提供 API 呼叫的端點 URL。

6. 選擇 [驗證類型]，並設定用於呼叫 API 的驗證資訊。 了解如何保護 API 連接器的安全。

   

7. 選取 [儲存]。

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

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

1. 登入 Azure 入口網站。

2. 在 [Azure 服務] 底下，選取 [Azure AD B2C]。

3. 選取 [使用者流程]，然後選取您要新增 API 連接器的使用者流程。

4. 選取 [API 連接器]，然後選取您要在使用者流程中 傳送令牌 （預覽） 步驟之前 叫用的 API 端點：

   

5. 選取 [儲存]。

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

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

當登入和註冊期間即將頒發令牌時，會在此步驟中調用 API 連接器。 API 連接器會具體化為 HTTP POST 要求，並將使用者屬性 (「宣告」) 作為 JSON 主體中的金鑰/值組傳送。 屬性的序列化方式類似於 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": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
 "extension_<extensions-app-id>_CustomAttribute1": "custom attribute value",
 "extension_<extensions-app-id>_CustomAttribute2": "custom attribute value",
 "client_id": "00001111-aaaa-2222-bbbb-3333cccc4444",
 "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 終端使用者在使用者流程中驗證的應用程式值。 這不是資源應用程式在存取權杖中的內容。
• objectId - 使用者的標識符。 您可以使用此項目來查詢下游服務，以取得使用者的相關信息。

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

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

接續回應

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

範例回應

接續回應範例

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
}

在此案例中，我們會整合公司企業營運工作流程來擴充使用者的令牌數據。 使用本機或同盟帳戶註冊或登入期間，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 原則執行期間提供數據的暫時存儲。 您可以在 宣告架構 區段中宣告宣告。

1. 開啟您政策的延伸檔案。 例如： SocialAndLocalAccounts/TrustFrameworkExtensions.xml 。
2. 搜尋 BuildingBlocks 元素。 如果元素不存在，加以新增。
3. 找出 ClaimsSchema 元素。 如果元素不存在，加以新增。
4. 將下列宣告新增至 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元素，然後新增一個新的宣告提供者，如下所示：

<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 將作為 lang 在 JSON 承載中傳送至 REST 服務。 宣告 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 呼叫註冊或登入之後，用來增強提供給應用程式的資訊。

1. 開啟原則的基底檔案。 例如： SocialAndLocalAccounts/TrustFrameworkBase.xml 。
2. 搜尋<UserJourneys>元素。 複製整個元素，然後刪除它。
3. 開啟您政策的延伸檔案。 例如： SocialAndLocalAccounts/TrustFrameworkExtensions.xml 。
4. 將 <UserJourneys> 貼到延伸模組檔案中，在 <ClaimsProviders> 元素結束之後。
5. 找出 <UserJourney Id="SignUpOrSignIn">，並在最後一個步驟之前新增下列流程編排步驟。

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

6. 將 Order 變更為 8 以重構最後一個協調步驟。 最後兩個編排步驟應如以下所示：

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

7. 針對 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。

測試自定義原則

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

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "X5eXk4xyojNFum1kl2Ytv8dlNP4-c57dO6QGTVBwaNk"
}.{
  "exp": 1584961516,
  "nbf": 1584957916,
  "ver": "1.0",
  "iss": "https://contoso.b2clogin.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/",
  "aud": "11112222-bbbb-3333-cccc-4444dddd5555",
  "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，建議您至少在生產環境中使用 Premium 方案 。
• 確保 API 的高可用性。
• 監視下游 API、資料庫或 API 其他相依性的效能，並將其最佳化。

使用記錄

使用無伺服器雲端函式

無伺服器函式 (例如 Azure Functions 中的 HTTP 觸發程序) 提供一個方式來建立 API 端點以搭配 API 連接器使用。 無伺服器雲端函式也可以呼叫和叫用其他 Web API、資料存放區及其他雲端服務來進行複雜的案例。

使用記錄

一般而言，您可以使用透過 Web API 服務啟用的記錄工具 (例如 Application insights)，來協助監視您的 API 是否有未預期的錯誤碼、例外狀況和效能不佳的情況。

• 監視非 HTTP 200 或 400 的 HTTP 狀態碼。
• 401 或 403 HTTP 狀態碼通常表示您的驗證發生問題。 請再次檢查您 API 的驗證層，以及 API 連接器中的對應設定。
• 如有需要，請在開發中使用更主動的記錄層級 (例如「追蹤」或「偵錯」)。
• 監視您的 API 是否有過長的回應時間。

此外，Azure AD B2C 會記錄透過使用者流程在使用者驗證期間發生的 API 交易元數據。 若要找到這些項目：

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

• 開始使用我們的 範例。
• 保護您的 API 連接器

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

• 操作指南：將 REST API 宣告交換整合至 Azure AD B2C 使用者旅程，作為協調流程的步驟
• 保護您的 RESTful API
• 參考：RESTful 技術設定檔