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

適用於：所有 API 管理層級

本文會引導您完成設定和使用受控 連線 的高階步驟，以授與 Microsoft Entra 使用者或群組委派給後端 OAuth 2.0 API 的許可權。 當客戶端應用程式（或機器人）需要代表已認證使用者存取後端安全線上資源時，請遵循以下步驟（例如查看電子郵件或下訂單）。

案例概觀

在此案例中，您會設定受控 連線 ，讓用戶端應用程式 （或 Bot） 代表 Microsoft Entra 使用者或群組存取後端 API。 舉例來說，你可能有一個靜態網頁應用程式，能存取後端的 GitHub API，而你想要存取登入使用者的特定資料。 下圖說明案例。

• 使用者必須授權應用程式代表他們存取安全資源。 要授權該應用程式，使用者必須在 Microsoft Entra 中驗證其身份。
• 為了代表使用者執行操作，應用程式會呼叫外部後端服務，例如 GitHub。
• 每個外部服務都有一種保護這些呼叫的方法;例如，使用唯一識別使用者的使用者權杖。
• 若要保護對外部服務的呼叫，應用程式必須要求使用者登入，才能取得使用者的權杖。
• 在設定過程中，你可以透過 API Management 實例中的憑證管理器註冊憑證提供者。 它包含要使用的身分識別提供者的相關資訊，以及有效的 OAuth 用戶端 ID 和密碼、要啟用的 OAuth 範圍，以及該身分提供者所需的其他連線中繼資料。
• 你建立並使用連線來幫助使用者登入並取得使用者憑證，這樣才能被管理。

先決條件

• 存取您有權建立應用程式註冊並授與管理員同意應用程式權限的 Microsoft Entra 租用戶。 瞭解更多資訊

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

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

• 執行中的 API 管理服務實例。 如有需要，請 建立 Azure API 管理 實例。

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

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

步驟 1：佈建 Azure API 管理資料平台服務主體

您必須佈建 Azure API 管理 資料平面服務主體，以授與使用者或群組必要的委派許可權。 請依照以下步驟使用 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 API 管理 資料平面服務主體：

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

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

建立使用者委派的 Microsoft Entra ID 應用程式，並授與其適當的許可權，以讀取 API 管理 中的連線。

1. 使用具有足夠許可權的帳戶登入租戶中的 Azure 入口網站。
2. 在 [Azure 服務] 底下，搜尋 Microsoft Entra ID。
3. 在左側功能表上，選取 [管理>]，然後選取 [+ 新增註冊]。
4. 在 [註冊應用程式] 頁面上，輸入您的應用程式註冊設定：
   1. 在 名稱中輸入使用者能看到的有意義名稱，例如 UserPermissions。
   2. 在 [支援的帳戶類型] 中，選取適合您案例的選項，例如，僅限此組織目錄中的帳戶 （單一租用戶）。
   3. 將 重新導向 URI 設定為 Web ，然後輸入 https://www.postman-echo.com/get。
   4. 選取 註冊。
5. 在左側功能表上，選取 [管理>，然後選取 [+ 新增許可權]。
   1. 選取 [ 我的組織使用的 API] 索引標籤，輸入 [Azure API 管理 資料平面]，然後選取它。
   2. 在 權限中，選擇 授權。讀取，然後選擇 新增權限。
6. 在左側功能表上，選取 概 觀。 在 概 觀 頁面上，尋找 應用程式 （用戶端） 識別碼 值並記錄它，以供稍後的步驟使用。
7. 在左側選單中，選擇 「管理>憑證與秘密」，然後選擇 「+ 新客戶端秘密」。
   1. 輸入 描述。
   2. 選取 Expires 的選項。
   3. 選取 ，然後新增。
   4. 在離開頁面之前，複製用戶端密碼的 值 。 您在稍後的步驟中需要此資訊。

步驟 3：在 API 管理 中設定認證提供者

在此步驟中，為你的後端 OAuth 2.0 API 建立一個認證提供者，代表使用者或群組進行存取。 例如，請依照步驟建立 GitHub API 的憑證提供者。 簡短步驟如下：

1. 在 GitHub 上為 API 建立一個 OAuth 應用程式，並賦予它你想要呼叫的請求適當的權限。
2. 登入 Azure 入口網站 ，並移至您的 API 管理實例。
3. 在左側選單中，選擇 API>憑證管理器，然後選擇 + 建立。
4. 在 建立憑證提供者時，輸入 GitHub 提供者的設定。 在此情境中，在 補助金類型中選擇 授權碼。 如需詳細資訊，請參閱 在認證管理員中設定認證提供者。
5. 選取 ，創建。
6. 當被提示時，請檢視顯示的 OAuth 重定向網址，並選擇 「是 」以確認它是否與你在 GitHub 應用程式註冊時輸入的網址相符。

步驟 4：設定連線

建立憑證提供者後，你可以新增與 GitHub 提供者的連線。 在 [連線] 索引標籤上，完成連線的步驟：

1. 輸入 連線名稱，然後選取 儲存。
2. 在 「步驟 2：登入連線」下，選取 「登入」 按鈕。 完成該處的步驟以授權存取，然後返回 API 管理。
3. 在 [步驟 3：判斷誰將有權存取此連線 （存取原則）] 底下，選取 [+ 新增]。 根據您的委派案例，選取 [ 使用者 ] 或 [群組]。
4. 在 [選取項目 ] 視窗中，依下列順序進行選取：
   1. 搜尋一個或多個使用者或群組加入，並勾選選項。
   2. 搜尋您在前一節建立的應用程式註冊。
   3. 選取 選取。
5. 選取 [完成]。

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

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

要啟用使用者委派存取後端 API，您必須在 get-authorization-context 政策執行時為委派使用者或群組提供存取權杖。 通常，您的用戶端應用程式會透過 Microsoft 認證函式庫 （MSAL）以程式化方式取得此權杖。 本節提供手動步驟，以建立用於測試的存取權杖。

1. 請將下列 URL 貼到瀏覽器中，並將 <tenant-id> 和 <client-id> 的變數值替換為您在 Microsoft Entra 應用程式註冊中所設定的值：

   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. 出現提示時，請登入。 在回應本文中，複製提供的 程式碼 值 （範例： "0.AXYAh2yl..."）。

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

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

   Header

   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 的值 （範例： eyJ0...）。 你在下一步的政策設定中傳遞這個值。

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

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

1. 登入 Azure 入口網站 ，並移至您的 API 管理實例。

2. 在左側功能表中，選取 API>API 並選取 您的 OAuth 2.0 後端 API。

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

4. 在該get-authorization-context區段設定inbound政策，設定identity-type為 jwt。 同時設定這兩個 set-header 原則，一個用來將在 get-authorization-context 原則中取得的存取權杖設定到 Authorization 標頭，另一個用來設定 GitHub API 所需的 User-Agent 標頭。

   <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" />
            <set-header name="Authorization" exists-action="override">
               <value>@("Bearer " + ((Authorization)context.Variables.GetValueOrDefault("auth-context"))?.AccessToken)</value>
           </set-header>
           <set-header name="User-Agent" exists-action="override">
               <value>API Management</value>
           </set-header>
           [...]
       </inbound> 
   </policies>
   

在上述政策定義中，替換：

• <credential-provider-id> 和 <connection-id> 分別是您在先前步驟中設定的認證提供者和連線的名稱。

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

步驟 7：測試 API

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

2. 選擇 傳送。

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

相關內容

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