共用方式為

設定認證管理員：使用者委派的後端 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。

步驟 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. 在左側功能表上選取 [認證管理員]，然後選取 [+ 建立]。
    在入口網站中建立 API 認證的螢幕快照。
  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 傳回使用者資料。

相關內容