如何藉由設定 OAuth 2.0 使用者授權來授權開發人員入口網站的測試主控台

發行項
04/01/2024

適用於：開發人員 |基本 |基本 v2 |標準 |標準 v2 |進階版

許多 API 都支援使用 OAuth 2.0 來保護 API，並確保只有有效的使用者才能存取，而且他們只能存取獲授權的資源。若要搭配此類 API 一起使用 Azure API 管理的互動式開發人員主控台，則該服務可讓您設定 OAuth 2.0 使用者授權的外部提供者。

在開發人員入口網站的測試主控台中設定 OAuth 2.0 使用者授權，開發人員即可方便取得 OAuth 2.0 存取權杖。權杖可從測試主控台傳至具有 API 呼叫的後端。權杖驗證必須分別設定 - 使用 JWT 驗證原則，或在後端服務中設定。

必要條件

本文將示範如何設定 API 管理服務執行個體，以便使用開發人員入口網站測試主控台中的 OAuth 2.0 授權，但不會示範如何設定 OAuth 2.0 提供者。

如果您尚未建立 API 管理服務執行個體，請參閱建立 API 管理服務執行個體。

案例概觀

在 APIM 中設定 OAuth 2.0 使用者授權，只會讓開發人員入口網站的測試主控台 (和 Azure 入口網站中的測試主控台) 作為用戶端，從授權伺服器取得權杖。儘管步驟相似，在 API 管理服務執行個體中設定 OAuth 2.0 所需的資訊也相同，但每個 OAuth 2.0 提供者的設定並不相同。本文將示範使用 Microsoft Entra ID 作為 OAuth 2.0 提供者的範例。

以下是高階設定步驟：

在 Microsoft Entra ID 中註冊應用程式 (後端應用程式) 來代表 API。
在 Microsoft Entra ID 中註冊另一個應用程式 (client-app)，以代表需要呼叫 API 的用戶端應用程式，在此案例中為開發人員入口網站的測試主控台。

在 Microsoft Entra ID 中授與權限，允許用戶端應用程式呼叫後端應用程式。
在開發人員入口網站中設定測試主控台，以使用 OAuth 2.0 使用者授權呼叫 API。
設定 API 以使用 OAuth 2.0 使用者授權。
新增原則，以預先授權每個連入要求的 OAuth 2.0 權杖。您可以針對任何 OAuth 2.0 提供者使用 validate-jwt 原則。

此設定支援下列 OAuth 流程：

概觀圖形，以可視化方式將下列流程概念化。

開發人員入口網站使用用戶端應用程式認證，向 Microsoft Entra ID 要求權杖。
成功驗證之後，Microsoft Entra ID 就會發出存取/重新整理權杖。
開發人員 (開發人員入口網站的使用者) 使用授權標頭進行 API 呼叫。
權杖會透過 Microsoft Entra ID，使用 APIM 中的 validate-jwt 原則進行驗證。
根據驗證結果，開發人員會在開發人員入口網站中收到回應。

授權授與類型

Azure API 管理支援下列 OAuth 2.0 授與類型 (流程)。授與類型表示用戶端應用程式 (此處是指開發人員入口網站中的測試主控台) 取得後端 API 存取權杖的方式。您可根據 OAuth 2.0 提供者及案例來設定一或多個授與類型。

以下為概略摘要。如需有關授與類型的詳細資訊，請參閱 OAuth 2.0 授權架構和 OAuth 授與類型。

授與類型	描述	案例
授權碼	交換權杖的授權碼	伺服器端應用程式，如 Web 應用程式
授權碼 + PKCE	授權碼流程的增強功能，可建立以授權要求傳送的程式代碼挑戰	無法保護秘密或令牌的行動和公用用戶端
隱含（已淘汰）	立即傳回存取權杖，而沒有額外的授權碼交換步驟	無法保護秘密或權杖的用戶端，例如行動應用程式和單頁應用程式通常不建議，因為沒有用戶端收到權杖的確認，HTTP 重新導向時，傳回存取權杖就具有一定風險
資源擁有者的密碼	要求使用者認證 (使用者名稱和密碼)，通常使用互動格式	用於高度信任的應用程式僅限無法使用其他更安全的流程時，才能使用
用戶端認證	驗證和授權應用程式，而非使用者	不需要特定使用者資料存取權限的機器對機器應用程式，例如在後端上執行的 CLI、精靈或服務

安全性考量

請考量授與類型所產生的權杖、權杖範圍，以及權杖的公開性。惡意執行者可能會盜用權杖，以存取權杖範圍內的其他資源。

在開發人員入口網站的測試主控台中設定 OAuth 2.0 使用者授權時：

