Autenticación y autorización en Microsoft Foundry (clásico)

La autenticación y la autorización en Microsoft Foundry controlan cómo los principales verifican su identidad y obtienen permiso para realizar operaciones. Foundry divide las operaciones en el plano de control (administración de recursos) y el plano de datos (uso en tiempo de ejecución), cada uno con su propia superficie de autenticación y control de acceso basado en roles (RBAC).

Foundry admite dos métodos de autenticación: Microsoft Entra ID y claves de API. Microsoft Entra ID habilita el acceso condicional, las identidades administradas y el RBAC pormenorizado. Las claves de API siguen estando disponibles para crear prototipos rápidos, pero carecen de rastreabilidad por usuario. En este artículo se comparan estos métodos, se asignan identidades a roles y se describen escenarios comunes de privilegios mínimos.

Prerrequisitos

• Una suscripción Azure. En caso de no tener ninguna, cree una cuenta gratuita.
• Un recurso de Microsoft Foundry con un subdominio personalizado configurado.
• Comprensión de conceptos de Azure RBAC.
• Para asignar roles, necesita el rol de Propietario o el rol de Administrador de Acceso de Usuario en el ámbito adecuado.
• (Opcional) El Azure CLI o Azure SDK para Python instalado para la autenticación mediante programación.
• (Opcional) paquetes de Python para ejemplos de código: pip install azure-identity requests

Plano de control y plano de datos

Azure las operaciones se dividen en dos categorías: plano de control y plano de datos. Azure separa la administración de recursos (plano de control) del entorno de ejecución operativo (plano de datos). Por lo tanto, utilice el plano de control para administrar los recursos de su suscripción y el plano de datos para utilizar las capacidades expuestas por su instancia de un tipo de recurso. Para obtener más información sobre el plano de control y el plano de datos, consulte Azure plano de control y plano de datos. En Foundry, hay una distinción clara entre las operaciones del plano de control y las operaciones del plano de datos. En la tabla siguiente se explica la diferencia entre los dos, el ámbito de Foundry, las operaciones típicas de un usuario, herramientas y características de ejemplo, y la superficie de autorización para usar cada una.

Para ver todos los ejemplos de Bicep, Terraform y SDK, consulte el repositorio foundry-samples en GitHub for Foundry.

En las listas y diagramas siguientes se muestra la separación entre las acciones del plano de control y del plano de datos en detalle. Las acciones del plano de control dentro de Foundry incluyen:

• Creación de recursos en una fundición
• Creación de proyectos de Foundry
• Capacidad de la cuenta Creación de hosts
• Capacidad del proyecto Creación de hosts
• Implementación del modelo
• Creación de conexión de cuentas y proyectos

Las acciones del plano de datos dentro de Foundry incluyen:

• Creación de agentes
• Ejecución de una evaluación
• Seguimiento y supervisión
• Ajuste preciso

En el diagrama siguiente se muestra una comparativa entre el plano de control y la separación del plano de datos en Foundry, junto con las asignaciones de control de acceso basado en roles (RBAC) y el acceso que un usuario podría tener en el plano de control, en el plano de datos o en ambos. Como se muestra en el diagrama, las "acciones" de RBAC están asociadas al plano de control mientras que RBAC "dataActions" están asociados con el plano de datos.

Métodos de autenticación

Foundry admite Microsoft Entra ID (basadas en tokens, sin claves) y claves de API.

Microsoft Entra ID

Microsoft Entra ID usa tokens de portador de OAuth 2.0 con ámbito limitado a https://cognitiveservices.azure.com/.default.

Utilice Microsoft Entra ID para:

• Cargas de trabajo de producción.
• Acceso condicional, autenticación multifactor (MFA) y acceso Just-In-Time.
• RBAC de privilegios mínimos e integración de identidades administradas.

Ventajas: asignaciones de roles específicas, auditoría por entidad de seguridad, vigencia de tokens controlables, protección automática de secretos e identidades administradas para servicios.

Limitaciones: mayor complejidad de configuración inicial. Requiere la comprensión del control de acceso basado en rol (RBAC). Para obtener más información sobre RBAC en Foundry, consulte Control de acceso basado en rol para Microsoft Foundry.

claves de API

Las claves de API son secretos estáticos asociados a un recurso de Foundry.

Use claves de API para:

• Creación rápida de prototipos.
• Entornos de prueba aislados en los que la rotación de secretos únicos es aceptable.

Ventajas: simple, independiente del lenguaje y no requiere la adquisición de tokens.

Limitaciones: no se puede expresar la identidad del usuario, es difícil definir el ámbito pormenorizado y es más difícil de auditar. Por lo general, no es aceptado por las cargas de trabajo de producción empresariales y no es recomendado por Microsoft.

Para obtener más información sobre cómo habilitar la autenticación sin claves, consulte Configurar la autenticación sin clave con Microsoft Entra ID.

Autenticación con Microsoft Entra ID (Python)

En el ejemplo siguiente se muestra cómo autenticarse con Microsoft Entra ID mediante la biblioteca de azure-identity y realizar una solicitud a un punto de conexión de Foundry:

from azure.identity import DefaultAzureCredential
import requests

