Compartir vía

Autenticación y autorización del acceso a las API de Azure OpenAI mediante Azure API Management

  • Artículo

SE APLICA A: todos los niveles de API Management

En este artículo, aprenderá formas de autenticación y autorización para puntos de conexión de la API de Azure OpenAI que se administran mediante Azure API Management. En este artículo se muestran los métodos comunes siguientes:

  • Autenticación: autentíquese en una API de Azure OpenAI mediante directivas que permitan la autenticación mediante una identidad administrada de Microsoft Entra ID o una clave de API.

  • Autorización: para obtener un control de acceso más minucioso, autorice previamente aquellas solicitudes que pasen tokens de OAuth 2.0 generados por un proveedor de identidades como Microsoft Entra ID.

Para obtener información general, consulte:

Requisitos previos

Para seguir los pasos de este artículo, debe tener:

Autenticación con la clave de API

Una manera predeterminada de autenticarse en una API de Azure OpenAI consiste en usar una clave de API. Para este tipo de autenticación, todas las solicitudes de API deben incluir una clave de API válida en el encabezado HTTP api-key.

  • API Management puede administrar la clave de API de forma segura mediante un valor con nombre.
  • A continuación, se puede hacer referencia al valor con nombre en una directiva de API para establecer el encabezado api-key en las solicitudes a la API de Azure OpenAI. Se proporcionan dos ejemplos de cómo hacerlo: uno usa la directiva set-backend-service y el otro usa la directiva set-header.

Almacenamiento de la clave de API en un valor con nombre

  1. Obtenga una clave de API del recurso de Azure OpenAI. En Azure Portal, busque una clave en la página Claves y punto de conexión del recurso de Azure OpenAI.
  2. Vaya a la instancia de API Management y seleccione Valores con nombre en el menú izquierdo.
  3. Seleccione + Agregar y agregue el valor como secreto o, de forma opcional, para obtener más seguridad, use una referencia del almacén de claves.

Pasar la clave de API en las solicitudes de API: directiva set-backend-service

  1. Cree un back-end que apunte a la API de Azure OpenAI.

    1. En el menú izquierdo de la instancia de API Management, seleccione Back-ends.
    2. Seleccione + Agregar y escriba un nombre descriptivo para el back-end. Ejemplo: openai-backend.
    3. En Tipo, seleccione Personalizado y escriba la dirección URL del punto de conexión de Azure OpenAI. Ejemplo: https://contoso.openai.azure.com/openai.
    4. En Credenciales de autorización, seleccione Encabezados y escriba api-key como nombre de encabezado y el valor con nombre como valor.
    5. Seleccione Crear.

  2. Agregue el siguiente fragmento de código de directiva set-backend-service en la sección de directiva inbound para pasar la clave de API en las solicitudes a la API de Azure OpenAI.

    En este ejemplo, el recurso de back-end es openai-backend.

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

Pasar la clave de API en las solicitudes de API: directiva set-header

Como alternativa, agregue el siguiente fragmento de código de directiva set-header en la sección de directiva inbound para pasar la clave de API en las solicitudes a la API de Azure OpenAI. Este fragmento de código de directiva establece el encabezado api-key con el valor con nombre que configuró.

En este ejemplo, el valor con nombre de API Management es openai-api-key.

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

Autenticación con una identidad administrada

Una manera alternativa de autenticarse en una API de Azure OpenAI mediante una identidad administrada en Microsoft Entra ID. Para obtener información general, consulte Configuración de Azure OpenAI Service con identidades administradas.

A continuación se indican los pasos para configurar su instancia de API Management para usar una identidad administrada para autenticar las solicitudes a una API de Azure OpenAI.

  1. Habilite una identidad administrada asignada por el sistema o por el usuario en la instancia de API Management. En el ejemplo siguiente se supone que ha habilitado la identidad administrada asignada por el sistema de la instancia.

  2. Asigne a la identidad administrada el rol Usuario de OpenAI de Cognitive Services, en el ámbito del recurso adecuado. Por ejemplo, asigne a la identidad administrada asignada por el sistema el rol Usuario de OpenAI de Cognitive Services en el recurso de Azure OpenAI. Para obtener pasos detallados, consulte Control de acceso basado en rol para Azure OpenAI Service.

  3. Agregue el siguiente fragmento de código de directiva en la sección de directiva inbound para autenticar las solicitudes a la API de Azure OpenAI mediante la identidad administrada.

    En este ejemplo:

    • La directiva authentication-managed-identity obtiene un token de acceso para la identidad administrada.
    • La directiva set-header establece el encabezado Authorization de la solicitud con el token de acceso.
    <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>

Autorización de OAuth 2.0 mediante el proveedor de identidades

Para permitir que determinados usuarios o clientes tengan un acceso más minucioso a las API de OpenAI, puede autorizar previamente el acceso a la API de Azure OpenAI mediante la autorización de OAuth 2.0 con Microsoft Entra ID u otro proveedor de identidades. Para obtener información general, consulte Protección de cualquier API en Azure API Management mediante la autorización de OAuth 2.0 con Microsoft Entra ID.

Nota:

Use la autorización de OAuth 2.0 como parte de una estrategia de defensa en profundidad. No sirve para reemplazar la autenticación mediante clave de API o la autenticación mediante identidad administrada en una API de Azure OpenAI.

A continuación, se muestran los pasos generales para restringir el acceso de la API a aquellos usuarios o aplicaciones que cuenten con autorización mediante un proveedor de identidades.

  1. Cree una aplicación en el proveedor de identidades para representar la API de OpenAI en Azure API Management. Si usa Microsoft Entra ID, registre una aplicación en el inquilino de Microsoft Entra ID. Registre detalles como el identificador de aplicación y el URI de audiencia.

    Según sea necesario, configure la aplicación para que tenga roles o ámbitos que representen los permisos específicos necesarios para acceder a la API de Azure OpenAI.

  2. Agregue un fragmento de código de directiva inbound en la instancia de API Management para validar aquellas solicitudes que presenten un JSON Web Token (JWT) en el encabezado Authorization. Coloque este fragmento de código antes que otras directivas inbound que establezca para autenticarse en la API de Azure OpenAI.

    Nota:

    En los ejemplos siguientes se muestra la estructura general de las directivas para validar un JWT. Adécuelos a su proveedor de identidades y los requisitos de su aplicación y API.

    • validate-azure-ad-token: si usa Microsoft Entra ID, configure la directiva validate-azure-ad-token para validar el público y las notificaciones en el JWT. Para obtener detalles, consulte la referencia de la directiva.

      <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: si usa otro proveedor de identidades, configure la directiva validate-jwt para validar el público y las notificaciones en el JWT. Para obtener detalles, consulte la referencia de la directiva.

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

Contenido relacionado