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

2025-04-17

適用於：所有 API 管理層

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

驗證：利用使用 API 金鑰或 Microsoft Entra ID 受控識別進行驗證的原則，對 Azure OpenAI API 進行驗證。
授權：如需更精細的存取控制，請預先授權傳遞識別提供者 (例如 Microsoft Entra ID) 所產生之 OAuth 2.0 權杖的要求。

如需背景知識，請參閱：

必要條件

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

APIM 執行個體。如需範例步驟，請參閱建立 Azure APIM 執行個體。
Azure OpenAI 資源和模型已新增至您的 API 管理執行個體。如需範例步驟，請參閱將 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 金鑰儲存在具名值中

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

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

建立指向 Azure OpenAI API 的後端 (部分機器翻譯)。
1. 在 APIM 執行個體的左側功能表中，選取 [後端]。
2. 選擇 + 新增，然後為後端輸入描述性名稱。範例：openai-backend。
3. 在 [類型] 下，選取 [自訂]，然後輸入 Azure OpenAI 端點的 URL。範例：https://contoso.openai.azure.com/openai。
4. 在 [授權認證] 下，選取 [標頭]，然後輸入 api-key 作為標頭名稱，並輸入具名值作為值。
5. 選取 [建立]。
在 set-backend-service 原則區段中，新增下列 inbound 原則程式碼片段，在要求中將 API 金鑰傳遞至 Azure OpenAI API。

在此範例中，後端資源是 openai-backend。
```
<set-backend-service backend-id="openai-backend" />
```

在 API 要求中傳遞 API 金鑰 - 「set-header」策略

或者，在 set-header 原則區段中，新增下列 inbound 原則程式碼片段，在要求中將 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>

使用受控識別進行驗證

建議的替代方式驗證 Azure OpenAI API 是使用 Microsoft Entra ID 中的受控識別。如需背景資料，請參閱如何使用受管理的身分識別來設定 Azure OpenAI 服務。

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

針對 APIM 執行個體，啟用 (部分機器翻譯) 系統指派或使用者指派的受控識別。下列範例假設您已啟用執行個體的系統指派受控識別。
為受控識別指派認知服務 OpenAI 使用者角色，並將範圍限定為適當的資源。例如，為系統指派的受控識別指派 Azure OpenAI 資源上的認知服務 OpenAI 使用者角色。如需詳細步驟，請參閱 Azure OpenAI 服務的角色型存取控制。
或者，在 inbound 原則區段中新增下列原則程式碼片段，以使用受控識別來驗證對 Azure OpenAI API 的要求。

在此範例中：
- authentication-managed-identity 原則會取得受控識別的存取權杖。
- set-header (部分機器翻譯) 原則會使用存取權杖來設定要求的 Authorization 標頭。
```
<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> 
```

小提示

使用 authentication-managed-identity 此範例中顯示的和 set-header 原則的替代方法是設定後端資源，以將 API 要求導向至 Azure OpenAI 服務端點。在後端設定中，啟用 Azure OpenAI 服務的受控識別驗證。 Azure API 管理會在直接從 Azure OpenAI 服務匯入 API 時，自動化這些步驟。如需詳細資訊，請參閱從 Azure OpenAI 服務匯入 API。

使用識別提供者的 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 存取限制為使用識別提供者授權之使用者或應用程式的概略步驟。

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

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

在 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>

共用方式為