# Create a credential object using DefaultAzureCredential
# This automatically uses environment variables, managed identity, or Azure CLI credentials
credential = DefaultAzureCredential()

# Get an access token for the Cognitive Services scope
token = credential.get_token("https://cognitiveservices.azure.com/.default")

# Use the token in your API request
headers = {
    "Authorization": f"Bearer {token.token}",
    "Content-Type": "application/json"
}

# Replace with your Foundry endpoint
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

# Example: List deployments (adjust the path for your specific API)
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Salida esperada: una respuesta JSON que enumera las implementaciones del modelo o un error de autenticación si faltan credenciales o la asignación de roles no está configurada.

Referencia: DefaultAzureCredential | azure-identity library

Autenticación con una clave de API (Python)

En el ejemplo siguiente se muestra cómo autenticarse mediante una clave de API. Use este enfoque solo para crear prototipos rápidos; Microsoft Entra ID se recomienda para producción.

import requests

# Replace with your actual API key and endpoint
api_key = "<your-api-key>"
endpoint = "https://<your-resource-name>.cognitiveservices.azure.com"

headers = {
    "api-key": api_key,
    "Content-Type": "application/json"
}

# Example: List deployments
response = requests.get(f"{endpoint}/openai/deployments?api-version=2024-10-21", headers=headers)
print(response.json())

Salida esperada: una respuesta JSON que enumera las implementaciones del modelo o un error 401 si la clave de API no es válida.

Referencia: Rotación de claves de acceso de API

Matriz de compatibilidad de características

Haga referencia a la siguiente matriz para entender qué capacidades en Foundry admiten la clave de API frente a Microsoft Entra ID.

Tipos de identidad

Azure recursos y aplicaciones se autentican mediante diferentes tipos de identidad, cada uno diseñado para escenarios específicos. Las entidades de seguridad de usuario representan a los usuarios humanos, las entidades de servicio representan aplicaciones o procesos automatizados, y las identidades administradas proporcionan un modo seguro y sin necesidad de credenciales para que los recursos de Azure accedan a otros servicios. Comprender estas distinciones le ayuda a elegir la identidad adecuada para inicios de sesión interactivos, comunicación entre aplicaciones o automatización de cargas de trabajo.

Azure admite los siguientes tipos de identidad.

Introducción a los roles integrados

En Foundry, utiliza los roles predeterminados para separar las acciones permitidas para los usuarios. La mayoría de las empresas quieren una separación de las acciones de control y plano de datos para sus roles integrados. Otros esperan una función combinada de datos y plano de control para minimizar el número de asignaciones de roles necesarias. En la tabla siguiente se enumeran los escenarios y los roles integrados de Foundry correspondientes que mejor se ajustan a cada escenario.

Para comprender el desglose de los roles integrados y las acciones de control y plano de datos, revise el diagrama siguiente.

Configuración de Microsoft Entra ID

Para obtener instrucciones de alto nivel sobre cómo configurar la autenticación entra ID en Foundry, consulte Configuración de la autenticación sin clave.

1. Asegúrese de que el recurso de Microsoft Foundry tiene configurado un subdominio personalizado. Consulte Subdominios personalizados. Se requiere un subdominio personalizado para la autenticación basada en tokens.

2. Asigne el rol integrado o personalizado necesario a cada principal. Necesita el rol Propietario o Administrador de acceso de usuarios en el ámbito de destino para asignar roles. Asignaciones de roles comunes:

   • Azure usuario de IA: para desarrolladores que necesitan compilar y probar con modelos implementados previamente.
   • Azure AI Project Manager: para los responsables del equipo que necesitan crear proyectos y administrar implementaciones.
   • Azure AI Account Owner: para los administradores que necesitan gestión completa de recursos y pueden asignar condicionalmente Azure AI User para el acceso al plano de datos.
   • Azure AI Owner: Para los usuarios que necesitan tanto la administración completa de recursos como el acceso al plano de datos. Comando de ejemplo de la CLI para asignar el rol de Usuario de IA de Azure:

   az role assignment create \
     --assignee <principal-id> \
     --role "Azure AI User" \
     --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<resource-name>
   

   Para comprobar la asignación de roles, ejecute az role assignment list --assignee <principal-id> --scope <resource-scope> y confirme que el rol aparece en la salida.

3. (Opcional) Para una entidad de servicio, cree un registro de aplicación, agregue un secreto de cliente o certificado y anote el identificador de inquilino, el identificador de cliente y el secreto o el certificado.

4. (Opcional) Para una identidad administrada, habilite la identidad asignada por el sistema en el servicio de llamada o adjunte una identidad asignada por el usuario y asígnele un rol en el recurso Foundry.

5. Quite la autenticación basada en claves después de que todos los usuarios utilicen la autenticación basada en tokens. Opcionalmente, deshabilite la autenticación local en las plantillas de implementación.

Referencia: Asignar roles de Azure | Control de acceso basado en roles para Foundry

Solución de errores comunes de autenticación

Contenido relacionado

• Control de acceso basado en rol para Foundry
• Configurar la autenticación sin clave con Microsoft Entra ID
• Rotación de claves de acceso de API
• Azure roles integrados (IA y aprendizaje automático)
• Autenticación vs. autorización (Microsoft Entra ID)
• Aspectos básicos de la identidad