限制權杖範圍，設為開發人員測試 API 所需的下限值。將範圍限制為測試主控台，或限制為受影響的 API。權杖範圍的設定步驟取決於您的 OAuth 2.0 提供者。

若您建立的其他用戶端應用程式用於存取後端 API，則可視案例調整權杖範圍的嚴格性。
若啟用用戶端認證流程，請特別小心。進行用戶端認證流程時，開發人員入口網站中的測試主控台不會要求認證。存取權杖可能會意外向開發人員或開發人員主控台的匿名使用者顯示。

追蹤重要資訊

在此教學課程中，會要求您記錄金鑰資訊，以供稍後參考：

後端應用程式 (用戶端) 識別碼：代表後端 API 的應用程式 GUID
後端應用程式範圍：針對存取 API，您可以建立的一或多個範圍。範圍格式為 api://<Backend Application (client) ID>/<Scope Name> (例如：api://1764e900-1827-4a0b-9182-b2c1841864c2/Read)
後端應用程式 (用戶端) 識別碼：代表開發人員入口網站的應用程式 GUID
用戶端應用程式祕密值：此 GUID 可用來作為在 Microsoft Entra ID 中與用戶端應用程式互動的祕密

向 OAuth 伺服器註冊應用程式

您必須向 OAuth 2.0 提供者註冊兩個應用程式：一個代表要保護的後端 API，而第二個代表呼叫 API 的用戶端應用程式，在此案例中為開發人員入口網站的測試主控台。

下列為使用 Microsoft Entra ID 作為 OAuth 2.0 提供者的範例步驟。如需應用程式註冊的詳細資訊，請參閱快速入門：設定應用程式以公開 Web API。

在 Microsoft Entra ID 中註冊應用程式來代表 API

在 Azure 入口網站中，搜尋並選取應用程式註冊。
選取新增註冊。
在出現的 [註冊應用程式] 頁面中，輸入應用程式的註冊資訊：
- 在 [名稱] 區段中，輸入將對應用程式使用者顯示、且有意義的應用程式名稱，例如 backend-app。
- 在 [支援的帳戶類型 ] 區段中，選取適合您情節的選項。
將 [重新導向 URI] 區段保持空白。稍後，您將在 API 管理的 OAuth 2.0 設定中新增產生的重新導向 URI。
選取 [暫存器] 以建立應用程式。
在應用程式 [概觀] 頁面上，尋找 [應用程式 (用戶端) 識別碼] 值並將它記下供稍後使用。
在側邊功能表的 [管理] 區段下，選取 [公開 API]，並使用預設值設定應用程式識別碼 URI。請記下此值，供後續使用。
選取 [新增範圍] 按鈕，以顯示 [新增範圍] 頁面：
1. 輸入 API 所支援範圍的範圍名稱 (例如 Files.Read)。
2. 在 [誰可以同意?] 中，針對您的案例進行選取，例如 [系統管理員與使用者]。針對較高權限案例，請選取 [僅限系統管理員]。
3. 輸入 [管理員同意顯示名稱] 和 [管理員同意描述]。
4. 確定已選取 [已啟用] 範圍狀態。
選取 [新增範圍] 按鈕以建立範圍。
重複上述兩個步驟，以新增 API 支援的所有範圍。
建立範圍後，請記下來，以便在後續步驟中使用。

在 Microsoft Entra ID 中註冊另一個應用程式來代表用戶端應用程式

每個呼叫 API 的用戶端應用程式也必須在 Microsoft Entra ID 中註冊為應用程式。

在 Azure 入口網站中，搜尋並選取應用程式註冊。
選取新增註冊。
在出現的 [註冊應用程式] 頁面中，輸入應用程式的註冊資訊：
- 在 [名稱] 區段中，輸入將對應用程式使用者顯示、且有意義的應用程式名稱，例如 client-app。
- 在 [支援的帳戶類型 ] 區段中，選取適合您情節的選項。
在 [重新導向 URI] 區段中，選取 [Web]，並將 [URL] 欄位暫時保留空白。
選取 [暫存器] 以建立應用程式。
在應用程式 [概觀] 頁面上，尋找 [應用程式 (用戶端) 識別碼] 值並將它記下供稍後使用。
建立此應用程式的用戶端密碼，以供後續步驟使用。
1. 在側邊功能表的 [管理] 區段底下，選取 [憑證及祕密]。
2. 在 [用戶端密碼] 底下，選取 [+ 新增用戶端密碼]。
3. 在 [新增用戶端密碼] 底下，提供描述，然後選擇金鑰到期時間。
4. 選取 [新增]。

建立密碼時，請記下金鑰值，以供後續步驟使用。您無法在入口網站中再次存取祕密。

在 Microsoft Entra ID 中授與權限

