共用方式為

使用 OAuth 2.0 授權搭配 Microsoft Entra ID 保護 Azure APIM 中的 API

適用於：所有 APIM 層

在本文中，您將瞭解如何使用 Microsoft Entra ID 搭配 OAuth 2.0 通訊協定 來設定您的 Azure API 管理實例，以保護 API 的高階步驟。

如需 API 授權的概念概觀，請參閱 APIM 中的 API 驗證和授權。

先決條件

在執行本文中的步驟之前，您必須具備：

  • API 管理執行個體
  • 使用 API 管理執行個體的已發佈 API
  • A Microsoft Entra 租用戶

概觀

依照下列步驟，使用 OAuth 2.0 授權和 Microsoft Entra ID 保護 Azure APIM 中的 API。

  1. 在 Microsoft Entra ID 中註冊應用程式 （在本文中稱為 backend-app ）。

    若要存取 API，使用者或應用程式必須取得並出示有效的 OAuth 權杖，以透過每個 API 請求授予對此應用程式的存取權。

  2. 在 API 管理 中設定 validate-jwt 原則。 此原則會驗證每個傳入 API 要求中呈現的 OAuth 權杖。 有效的要求可以傳遞至 API。

OAuth 授權流程的詳細資料，以及如何產生必要的 OAuth 權杖，均已超出本文討論範圍。 一般而言，個別的用戶端應用程式是用來向 Microsoft Entra ID 取得權杖，以授權存取 API。 如需詳細資訊的連結，請參閱 相關內容 區段。

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

使用 Azure 入口網站，透過先註冊代表 API 的應用程式，使用 Microsoft Entra ID 來保護 API。

如需應用程式註冊的詳細資訊，請參閱快速入門：設定應用程式以公開 Web API。

  1. 在 Azure 入口網站中，搜尋並選取 [應用程式註冊]。

  2. 選取 [新增註冊]。

  3. 當 [註冊應用程式] 頁面出現時，輸入您應用程式的註冊資訊：

    • 在 [名稱 ] 區段中，輸入有意義的應用程式名稱，例如 backend-app。 此名稱會顯示給應用程式的使用者。
    • 在 [支援的帳戶類型 ] 區段中，選取適合您情節的選項。

  4. 將 [重新導向 URI] 區段保持空白。

  5. 選取 [註冊] 以建立應用程式。

  6. 在應用程式 [概觀] 頁面上，尋找 [應用程式 (用戶端) 識別碼] 值並將它記下供稍後使用。

  7. 在側邊功能表的 [管理] 區段下，選取 [公開 API]，並使用預設值設定應用程式識別碼 URI。 如果您要開發個別的用戶端應用程式來取得 OAuth 2.0 權杖，以存取後端應用程式，請於稍後記錄此值。

  8. 選取 [新增範圍] 按鈕，以顯示 [新增範圍] 頁面：

    1. 輸入新的範圍名稱、系統管理員同意顯示名稱，以及管理員同意描述。
    2. 確定已選取 [已啟用] 範圍狀態。

  9. 選取 [新增範圍] 按鈕以建立範圍。

  10. 請重複上述兩個步驟，以新增 API 支援的所有範圍。

  11. 建立範圍後，請記下來，以供往後使用。

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

下列範例原則在新增至 <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 原則。

授權工作流程

  1. 使用者或應用程式會從 Microsoft Entra ID 取得權杖，此權杖具有授與後端應用程式存取權的授權。 如果您使用 v2 端點，請確定 accessTokenAcceptedVersion 在後端應用程式和您設定的任何用戶端應用程式的應用程式資訊清單中將屬性設定為 2 。

  2. 權杖會新增至對 API 管理之 API 要求的授權標頭中。

  3. API 管理會使用 validate-jwt 原則來驗證權杖。

    • 若要求並無有效的權杖，則 API 管理會封鎖該要求。

    • 如果要求具有有效的權杖，閘道可以將要求轉送至 API。

相關內容

  • Last updated on