Autenticación y autorización en Microsoft Foundry

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 propio sistema de autenticación y control de acceso basado en roles (RBAC).

Foundry admite dos métodos de autenticación: Id. de Microsoft Entra 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.

Importante

Use Microsoft Entra ID para cargas de trabajo de producción para habilitar el acceso condicional, las identidades administradas y el RBAC con privilegios mínimos. Las claves de la API son cómodas para la evaluación rápida, pero proporcionan acceso de grano grueso.

Requisitos previos

Una suscripción de Azure. Si no tiene una, cree una cuenta gratuita.
Un recurso de Microsoft Foundry con un subdominio personalizado configurado.
Descripción de los conceptos de RBAC de Azure.
Para asignar roles, necesita el rol Propietario o el rol Administrador de acceso de usuarios en el ámbito correspondiente.
(Opcional) La CLI de Azure o el SDK de Azure para Python instalados 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

Las operaciones de Azure 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, use el plano de control para administrar los recursos de su suscripción y el plano de datos para usar las capacidades expuestas por su instancia de un tipo de recurso. Para más información sobre el plano de control y el plano de datos, consulte Plano de control y plano de datos de Azure. 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.

Avión	Alcance en Foundry	Operaciones típicas	Herramientas de ejemplo	Superficie de autorización
Plano de control	Configuración y configuración de recursos, proyectos, redes, cifrado y conexiones	Creación o eliminación de recursos, asignación de roles, rotación de claves, configuración de Private Link	Azure Portal, CLI de Azure, plantillas de ARM, Bicep, Terraform	Acciones de RBAC de Azure
Plano de datos	Ejecución y uso de la inferencia de modelos, interacciones de agentes, trabajos de evaluación y llamadas relacionadas con la seguridad del contenido	Finalizaciones de chat, generación de incrustaciones, inicio de trabajos de ajuste fino, envío de mensajes de agente, operaciones de analizador y clasificador	SDKs, APIs REST, zona de pruebas del portal Foundry	Acciones de datos de RBAC de Azure

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 de la fundición
Creación de proyectos de Foundry
Creación del host de funcionalidad de la cuenta
Creación del host de funcionalidad del proyecto
Implementación de modelos
Creación de conexiones de cuenta y de proyecto

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 la vista de la separación del plano de control frente al plano de datos en Foundry, junto con las asignaciones de control de acceso basado en roles (RBAC) y qué acceso podría tener un usuario en el plano de control, 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 el identificador de Microsoft Entra (basado en tokens, sin claves) y las claves de API.

Microsoft Entra ID

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

Use Microsoft Entra ID para:

Cargas de trabajo de producción.
Acceso condicional, autenticación multifactor (MFA) y acceso Just-In-Time.
Integración de RBAC con privilegios mínimos e identidad administrada.

Ventajas: asignaciones de roles detalladas, auditoría por principal, duraciones de tokens controlables, gestión automática de secretos e identidades administradas para los 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 API son secretos estáticos asociadas 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, las cargas de trabajo de producción empresariales no son aceptadas y no son recomendadas por Microsoft.

Para obtener más información sobre cómo habilitar la autenticación sin claves, consulte Configuración de la autenticación sin clave con el identificador de Microsoft Entra.

Autenticación con el identificador de Microsoft Entra (Python)

En el ejemplo siguiente se muestra cómo autenticarse con el identificador de Entra de Microsoft mediante la azure-identity biblioteca 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://ai.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())

Advertencia

Las claves de API proporcionan acceso completo al recurso y no se pueden limitar a usuarios o acciones específicos. Gire las claves con regularidad y evite confirmarlas en el control de código fuente.

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

Consulte la siguiente matriz para entender qué capacidades de Foundry son compatibles con la clave de API en comparación con Microsoft Entra ID.

Funcionalidad o característica	Clave de API	Microsoft Entra ID	Notas
Inferencia de modelos básica (chat, inserciones)	Sí	Sí	Totalmente compatible.
Operaciones de ajuste	Sí	Sí	Entra ID agrega auditoría por principal.
Servicio de agentes	No	Sí	Use Entra ID para el acceso a herramientas de identidad administrada.
Evaluaciones	No	Sí	Utilice Entra ID.
Análisis de las llamadas para la seguridad del contenido	Sí	Sí	Use RBAC para limitar las operaciones de alto riesgo.
Trabajos de análisis en lotes (Comprensión del Contenido)	Sí	Sí	Se recomienda Entra ID para la escala.
Uso del área de juegos del portal	Sí	Sí	Playground utiliza el modo de conexión a proyectos.
Aislamiento de red con Private Link	Sí	Sí	Entra ID agrega acceso condicional.
Privilegios mínimos con roles predefinidos y personalizados	No	Sí	Las claves son todo o nada por recurso.
Identidad administrada (asignada por el sistema o por el usuario)	No	Sí	Habilita la autenticación sin secretos.
Atribución de usuario por solicitud	No	Sí	El token contiene identificadores de inquilino y de objeto.
Revocación (inmediata)	Girar clave	Quitar rol o deshabilitar principal	Se aplica una duración corta del token.
Compatibilidad con canalizaciones de automatización	Sí (secreto)	Sí (entidad de servicio o identidad administrada)	Entra ID reduce la rotación de credenciales.
API de asistentes	Sí	Sí	Se recomienda usar entra ID.
Inferencia por lotes	Sí	Sí
Cuadro de herramientas	No	Sí	Use Entra ID para el acceso a herramientas de identidad administrada.

