設定認證管理員：使用者委派的後端 API 存取權

適用於：所有 API 管理 層

本文會引導您完成設定和使用受控連線的高階步驟，以將委派的後端 OAuth 2.0 API 權限授與 Microsoft Entra 使用者或群組。 針對用戶端應用程式 (或 Bot) 必須代表已驗證的使用者存取後端保護之線上資源的案例 (例如，檢查電子郵件或下單)，請遵循下列步驟。

案例概觀

注意

此案例僅適用於設定了授權碼授與類型的認證提供者。

在此案例中，您會設定受控連線，讓用戶端應用程式 (或 Bot) 代表 Microsoft Entra 使用者或群組存取後端 API。 例如，您可能有靜態 Web 應用程式可存取後端 GitHub API，且您想要使用該應用程式存取登入使用者專屬的資料。 下圖說明此案例。

• 使用者必須授權應用程式代表其存取受保護的資源，以及為了授權應用程式，使用者必須驗證其身分識別
• 為了代表使用者執行作業，應用程式會呼叫外部後端服務，例如 Microsoft Graph 或 GitHub
• 每個外部服務都有保護這些呼叫的方法，例如，使用可唯一識別使用者的使用者權杖
• 為了保護外部服務的呼叫，應用程式必須要求使用者登入，使其能夠取得使用者的權杖
• 在設定過程中，認證提供者會使用 APIM 執行個體中的認證管理員進行註冊。 其中包含要使用的識別提供者相關資訊，以及有效的 OAuth 用戶端識別碼及祕密、要啟用的 OAuth 範圍和該識別提供者所需的其他連線中繼資料。
• 此外，還會建立連線，並將其用來協助使用者登入及取得使用者權杖，以便進行管理

必要條件

• 存取您有權建立應用程式註冊並授與管理員同意應用程式權限的 Microsoft Entra 租用戶。 深入了解

  如果您想要建立自己的開發人員租用戶，可以註冊 Microsoft 365 開發人員計劃。

• 租用戶中要向其委派權限的一或多個使用者或群組。

• 執行中的 APIM 執行個體。 如有必要，請建立 Azure APIM 執行個體。

• 您想要代表使用者或群組存取的後端 OAuth 2.0 API。

• 如果您選擇在本機使用 Azure PowerShell：
  • 安裝最新版的 Az PowerShell 模組。
  • 使用 Connect-AzAccount Cmdlet 連線至 Azure 帳戶。
• 如果您選擇使用 Azure Cloud Shell：
  • 請參閱 Azure Cloud Shell 概觀 以取得詳細資訊。

步驟 1：佈建 Azure APIM 資料平面服務主體

您必須佈建 Azure APIM　資料平面服務主體，將必要的委派權限授與使用者或群組。 使用下列步驟，透過 Azure PowerShell 佈建服務主體。

1. 登入 Azure PowerShell。

2. 如果尚未安裝 AzureAD 模組，請使用下列命令加以安裝：

   Install-Module -Name AzureAD -Scope CurrentUser -Repository PSGallery -Force
   

3. 使用下列命令連線到租用戶：

   Connect-AzureAD -TenantId "<YOUR_TENANT_ID>"
   

4. 如果出現提示，請使用租用戶的系統管理員帳戶認證登入。

5. 使用下列命令佈建 Azure APIM 資料平面服務主體：

   New-AzureADServicePrincipal -AppId c8623e40-e6ab-4d2b-b123-2ca193542c65 -DisplayName "Azure API Management Data Plane"
   

步驟 2：建立 Microsoft Entra 應用程式註冊

建立 Microsoft Entra ID 應用程式以進行使用者委派，並授與其適當的權限以讀取 APIM 中的連線。

1. 使用租用戶中具有足夠權限的帳戶登入 Azure 入口網站。
2. 在 [Azure 服務] 底下，搜尋 Microsoft Entra ID。
3. 在左側功能表中選取 [應用程式註冊]，然後選取 [+ 新增註冊]。
4. 在 [註冊應用程式] 頁面中，輸入應用程式的註冊設定：
   1. 在 [名稱] 中，輸入將對應用程式使用者顯示且有意義的名稱，例如 UserPermissions。
   2. 在 [支援的帳戶類型] 中，選取適合您案例的選項，例如 [僅此組織目錄中的帳戶 (單一租用戶)]。
   3. 將 [重新導向 URI] 設定為 [Web]，並輸入 https://www.postman-echo.com/get。
5. 在左側功能表中選取 [API 權限]，然後選取 [+ 新增權限]。
   1. 選取 [我的組織使用的 API] 索引標籤，輸入 Azure APIM 資料平面，然後加以選取。
   2. 在 [權限] 底下選取 [Authorizations.Read]，然後選取 [新增權限]。
6. 在左側功能表上選取 [概觀]。 在 [概觀] 頁面上，尋找 [應用程式 (用戶端) 識別碼] 值並將其記下供稍後的步驟使用。
7. 在左側功能表中選取 [憑證和祕密]，然後選取 [+ 新增用戶端密碼]。
   1. 輸入說明。
   2. 為 [到期] 選取選項。
   3. 選取 [新增]。
   4. 在離開此頁面之前，請複製用戶端密碼的 [值]。 您在稍後的步驟中需要此資訊。

