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 propia superficie 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 API son útiles para realizar evaluaciones rápidas, pero proporcionan un acceso poco preciso.

Prerrequisitos

Una suscripción a Azure. En caso de no tener ninguna, 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 de Propietario o el rol de Administrador de Acceso de Usuario en el ámbito adecuado.
(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, 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 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	Ámbito 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 de seguridad del contenido	Finalizaciones de conversaciones, generación de embeddings, inicio de trabajos de ajuste fino, envío de mensajes de agente, operaciones de analizador y clasificador	SDKs, APIs REST, área de juegos del portal Foundry	Azure RBAC dataActions

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
Creación del host de funcionalidad de la cuenta
Creación del host de funcionalidad del proyecto
Implementación de 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 el identificador de Microsoft Entra (basado en tokens, sin claves) y las claves de API.

Microsoft Entra ID

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

Utiliza 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 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, 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://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())

Advertencia

Las claves de API proporcionan acceso completo al recurso y no se pueden limitar a usuarios o acciones específicos. Realice la rotación de 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

Haga referencia a la siguiente matriz para comprender qué capacidades de Foundry son compatibles con clave de API frente a Microsoft Entra ID.

Funcionalidad o característica	API key	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 para cada principal.
Servicio de agentes	No	Sí	Use Entra ID para el acceso a herramientas de identidad administrada.
Evaluations	No	Sí	Utiliza Entra ID.
Análisis de la seguridad del contenido de llamadas	Sí	Sí	Use RBAC para limitar las operaciones de alto riesgo.
Trabajos de análisis por lotes (Comprensión de Contenido)	Sí	Sí	Id. de Entra recomendado para la escala.
Uso del área de juegos del portal	Sí	Sí	El Playground utiliza el modo de conexión del proyecto.
Aislamiento de red con Private Link	Sí	Sí	Entra ID agrega acceso condicional.
Privilegio mínimo con funciones predeterminadas y personalizadas	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 inhabilitar 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 secretos.
Asistentes API	Sí	Sí	Se recomienda usar entra ID.
Inferencia por lotes	Sí	Sí

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. Las principales de usuario representan a usuarios humanos, las principales de servicio representan a aplicaciones o procesos automatizados, y las identidades administradas proporcionan una forma segura sin necesidad de credenciales para que los recursos de Azure puedan acceder 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	Description
Principal de usuario	Usuario individual de Microsoft Entra ID
Principal de servicio (registro de aplicación)	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.

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.

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 administració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.
Gestionar recursos, gestionar implementaciones, construir agentes	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.

Sugerencia

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 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 usuarios utilicen la autenticación basada en 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://cognitiveservices.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 inquilino	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-02-28