Tipos de identidad

Los recursos y las aplicaciones de Azure se autentican mediante diferentes tipos de identidad, cada uno diseñado para escenarios específicos. Los principios de usuario representan usuarios humanos, los principios de servicio representan aplicaciones o procesos automatizados, y las identidades administradas brindan un método seguro y exento de credenciales para que los recursos de Azure puedan tener acceso 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.

Tipo de identidad	Descripción
Principal de usuario	Usuario individual de Microsoft Entra ID
Entidad de servicio (registro de aplicaciones)	Identidad de la aplicación que usa un secreto de cliente o un certificado
Identidad administrada (asignada por el sistema)	Identidad enlazada a recursos de Azure administrada automáticamente por la plataforma.
Identidad administrada (asignada por el usuario)	Identidad independiente que se asocia a varios recursos.

Resumen de los roles integrados

Dentro de Foundry, usa los roles integrados para distinguir las acciones que se permiten para cada usuario. 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 un plano de datos y control combinados 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.

Escenario	Roles integrados típicos	Notas
Creación de agentes con modelos desplegados previamente	Usuario de Azure AI	Solo uso del plano de datos; sin escrituras de gestión.
Administrar implementaciones o ajustar modelos	Administrador de proyectos de Azure AI	Incluye la creación y actualización de la implementación del modelo.
Rotación de claves o administración de recursos	Propietario de la cuenta de Azure AI	Privilegios elevados; considere el rol personalizado para privilegios mínimos.
Gestión de recursos, gestión de implementaciones, agentes de construcción	Propietario de Azure AI	Rol de autoservicio con privilegios elevados para los usuarios que necesitan acceso tanto al plano de control como al plano de datos. Combine con el Lector de Azure Monitor si se requiere observabilidad.
Observabilidad, seguimiento, supervisión	Usuario de Azure AI (mínimo)	Agregue lector de Azure Monitor en Application Insights.

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

Propina

Cree un rol personalizado si un rol integrado concede permisos excesivos para su caso de uso.

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.

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.
Asigne el rol integrado o personalizado necesario a cada principal. Necesita el rol Propietario o el Administrador de acceso de usuarios en el ámbito de destino para asignar roles. Asignaciones de roles comunes:
- Usuario de Azure AI: para desarrolladores que necesitan compilar y probar con modelos implementados previamente.
- Administrador de proyectos de Azure AI: para los responsables del equipo que necesitan crear proyectos y administrar implementaciones.
- Propietario de la cuenta de Azure AI: para los administradores que necesitan administración completa de recursos y pueden asignar condicionalmente el usuario de Azure AI para el acceso al plano de datos.
- Propietario de Azure AI: para los usuarios que necesitan acceso completo a la administración de recursos y al plano de datos. Comando de la CLI de ejemplo para asignar el rol de usuario de Azure AI:
```
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.
(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.
(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.
Quite la autenticación basada en claves después de que todos los llamantes usen la autenticación con tokens. Opcionalmente, deshabilite la autenticación local en las plantillas de implementación.

Referencia: Asignación del | de Azure para Foundry

Solución de errores comunes de autenticación

Error	Causa	Resolución
401 No autorizado	Falta o ha expirado el token; clave de API no válida	Compruebe que el ámbito de adquisición de tokens es `https://ai.azure.com/.default`. Vuelva a generar la clave de API si usa la autenticación basada en claves.
403 Prohibido	Falta la asignación de roles de RBAC	Asigne el rol integrado adecuado (por ejemplo, usuario de Azure AI) en el ámbito del recurso o del proyecto.
AADSTS700016	No se encuentra la aplicación en el tenant	Compruebe que el registro de la aplicación existe en el inquilino correcto y que el identificador de cliente es correcto.
Subdominio personalizado necesario	El recurso usa un punto de conexión regional en lugar de un subdominio personalizado	Configure un subdominio personalizado en el recurso Foundry. La autenticación basada en tokens requiere un subdominio personalizado.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-04-30