共用方式為

使用 Azure APIM 對 Azure OpenAI API 的存取進行驗證和授權

  • 發行項

適用於：所有 APIM 層

在本文中，您將了解對使用 Azure APIM 管理的 Azure OpenAI API 端點進行驗證和授權的方式。 本文說明下列常見方法：

  • 驗證：利用使用 API 金鑰或 Microsoft Entra ID 受控識別進行驗證的原則，對 Azure OpenAI API 進行驗證。

  • 授權：如需更精細的存取控制，請預先授權傳遞識別提供者 (例如 Microsoft Entra ID) 所產生之 OAuth 2.0 權杖的要求。

如需背景知識，請參閱：

必要條件

依照本文中的步驟進行之前，您必須有：

  • API 管理執行個體。 如需範例步驟，請參閱建立 Azure APIM 執行個體。
  • 新增至 APIM 執行個體的 Azure OpenAI 資源和模型。 如需範例步驟，請參閱將 Azure OpenAI API 匯入為 REST API (英文)。
  • 在識別提供者 (例如，與您 Azure 訂用帳戶相關聯的 Microsoft Entra 租用戶) 中建立應用程式註冊的權限 (適用於 OAuth 2.0 授權)。

使用 API 金鑰進行驗證

對 Azure OpenAI API 進行驗證的預設方式是使用 API 金鑰。 針對此類型的驗證，所有 API 要求都必須在 api-key HTTP 標頭中包含有效的 API 金鑰。

  • APIM 可以使用具名值，以安全的方式管理 API 金鑰。
  • 接著，可在 API 原則中參考具名值，以將要求中的 api-key 標頭設定為 Azure OpenAI API。 我們提供兩個如何執行此作業的範例：一個使用 set-backend-service (部分機器翻譯) 原則，另一個則使用 set-header (部分機器翻譯) 原則。

將 API 金鑰儲存在具名值中

  1. 從 Azure OpenAI 資源取得 API 金鑰。 在 Azure 入口網站中，於 Azure OpenAI 資源的 [金鑰與端點] 頁面上尋找金鑰。
  2. 瀏覽至您的 APIM 執行個體，然後選取左側功能表中的 [具名值]。
  3. 選取 [+ 新增]，然後將值新增為祕密，或者選擇性地使用金鑰保存庫參考來提高安全性。

在 API 要求中傳遞 API 金鑰 - set-backend-service 原則

  1. 建立指向 Azure OpenAI API 的後端 (部分機器翻譯)。

    1. 在 APIM 執行個體的左側功能表中，選取 [後端]。
    2. 選取 [+ 新增]，然後為後端輸入描述性名稱。 範例：openai-backend。
    3. 在 [類型] 下，選取 [自訂]，然後輸入 Azure OpenAI 端點的 URL。 範例：https://contoso.openai.azure.com/openai。
    4. 在 [授權認證] 下，選取 [標頭]，然後輸入 api-key 作為標頭名稱，並輸入具名值作為值。
    5. 選取 建立。

  2. 在 inbound 原則區段中，新增下列 set-backend-service 原則程式碼片段，在要求中將 API 金鑰傳遞至 Azure OpenAI API。

    在此範例中，後端資源是 openai-backend。

    <set-backend-service backend-id="openai-backend" />

在 API 要求中傳遞 API 金鑰 - set-header 原則

或者，在 inbound 原則區段中，新增下列 set-header 原則程式碼片段，在要求中將 API 金鑰傳遞至 Azure OpenAI API。 此原則程式碼片段會使用您設定的具名值來設定 api-key 標頭。

在此範例中，APIM 中的具名值為 openai-api-key。

<set-header name="api-key" exists-action="override">
    <value>{{openai-api-key}}</value>
</set-header>

使用受控識別進行驗證

使用 Microsoft Entra ID 中的受控識別來對 Azure OpenAI API 進行驗證的替代方式。 如需背景知識，請參閱如何使用受控識別設定 Azure OpenAI 服務 (部分機器翻譯)。