現在您已註冊兩個應用程式來代表 API 與測試主控台，請授與權限，允許用戶端應用程式呼叫後端應用程式。

在 Azure 入口網站中，搜尋並選取應用程式註冊。
選擇您的用戶端應用程式。然後在側邊功能表中，選取 [API 權限]。
選取 [+ Add a Permission] \(+ 新增權限\)。
在 [選取 API] 底下，選取 [我的 API]，然後尋找並選取您的後端應用程式。
選取 [委派權限]，然後為後端應用程式選取適當權限。
選取新增權限。

或者：

巡覽至用戶端應用程式的 [API 權限] 頁面。
選取 [為您的租用戶名稱授與系統管理員同意]<>，以代表此目錄中的所有使用者授與同意。

在 APIM 中設定 OAuth 2.0 授權伺服器

在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
在開發人員入口網站下的側邊功能表中，選取 [OAuth 2.0 + OpenID Connect]。
在 [OAuth 2.0] 索引標籤下，選取 [+ 新增]。
在 [名稱] 和 [說明] 欄位中輸入名稱和選擇性的說明。

注意

在 API 管理服務中，這些欄位會識別 OAuth 2.0 授權伺服器。其值不是來自 OAuth 2.0 伺服器。
輸入用戶端註冊頁面 URL，例如 https://contoso.com/login。若 OAuth 2.0 提供者支援管理帳戶的使用者，使用者則可在此頁面建立和管理帳戶。取決於使用的 OAuth 2.0 提供者，頁面將有所不同。

