通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用 Azure API 管理对 Azure OpenAI API 进行身份验证和授权访问

  • 项目

适用于：所有 API 管理层级

本文介绍如何对使用 Azure API 管理托管的 Azure OpenAI API 终结点进行身份验证和授权。 本文介绍以下常见方法：

  • 身份验证 - 通过使用 API 密钥或 Microsoft Entra ID 托管标识进行身份验证的策略向 Azure OpenAI API 进行身份验证。

  • 授权 - 对于更精细的访问控制，预授权通过标识提供者（如 Microsoft Entra ID）生成的 OAuth 2.0 令牌的请求。

有关背景信息，请参阅：

先决条件

在按照本文中的步骤操作之前，必须具备：

使用 API 密钥进行身份验证

向 Azure OpenAI API 进行身份验证的默认方法是使用 API 密钥。 对于这种类型的身份验证，所有 API 请求都必须在 api-key HTTP 标头中包含有效的 API 密钥。

  • API 管理可以使用命名值以安全的方式管理 API 密钥。
  • 然后，可以在 API 策略中引用命名值，以将请求中的 api-key 标头设置为 Azure OpenAI API。 我们提供了两个如何执行此操作的示例：一个使用 set-backend-service 策略，另一个使用 set-header 策略。

将 API 密钥存储在命名值中

  1. 从 Azure OpenAI 资源获取 API 密钥。 在 Azure 门户中，在 Azure OpenAI 资源的“密钥和终结点”页上找到密钥。
  2. 转到 API 管理实例，然后在左侧菜单中选择“命名值”。
  3. 选择“+ 添加”，并将该值添加为机密，或者可以选择使用密钥保管库引用来增强安全性。

在 API 请求中传递 API 密钥 - set-backend-service 策略

  1. 创建指向 Azure OpenAI API 的后端。

    1. 在 API 管理实例的左侧菜单中，选择“后端”。
    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 标头。

在此示例中，API 管理中的命名值是 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 服务”。

以下步骤将 API 管理实例配置为使用托管标识对 Azure OpenAI API 的请求进行身份验证。

  1. 为 API 管理实例启用系统分配的或用户分配的托管标识。 以下示例假定你已启用实例的系统分配托管标识。

  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，可以使用具有 Microsoft Entra ID 或其他标识提供者的 OAuth 2.0 授权来预授权访问 Azure OpenAI API。 有关背景信息，请参阅“使用 OAuth 2.0 授权和 Microsoft Entra ID 保护 Azure API 管理中的 API”。

注意

使用 OAuth 2.0 授权作为深层防御策略的一部分。 它不能替代 API 密钥身份验证或 Azure OpenAI API 的托管标识身份验证。

以下是限制对使用标识提供者授权的用户或应用进行 API 访问的概括性步骤。

  1. 在标识提供者中创建一个应用程序，以在 Azure API 管理中表示 OpenAI API。 如果使用 Microsoft Entra ID，请在 Microsoft Entra ID 租户中注册一个应用程序。 记录应用程序 ID 和受众 URI 等详细信息。

    根据需要，将应用程序配置为具有表示访问 Azure OpenAI API 所需细化权限的角色或范围。

  2. 在 API 管理实例中添加策略 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>

相关内容