下列步驟可將您的 APIM 執行個體設定為使用受控識別來驗證對 Azure OpenAI API 的要求。

  1. 針對您的 APIM 執行個體，啟用 (部分機器翻譯) 系統指派或使用者指派的受控識別。 下列範例假設您已啟用執行個體的系統指派受控識別。

  2. 為受控識別指派認知服務 OpenAI 使用者角色，並將範圍限定為適當的資源。 例如，為系統指派的受控識別指派 Azure OpenAI 資源上的認知服務 OpenAI 使用者角色。 如需詳細步驟，請參閱 Azure OpenAI 服務的角色型存取控制 (部分機器翻譯)。

  3. 或者，在 inbound 原則區段中新增下列原則程式碼片段，以使用受控識別來驗證對 Azure OpenAI API 的要求。

    在此範例中：

    <authentication-managed-identity resource="https://cognitiveservices.azure.com" output-token-variable-name="managed-id-access-token" ignore-error="false" /> 
<set-header name="Authorization" exists-action="override"> 
    <value>@("Bearer " + (string)context.Variables["managed-id-access-token"])</value> 
</set-header>

使用識別提供者的 OAuth 2.0 授權

若要讓特定使用者或用戶端更精細地存取 OpenAPI API，您可以使用 OAuth 2.0 授權搭配 Microsoft Entra ID 或其他識別提供者，預先授權對 Azure OpenAI API 的存取。 如需背景知識，請參閱使用 OAuth 2.0 授權搭配 Microsoft Entra ID 保護 Azure APIM 中的 API (部分機器翻譯)。

注意

使用 OAuth 2.0 授權作為深層防禦策略的一部分。 它不能將 API 金鑰驗證或受控識別驗證取代為 Azure OpenAI API。

以下為可將 API 存取限制為使用識別提供者授權之使用者或應用程式的概略步驟。

  1. 在識別提供者中建立應用程式，以代表 Azure APIM 中的 OpenAI API。 如果您使用 Microsoft Entra ID，請在 Microsoft Entra ID 租用戶中註冊 (部分機器翻譯) 應用程式。 記錄應用程式識別碼和受眾 URI 等詳細資料。

    視需要，將應用程式設定為具有代表存取 Azure OpenAI API 所需之細微權限的角色或範圍。

  2. 在 APIM 執行個體中新增 inbound 原則程式碼片段，以驗證 Authorization 標頭中呈現 JSON Web 權杖 (JWT) 的要求。 將此程式碼片段放置於您設定來對 Azure OpenAI API 進行驗證的其他 inbound 原則「之前」。

    注意

    下列範例顯示可驗證 JWT 之原則的一般結構。 將其自訂至您的識別提供者，以及應用程式和 API 的需求。

    • validate-azure-ad-token：如果您使用 Microsoft Entra ID，請設定 validate-azure-ad-token 原則來驗證 JWT 中的受眾和宣告。 如需詳細資料，請參閱原則參考 (部分機器翻譯)。

      <validate-azure-ad-token tenant-id={{TENANT_ID}} header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <client-application-ids>
            <application-id>{{CLIENT_APP_ID}}</application-id>
    </client-application-ids>
   <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-azure-ad-token>

    • validate-jwt：如果您使用其他識別提供者，請設定 validate-jwt 原則來驗證 JWT 中的受眾和宣告。 如需詳細資料，請參閱原則參考 (部分機器翻譯)。

      <validate-jwt header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized. Access token is missing or invalid.">
    <openid-config url={{OPENID_CONFIGURATION_URL}} />
    <issuers>
        <issuer>{{ISSUER_URL}}</issuer>
    </issuers>
    <audiences>
        <audience>...</audience> 
    </audiences>
    <required-claims>
        <claim name=...>
            <value>...</value>
        </claim>
    </required-claims>
</validate-jwt>

相關內容