若您的 OAuth 2.0 提供者未設定使用者帳戶管理，請在此處輸入預留位置 URL，例如您公司的 URL，或 http://localhost 等 URL。
表單的下一個區段含有 [授權授與類型]、[授權端點 URL] 及 [授權要求方法] 等設定。
- 選取一或多個所需的授權授與類型。在此範例中，選取 [授權碼] (預設)。深入了解
- 輸入 [Authorization endpoint URL] 。您可以從其中一個應用程式註冊的 [端點] 頁面取得端點 URL。針對 Microsoft Entra ID 中的單一租用戶應用程式，此 URL 將類似於下列其中一個 URL，其中 {aad-tenant} 將取代為您 Microsoft Entra 租用戶的識別碼。
  
  建議使用 v2 端點；然而，API 管理同時支援 v1 與 v2 端點。
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/authorize (v2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/authorize (v1)
- [授權要求方法] 能指定將授權要求傳送到 OAuth 2.0 伺服器的方法。選取 [POST] 。
指定 [權杖端點 URL]、[用戶端驗證方法]、[存取權杖傳送方法] 及 [預設範圍]。
- 輸入 [Token endpoint URL] \(權杖端點 URL\)。針對 Microsoft Entra ID 中的單一租用戶應用程式，其將類似於下列其中一個 URL，其中 {aad-tenant} 將取代為您 Microsoft Entra 租用戶的識別碼。使用您先前選擇的相同端點版本 (v2 或 v1)。
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/v2.0/token (v2)
  
  https://login.microsoftonline.com/{aad-tenant}/oauth2/token (v1)
- 若您使用 v1 端點，請新增主體參數：
  * 名稱：資源。
  * 值：後端應用程式應用程式 (用戶端) 識別碼。
- 若您使用 v2 端點：
  * 輸入您在 [預設範圍] 欄位中建立的後端應用程式範圍。
  * 在後端應用程式與用戶端應用程式註冊的應用程式資訊清單中，將 accessTokenAcceptedVersion 屬性的值設定為 2。
- 接受用戶端驗證方法與存取權杖傳送方法的預設設定。
在 [用戶端認證] 中，輸入您已在用戶端應用程式其建立和設定程序中取得的 [用戶端識別碼] 和 [用戶端祕密]。
指定 [用戶端識別碼] 與 [用戶端祕密] 之後，便會產生 [授權碼] 的 [重新導向 URI]。此 URI 可用於設定 OAuth 2.0 伺服器設定中的重新導向 URL。

在開發人員入口網站中，URI 尾碼格式如下：
- /signin-oauth/code/callback/{authServerName} 適用於授權碼授與流程
- /signin-oauth/implicit/callback 適用於隱含授與流程
將適當的重新導向 URI 複製到用戶端應用程式註冊的 [驗證] 頁面。在應用程式註冊中，選取 [驗證] > [+ 新增平台] > [Web]，然後輸入重新導向 URI。
如果將 [授權授與類型] 設定為 [資源擁有者密碼]，您便需要使用 [資源擁有者密碼認證] 區段來指定認證，若不想這麼做，則可以將授與類型保持空白。
選取 [建立]，儲存 API 管理 OAuth 2.0 授權伺服器設定。
重新發佈開發人員入口網站。

重要

進行 OAuth 2.0 相關變更時，請務必在每次修改後重新發佈開發人員入口網站，否則，相關變更 (例如範圍變更) 將無法傳播至入口網站並後續用於試用 API。

設定 API 使用 OAuth 2.0 使用者授權

儲存 OAuth 2.0 伺服器設定之後，設定一或多個 API 以使用此設定。

重要

針對 API 設定 OAuth 2.0 使用者授權設定，可讓 APIM 在您於 Azure 入口網站或開發人員入口網站中使用測試主控台時，向授權伺服器取得權杖。授權伺服器設定也會新增至 API 定義和文件。
針對執行階段的 OAuth 2.0 授權，用戶端應用程式必須取得並顯示權杖，而您必須在 APIM 或後端 API 中設定權杖驗證。如需範例，請參閱使用 OAuth 2.0 授權搭配 Microsoft Entra ID 保護 Azure APIM 中的 API。

選取左側 [API 管理] 功能表的 [API]。
選取所需 API 的名稱，然後選取 [設定] 索引標籤。捲動至 [安全性] 區段，然後選取 [OAuth 2.0]。
從下拉式清單選取所需的 [授權伺服器]，並選取 [儲存]。

開發人員入口網站 - 測試 OAuth 2.0 使用者授權

設定好 OAuth 2.0 授權伺服器，並將 API 設定為使用該伺服器後，您可以前往開發人員入口網站，並呼叫 API 來進行測試。

在 Azure API 管理執行個體 [概觀] 頁面的頂端功能表中，按一下 [開發人員入口網站]。
在開發人員入口網站中，瀏覽至 API 下的任何作業。
選取 [試試看]，系統會帶您前往開發人員主控台。
請注意，在 [授權] 區段中有一個新項目對應到您剛才新增的授權伺服器。
從授權下拉式清單中選取 [授權碼]。
出現提示之後，登入 Microsoft Entra 租用戶。
- 若已登入帳戶，系統則不會提示您。
成功登入之後，就會在要求中新增 Authorization 標頭，以及來自 Microsoft Entra ID 的存取權杖。以下為範例權杖縮寫 (Base64 編碼)：
```
Authorization: Bearer eyJ0eXAiOi[...]3pkCfvEOyA
```
設定其餘參數所需的值，然後選取 [傳送] 以呼叫 API。

設定 JWT 驗證原則來預先授權要求

在目前為止的設定中，API 管理不會驗證存取權杖。其只會將授權標頭中的權杖傳遞至後端 API。

若要預先授權要求，請設定 validate-jwt 原則來驗證每個傳入要求的存取權杖。若要求並無有效的權杖，則 API 管理會封鎖該要求。

下列範例原則在新增至 <inbound> 原則區段時，會檢查從 Microsoft Entra ID 所取得存取權杖中的對象宣告值，其會顯示在 Authorization 標頭中。若不是有效的權杖，則會傳回錯誤訊息。在適合您案例的原則範圍內，設定此原則。

在 openid-config URL 中，aad-tenant 是 Microsoft Entra ID 中的租用戶識別碼。例如，在 Azure 入口網站中，於 Microsoft Entra 資源的 [概觀] 頁面上，尋找此值。顯示的範例假設有一個單一租用戶 Microsoft Entra 應用程式和一個 v2 設定端點。
claim 的值是您在 Microsoft Entra ID 中所註冊後端應用程式的用戶端識別碼。

<validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url="https://login.microsoftonline.com/{aad-tenant}/v2.0/.well-known/openid-configuration" />
    <audiences>
        <audience>{audience-value - (ex:api://guid)}</audience>
    </audiences>
    <issuers>
        <issuer>{issuer-value - (ex: https://sts.windows.net/{tenant id}/)}</issuer>
    </issuers>
    <required-claims>
        <claim name="aud">
            <value>{backend-app-client-id}</value>
        </claim>
    </required-claims>
</validate-jwt>

注意

先前的 openid-config URL 會對應至 v2 端點。針對 v1 openid-config 端點，請使用 https://login.microsoftonline.com/{aad-tenant}/.well-known/openid-configuration。

如需如何設定原則的資訊，請參閱設定或編輯原則。如需更多有關 JWT 驗證的自訂資訊，請參閱 validate-jwt 參考。為了驗證 Microsoft Entra 服務所提供的 JWT，APIM 也會提供 validate-azure-ad-token 原則。

如需使用 OAuth 2.0 與 APIM 的詳細資訊，請參閱使用 OAuth 2.0 授權與 Microsoft Entra ID 保護 Azure APIM 中的 Web API 後端。
深入瞭解 Microsoft 身分識別平台和 OAuth 2.0 授權碼流程