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

SE APLICA A: Todos los niveles de API Management

En este artículo, aprenderá a autenticar y autorizar el acceso a los puntos de conexión de la API de IA gestionados por Azure API Management. En este artículo se muestran los métodos comunes siguientes:

• Autenticación : autentíquese en una API de IA mediante directivas que usan una clave de API o una identidad administrada de Microsoft Entra ID.

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

• Autenticación y autorización para las API en API Management

Prerrequisitos

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

• Una instancia de API Management Para ver pasos de ejemplo, consulte Creación de una instancia de Azure API Management.
• Una implementación de modelo de IA añadida a su instancia de API Management como IA. Para ver los pasos de ejemplo, consulte Importación de una API de Microsoft Foundry o Importación de una API de modelo de lenguaje.
• (Para la autorización de OAuth 2.0) Permisos para crear un registro de una aplicación en un proveedor de identidades, como un inquilino de Microsoft Entra ID asociado a su suscripción de Azure.

Autenticación mediante la clave de API

Una manera predeterminada de autenticarse en una API de IA es mediante una clave de API. Para este tipo de autenticación, todas las solicitudes de API deben incluir una clave de API válida en un encabezado HTTP. El nombre del encabezado depende de la API. Por ejemplo, Azure OpenAI en la API de Microsoft Foundry usa el encabezado api-key.

• API Management puede administrar la clave de API de forma segura mediante un valor con nombre.
• Puede hacer referencia al valor con nombre en una directiva de API para establecer el encabezado api-key en las solicitudes a la API. Los dos ejemplos siguientes muestran cómo hacerlo: uno usa la set-backend-service directiva y el otro usa la set-header directiva.

Almacenamiento de la clave de API en un valor con nombre

Este es un ejemplo de cómo almacenar una clave de API de Azure OpenAI en un valor con nombre en API Management:

1. Obtenga una clave de API de la implementación del modelo de IA. Para una implementación de modelos de Azure OpenAI, busque esta información en la página Principal del proyecto en el portal de Microsoft Foundry.
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. Para obtener más seguridad, opcionalmente use una referencia de 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.services.ai.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. Selecciona 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

En el caso de Azure OpenAI y otras implementaciones de modelos en Microsoft Foundry, use una identidad administrada en Microsoft Entra ID para autenticarse. Para obtener información general, consulte Configuración de Azure OpenAI en modelos de Microsoft Foundry con autenticación de Id. de Microsoft Entra.

Siga estos pasos para configurar la instancia de API Management para usar una identidad administrada para la autenticación.

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 la identidad administrada al rol Usuario de OpenAI de Cognitive Services, con ámbito al recurso adecuado. Por ejemplo, asigne a la identidad administrada asignada por el sistema el rol Cognitive Services OpenAI User en el recurso de Microsoft Foundry. 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 inbound sección directiva para autenticar las solicitudes a la API 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 habilitar el acceso más específico a Azure OpenAPI u otras API de LLM por parte de usuarios o clientes concretos, autorice previamente el acceso a la API 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.

Los pasos siguientes muestran cómo restringir el acceso de API a usuarios o aplicaciones que están autorizados mediante un proveedor de identidades.

1. Cree una aplicación en el proveedor de identidades para representar la API de IA en Azure API Management. Si usa el Microsoft Entra ID, registrar 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 IA.

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

• Obtenga más información sobre Microsoft Entra ID y OAuth2.0.
• Autenticación de solicitudes a las herramientas de Foundry