步驟 3：在 APIM 中設定認證提供者

1. 登入入口網站，並瀏覽至您的 APIM 執行個體。
2. 在左側功能表上選取 [認證管理員]，然後選取 [+ 建立]。
   
3. 在 [建立認證提供者] 頁面上，輸入 API 認證提供者的設定。 針對此案例，您必須在 [授與類型] 中選取 [授權碼]。 如需詳細資訊，請參閱在認證管理員中設定認證提供者。
4. 選取 建立。
5. 出現提示時，請檢閱顯示的 OAuth 重新導向 URL，然後選取 [是] 以確認符合您在應用程式註冊中輸入的 URL。

步驟 4：設定連線

建立認證提供者之後，您可以新增提供者的連線。 在 [連線] 索引標籤上，完成用於連線的步驟：

1. 輸入連線名稱，然後選取 [儲存]。
2. 根據步驟 2：登入您的連線，選取登入認證提供者的連結。 完成該處授權存取的步驟，然後返回 APIM。
3. 根據步驟 3：判斷誰可以存取此連線 (存取原則)，選取 [+ 新增]。 根據委派案例，選取 [使用者] 或 [群組]。
4. 在 [選取項目] 視窗中，依下列順序進行選取：
   1. 首先，搜尋一或多個使用者 (或群組) 以新增並勾選選取方塊。
   2. 然後，在顯示的清單中，搜尋您在上一節中建立的應用程式註冊。
   3. 然後按一下 [選取]。
5. 選取 [完成]。

新的連線會出現在連線清單中，並顯示 [已連線] 狀態。 如果您想要為認證提供者建立另一個連線，請完成上述步驟。

提示

您可以隨時使用入口網站來新增、更新或刪除認證提供者的連線。 如需詳細資訊，請參閱設定多個連線。

步驟 5：取得 Microsoft Entra ID 存取權杖

若要啟用使用者委派的後端 API 存取權，必須在執行階段於 get-authorization-context 原則中提供委派使用者或群組的存取權杖。 一般而言，這是透過使用 Microsoft 驗證程式庫 (MSAL) 在用戶端應用程式中以程式設計方式完成。 本節提供建立存取權杖以進行測試的手動步驟。

1. 在瀏覽器中貼上下列 URL，以 Microsoft Entra 應用程式註冊的值取代 <tenant-id> 和 <client-id> 的值：

   https://login.microsoftonline.com/<tenant-id>/oauth2/authorize?client_id=<client-id>&response_type=code&redirect_uri=https://www.postman-echo.com/get&response_mode=query&resource=https://azure-api.net/authorization-manager&state=1234`
   

2. 出現提示時，請登入。 在回應本文中，複製所提供 code 的值 (範例："0.AXYAh2yl…")。

3. 將下列 POST 要求傳送至權杖端點，以您的租用戶識別碼取代 <tenant-id>，並包含應用程式註冊中指示的標頭和主體參數，以及您在上一個步驟中複製的程式碼。

   POST https://login.microsoftonline.com/<tenant-id>/oauth2/token HTTP/1.1
   

   頁首

   Content-Type: application/x-www-form-urlencoded

   本文

   grant_type: "authorization_code"
   client_id: <client-id>
   client_secret: <client-secret>
   redirect_uri: <redirect-url> 
   code: <code>   ## The code you copied in the previous step
   

4. 在回應本文中，複製所提供 access_token 的值 (範例：eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjZqQmZ1...)。 在下一個步驟中，您將在原則組態中傳遞此值。

步驟 6：為後端 API 設定 get-authorization-context 原則

為您想要代表使用者或群組存取的後端 API 設定 get-authorization-context 原則。 為了進行測試，您可以針對上一節中取得的使用者，使用 Microsoft Entra ID 存取權杖來設定原則。

1. 登入入口網站，並瀏覽至您的 APIM 執行個體。

2. 在左側功能表上選取 [API]，然後選取您的 OAuth 2.0 後端 API。

3. 選取 [所有作業]。 在 [輸入處理] 區段中，選取程式碼編輯器 (</>) 圖示。

4. 在 inbound 區段中設定 get-authorization-context 原則，將 identity-type 設定為 jwt：

   <policies>
       <inbound>
           [...]
           <get-authorization-context provider-id="<credential-provider-id>" authorization-id="<connection-id>" context-variable-name="auth-context" identity-type="jwt" identity="<access-token>" ignore-error="false" />
           [...]
       </inbound> 
   </policies>
   

在上述原則定義中：

• 將 <credential-provider-id> 和 <connection-id> 分別取代為您在上一個步驟中設定的認證提供者名稱和連線名稱。

• 將 <access-token> 取代為您在上一個步驟中產生的 Microsoft Entra ID 存取權杖。

步驟 7：測試 API

1. 在 [測試] 索引標籤上，選取您設定的一項作業。

2. 請選取傳送。

   成功的回應會從後端 API 傳回使用者資料。

相關內容

• 深入瞭解 驗證和授權原則
• 深入了解 Microsoft Entra ID 中的範圍和權限。