Configuración de la autenticación sin claves con Microsoft Entra ID

En este artículo se explica cómo configurar la autenticación sin claves con Microsoft Entra ID para los Microsoft Foundry Models. La autenticación sin claves mejora la seguridad al eliminar la necesidad de claves de API, simplifica la experiencia del usuario con el control de acceso basado en rol (RBAC) y reduce la complejidad operativa, al tiempo que proporciona una sólida compatibilidad con el cumplimiento.

Requisitos previos

Para completar este artículo, necesita lo siguiente:

Roles y permisos de Azure necesarios

Microsoft Entra ID usa el control de acceso basado en rol (RBAC) para administrar el acceso a los recursos de Azure. Necesita distintos roles, en función de si va a configurar la autenticación (administrador) o su uso para realizar llamadas API (desarrollador).

Para configurar la autenticación

  • Propietario o administrador de la suscripción: una cuenta con permisos Microsoft.Authorization/roleAssignments/write y Microsoft.Authorization/roleAssignments/delete, como el rol de Propietario o Administrador de Acceso de Usuarios, necesario para asignar el rol de Usuario de Servicios Cognitivos a los desarrolladores.

Para realizar llamadas API autenticadas

  • rol Cognitive Services User: obligatorio para que los desarrolladores autentiquen y realicen llamadas API de inferencia mediante Microsoft Entra ID. Este rol debe asignarse en el ámbito de su recurso de Foundry.

Requisitos de asignación de roles

Al asignar roles, especifique estos tres elementos:

  • Entidad de seguridad: la cuenta de usuario, entidad de servicio o grupo de seguridad (recomendado para administrar varios usuarios)
  • Definición de rol: el rol de Usuario de Cognitive Services
  • Ámbito: su recurso específico de Foundry

Sugerencia

Las asignaciones de roles de Azure pueden tardar hasta 5 minutos en propagarse. Al usar grupos de seguridad, los cambios en la pertenencia a grupos se propagan inmediatamente.

Rol personalizado (opcional)

Si prefiere un rol personalizado en lugar de un usuario de Cognitive Services, asegúrese de que incluye estos permisos:

{
  "permissions": [
    {
      "dataActions": [
        "Microsoft.CognitiveServices/accounts/MaaS/*"
      ]
    }
  ]
}

Para obtener más contexto sobre cómo funcionan los roles con recursos de Azure, consulte Understand roles en el contexto del recurso en Azure.

Configuración de Microsoft Entra ID para la inferencia

En esta sección se enumeran los pasos para configurar Microsoft Entra ID para la inferencia desde la página de recursos Microsoft Foundry en el portal Azure.

Captura de pantalla que muestra el recurso para el cual configuramos Microsoft Entra ID.

  1. Seleccione el nombre del recurso para abrirlo.

  2. En el panel izquierdo, seleccione Control de acceso (IAM) y, a continuación, seleccione Agregar asignación> deroles.

    Screenshot que muestra cómo agregar una asignación de un rol en la sección Control de acceso del recurso en el portal de Azure.

    Sugerencia

    Use la opción Ver mi acceso para comprobar qué roles ya están asignados.

  3. En Roles de trabajo, escriba Usuario de Cognitive Services.

    Captura de pantalla que muestra cómo seleccionar la asignación de roles de usuario de Cognitive Services.

  4. Seleccione el rol y seleccione Siguiente.

  5. En Miembros, seleccione el usuario o grupo al que desea conceder acceso. Use grupos de seguridad siempre que sea posible porque son más fáciles de administrar y mantener.

    Captura de pantalla que muestra cómo seleccionar el usuario al que se asigna el rol.

  6. Seleccione Siguiente y finalice el asistente.

  7. El usuario seleccionado ahora puede usar Microsoft Entra ID para la inferencia.

    Sugerencia

    Las asignaciones de roles de Azure pueden tardar hasta cinco minutos en propagarse. Al trabajar con grupos de seguridad, agregar o quitar usuarios del grupo de seguridad se propaga inmediatamente.

  8. Compruebe la asignación de roles:

    1. En el panel izquierdo del portal de Azure, seleccione Access control (IAM).

    2. Seleccione Comprobar acceso.

    3. Busque el usuario o grupo de seguridad al que asignó el rol.

    4. Compruebe que el usuario de Cognitive Services aparece en sus roles asignados.

El acceso basado en claves sigue siendo posible para los usuarios que ya tienen claves disponibles para ellos. Para revocar las claves, en Azure portal, en el panel de navegación izquierdo, seleccione Resource Management>Keys and Endpoints>Regenerate Key1 y Regenerate Key2.

Usa Microsoft Entra ID en tu código

Después de configurar Microsoft Entra ID en el recurso, actualice el código para usarlo al consumir el punto de conexión de inferencia. En este ejemplo se muestra cómo usar un modelo de finalizaciones de chat:

Instale el SDK de OpenAI mediante un administrador de paquetes como pip:

pip install openai

Para la autenticación de Microsoft Entra ID, instale también:

pip install azure-identity

Use el paquete para consumir el modelo. En el ejemplo siguiente se muestra cómo crear un cliente para consumir finalizaciones de chat con Microsoft Entra ID y realizar una llamada de prueba al punto de conexión de finalizaciones de chat con la implementación del modelo.

Reemplace <resource> con el nombre de su recurso Foundry. Encuéntrelo en el portal de Azure o bien ejecutando az cognitiveservices account list. Reemplace DeepSeek-V3.1 con su nombre de implementación real.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), 
    "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://<resource>.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

completion = client.chat.completions.create(
    model="DeepSeek-V3.1",  # Required: your deployment name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Azure AI?"}
    ]
)

print(completion.choices[0].message.content)

Salida esperada

Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.

Referencia: OpenAI Python SDK y clase DefaultAzureCredential.

Opciones de credenciales al usar Microsoft Entra ID

DefaultAzureCredential es una secuencia ordenada de mecanismos para autenticarse en Microsoft Entra ID. Cada mecanismo de autenticación es una clase derivada de la TokenCredential clase y que se conoce como credencial. En tiempo de ejecución, DefaultAzureCredential intenta autenticarse con la primera credencial. Si esa credencial no puede adquirir un token de acceso, se intenta la siguiente credencial de la secuencia, etc., hasta que se obtiene un token de acceso. De este modo, la aplicación puede usar credenciales diferentes en distintos entornos sin escribir código específico del entorno.

Cuando el código anterior se ejecuta en la estación de trabajo de desarrollo local, busca en las variables de entorno de una entidad de servicio de aplicación o en las herramientas de desarrollo instaladas localmente, como Visual Studio, para un conjunto de credenciales de desarrollador. Puede usar cualquiera de los enfoques para autenticar la aplicación a recursos de Azure durante el desarrollo local.

Cuando se implementa en Azure, este mismo código también puede autenticar la aplicación en otros recursos de Azure. DefaultAzureCredential puede recuperar la configuración del entorno y las configuraciones de identidad administrada para autenticarse en otros servicios automáticamente.

Procedimientos recomendados

  • Usar credenciales deterministas en entornos de producción: considere encarecidamente la posibilidad de pasar de DefaultAzureCredential a una de las siguientes soluciones deterministas en entornos de producción:

    • Una implementación específica de TokenCredential, como ManagedIdentityCredential. Consulte la lista Derivada para ver las opciones.
    • Una implementación de ChainedTokenCredential reducida optimizada para el entorno de Azure en el que se ejecuta tu aplicación. ChainedTokenCredential básicamente crea una lista de permitidos específica de opciones de credenciales aceptables, como ManagedIdentity para producción y VisualStudioCredential para desarrollo.

  • Configure identidades administradas asignadas por el sistema o asignadas por el usuario a los recursos Azure donde se ejecuta el código, si es posible. Configura el acceso de Microsoft Entra ID a esas identidades específicas.

Deshabilitación de la autenticación basada en claves en el recurso

Deshabilite la autenticación basada en claves cuando implemente Microsoft Entra ID y aborde completamente las preocupaciones de compatibilidad o retrocompatibilidad en todas las aplicaciones que consumen el servicio. Puede deshabilitar la autenticación basada en claves mediante CLI de Azure o al implementar con Bicep o ARM.

El acceso basado en claves sigue siendo posible para los usuarios que ya tienen claves disponibles para ellos. Para revocar las claves, en el portal de Azure, en el panel de navegación izquierdo, seleccione Resource Management>Keys and Endpoints>Regenerate Key1 y Regenerate Key2.

  • Instale el CLI de Azure

  • Identifique la siguiente información:

    • Identificador de suscripción de Azure

    • Nombre del recurso de Microsoft Foundry

    • El grupo de recursos donde implementó el recurso Foundry.

Configuración de Microsoft Entra ID para la inferencia

Para configurar Microsoft Entra ID para la inferencia, siga estos pasos:

  1. Inicie sesión en la suscripción de Azure.

    # Authenticate with Azure and sign in interactively
az login

  2. Si tiene más de una suscripción, seleccione la suscripción donde se encuentra el recurso.

    # Set the active subscription context
az account set --subscription "<subscription-id>"

  3. Establezca las siguientes variables de entorno con el nombre del recurso y el grupo de recursos que planea usar.

    # Store resource identifiers for reuse in subsequent commands
ACCOUNT_NAME="<ai-services-resource-name>"
RESOURCE_GROUP="<resource-group>"

  4. Obtenga el nombre completo del recurso.

    # Retrieve the full Azure Resource Manager ID for role assignment scoping
RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts" --query id --output tsv)

  5. Obtenga el identificador de objeto de la entidad de seguridad a la que desea asignar permisos. En los ejemplos siguientes se muestra cómo obtener el identificador de objeto asociado a:

    Su propia cuenta con sesión iniciada:

    # Get your user's Microsoft Entra ID object ID
OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)

    Un grupo de seguridad:

    # Get the object ID for a security group (recommended for production)
OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)

    Una entidad de servicio:

    # Get the object ID for a service principal (for app authentication)
OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)

  6. Asigne el rol usuario de Cognitive Services a la entidad de servicio (con ámbito al recurso). Al asignar un rol, se otorga al principal de servicio acceso a este recurso.

    # Grant inference access by assigning the Cognitive Services User role
az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID

  7. El usuario seleccionado ahora puede usar Microsoft Entra ID para la inferencia.

    Sugerencia

    Tenga en cuenta que las asignaciones de roles Azure pueden tardar hasta cinco minutos en propagarse. Agregar o quitar usuarios de un grupo de seguridad se propaga inmediatamente.

  8. Compruebe la asignación de roles:

    az role assignment list --scope $RESOURCE_ID --assignee $OBJECT_ID --query "[?roleDefinitionName=='Cognitive Services User'].{principalName:principalName, roleDefinitionName:roleDefinitionName}" --output table

    La salida debe mostrar el rol usuario de Cognitive Services asignado a la entidad de seguridad.

Usa Microsoft Entra ID en tu código

Después de configurar Microsoft Entra ID en el recurso, actualice el código para usarlo al consumir el punto de conexión de inferencia. En el ejemplo siguiente se muestra cómo usar un modelo de finalizaciones de chat:

Instale el SDK de OpenAI mediante un administrador de paquetes como pip:

pip install openai

Para la autenticación de Microsoft Entra ID, instale también:

pip install azure-identity

Use el paquete para consumir el modelo. En el ejemplo siguiente se muestra cómo crear un cliente para consumir finalizaciones de chat con Microsoft Entra ID y realizar una llamada de prueba al punto de conexión de finalizaciones de chat con la implementación del modelo.

Reemplace <resource> con el nombre de su recurso Foundry. Encuéntrelo en el portal de Azure o bien ejecutando az cognitiveservices account list. Reemplace DeepSeek-V3.1 con su nombre de implementación real.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), 
    "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://<resource>.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

completion = client.chat.completions.create(
    model="DeepSeek-V3.1",  # Required: your deployment name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Azure AI?"}
    ]
)

print(completion.choices[0].message.content)

Salida esperada

Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.

Referencia: OpenAI Python SDK y clase DefaultAzureCredential.

Opciones de credenciales al usar Microsoft Entra ID

DefaultAzureCredential es una secuencia ordenada de mecanismos para autenticarse en Microsoft Entra ID. Cada mecanismo de autenticación es una clase derivada de la TokenCredential clase y que se conoce como credencial. En tiempo de ejecución, DefaultAzureCredential intenta autenticarse con la primera credencial. Si esa credencial no puede adquirir un token de acceso, se intenta la siguiente credencial de la secuencia, etc., hasta que se obtiene un token de acceso. De este modo, la aplicación puede usar credenciales diferentes en distintos entornos sin escribir código específico del entorno.

Cuando el código anterior se ejecuta en la estación de trabajo de desarrollo local, busca en las variables de entorno de una entidad de servicio de aplicación o en las herramientas de desarrollo instaladas localmente, como Visual Studio, para un conjunto de credenciales de desarrollador. Puede usar cualquiera de los enfoques para autenticar la aplicación a recursos de Azure durante el desarrollo local.

Cuando se implementa en Azure, este mismo código también puede autenticar la aplicación en otros recursos de Azure. DefaultAzureCredential puede recuperar la configuración del entorno y las configuraciones de identidad administrada para autenticarse en otros servicios automáticamente.

Procedimientos recomendados

  • Usar credenciales deterministas en entornos de producción: considere encarecidamente la posibilidad de pasar de DefaultAzureCredential a una de las siguientes soluciones deterministas en entornos de producción:

    • Una implementación específica de TokenCredential, como ManagedIdentityCredential. Consulte la lista Derivada para ver las opciones.
    • Una implementación de ChainedTokenCredential reducida optimizada para el entorno de Azure en el que se ejecuta tu aplicación. ChainedTokenCredential básicamente crea una lista de permitidos específica de opciones de credenciales aceptables, como ManagedIdentity para producción y VisualStudioCredential para desarrollo.

  • Configure identidades administradas asignadas por el sistema o asignadas por el usuario a los recursos Azure donde se ejecuta el código, si es posible. Configura el acceso de Microsoft Entra ID a esas identidades específicas.

Deshabilitación de la autenticación basada en claves en el recurso

Deshabilite la autenticación basada en claves cuando implemente Microsoft Entra ID y solucione completamente los problemas de compatibilidad o alternativas en todas las aplicaciones que consumen el servicio. Use PowerShell con el CLI de Azure para deshabilitar la autenticación local para un recurso individual. Inicie sesión primero con el Connect-AzAccount comando . A continuación, use el Set-AzCognitiveServicesAccount cmdlet con el parámetro -DisableLocalAuth $true, como en el ejemplo siguiente:

Set-AzCognitiveServicesAccount -ResourceGroupName "my-resource-group" -Name "my-resource-name" -DisableLocalAuth $true

Para obtener más información sobre cómo usar el CLI de Azure para deshabilitar o volver a habilitar la autenticación local y comprobar el estado de autenticación, vea Deshabilitar la autenticación local en Foundry Tools.

  • Instale el CLI de Azure

  • Identifique la siguiente información:

    • Identificador de suscripción de Azure

Acerca de este tutorial

El ejemplo de este artículo se basa en ejemplos de código del repositorio Azure-Samples/azureai-model-inference-bicep. Para ejecutar los comandos localmente sin copiar o pegar contenido del archivo, clone el repositorio con estos comandos y vaya a la carpeta del lenguaje de codificación:

git clone https://github.com/Azure-Samples/azureai-model-inference-bicep

Los archivos de este ejemplo se encuentran en el directorio siguiente:

cd azureai-model-inference-bicep/infra

Descripción de los recursos

En este tutorial, creará los siguientes recursos:

  • Un recurso de Microsoft Foundry con acceso a claves deshabilitado. Por motivos de simplicidad, esta plantilla no implementa modelos.
  • Asignación de un rol para una entidad de seguridad determinada con el rol de Usuario de Cognitive Services.

Para crear estos recursos, use los siguientes recursos:

  1. Use la plantilla modules/ai-services-template.bicep para describir el recurso Foundry.

    modules/ai-services-template.bicep

    @description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id

    Sugerencia

    Esta plantilla acepta el allowKeys parámetro . Establézcalo en false para deshabilitar el acceso a claves en el recurso.

  2. Use la plantilla modules/role-assignment-template.bicep para describir una asignación de roles en Azure:

    modules/role-assignment-template.bicep

    @description('Specifies the role definition ID used in the role assignment.')
param roleDefinitionID string

@description('Specifies the principal ID assigned to the role.')
param principalId string

@description('Specifies the resource ID of the resource to assign the role to.')
param scopeResourceId string = resourceGroup().id

var roleAssignmentName= guid(principalId, roleDefinitionID, scopeResourceId)
resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: roleAssignmentName
  properties: {
    roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionID)
    principalId: principalId
  }
}

output name string = roleAssignment.name
output resourceId string = roleAssignment.id

Creación de los recursos

En la consola, siga estos pasos:

  1. Defina la implementación principal:

    deploy-entra-id.bicep

    @description('Location to create the resources in')
param location string = resourceGroup().location

@description('Name of the resource group to create the resources in')
param resourceGroupName string = resourceGroup().name

@description('Name of the AI Services account to create')
param accountName string = 'azurei-models-dev'

@description('ID of the developers to assign the user role to')
param securityPrincipalId string

module aiServicesAccount 'modules/ai-services-template.bicep' = {
  name: 'aiServicesAccount'
  scope: resourceGroup(resourceGroupName)
  params: {
    accountName: accountName
    location: location
    allowKeys: false
  }
}

module roleAssignmentDeveloperAccount 'modules/role-assignment-template.bicep' = {
  name: 'roleAssignmentDeveloperAccount'
  scope: resourceGroup(resourceGroupName)
  params: {
    roleDefinitionID: 'a97b65f3-24c7-4388-baec-2e87135dc908' // Azure Cognitive Services User
    principalId: securityPrincipalId
  }
}

output endpoint string = aiServicesAccount.outputs.endpointUri

  2. Inicie sesión en Azure:

    az login

  3. Asegúrese de que está en la suscripción correcta:

    az account set --subscription "<subscription-id>"

  4. Ejecute la implementación:

    RESOURCE_GROUP="<resource-group-name>"
SECURITY_PRINCIPAL_ID="<your-security-principal-id>"

az deployment group create \
  --resource-group $RESOURCE_GROUP \
  --parameters securityPrincipalId=$SECURITY_PRINCIPAL_ID \
  --template-file deploy-entra-id.bicep

  5. La plantilla genera el punto de conexión de Foundry Models que puede usar para consumir cualquiera de las implementaciones de modelo que ha creado.

  6. Compruebe la implementación y la asignación de roles:

    # Get the endpoint from deployment output
ENDPOINT=$(az deployment group show --resource-group $RESOURCE_GROUP --name deploy-entra-id --query properties.outputs.endpoint.value --output tsv)

# Verify role assignment
RESOURCE_ID=$(az deployment group show --resource-group $RESOURCE_GROUP --name deploy-entra-id --query properties.outputs.resourceId.value --output tsv)
az role assignment list --scope $RESOURCE_ID --assignee $SECURITY_PRINCIPAL_ID --query "[?roleDefinitionName=='Cognitive Services User'].roleDefinitionName" --output tsv

# Test authentication by getting an access token
az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

    Si se ejecuta correctamente, verá Usuario de Cognitive Services en la comprobación de asignación de roles y un token de acceso de la prueba de autenticación. Ahora puede usar este punto de conexión y la autenticación de Microsoft Entra ID en su código.

Usa Microsoft Entra ID en tu código

Después de configurar Microsoft Entra ID en el recurso, actualice el código para usarlo al consumir el punto de conexión de inferencia. En el ejemplo siguiente se muestra cómo usar un modelo de finalizaciones de chat.

Instale el SDK de OpenAI mediante un administrador de paquetes como pip:

pip install openai

Para la autenticación de Microsoft Entra ID, instale también:

pip install azure-identity

Use el paquete para consumir el modelo. En el ejemplo siguiente se muestra cómo crear un cliente para consumir finalizaciones de chat con Microsoft Entra ID y realizar una llamada de prueba al punto de conexión de finalizaciones de chat con la implementación del modelo.

Reemplace <resource> con el nombre de su recurso Foundry. Encuéntrelo en el portal de Azure o bien ejecutando az cognitiveservices account list. Reemplace DeepSeek-V3.1 con su nombre de implementación real.

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), 
    "https://ai.azure.com/.default"
)

client = OpenAI(
    base_url="https://<resource>.openai.azure.com/openai/v1/",
    api_key=token_provider,
)

completion = client.chat.completions.create(
    model="DeepSeek-V3.1",  # Required: your deployment name
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is Azure AI?"}
    ]
)

print(completion.choices[0].message.content)

Salida esperada

Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.

Referencia: OpenAI Python SDK y clase DefaultAzureCredential.

Opciones de credenciales al usar Microsoft Entra ID

DefaultAzureCredential es una secuencia ordenada de mecanismos para autenticarse en Microsoft Entra ID. Cada mecanismo de autenticación es una clase derivada de la TokenCredential clase y que se conoce como credencial. En tiempo de ejecución, DefaultAzureCredential intenta autenticarse con la primera credencial. Si esa credencial no puede adquirir un token de acceso, se intenta la siguiente credencial de la secuencia, etc., hasta que se obtiene un token de acceso. De este modo, la aplicación puede usar credenciales diferentes en distintos entornos sin escribir código específico del entorno.

Cuando el código anterior se ejecuta en la estación de trabajo de desarrollo local, busca en las variables de entorno de una entidad de servicio de aplicación o en las herramientas de desarrollo instaladas localmente, como Visual Studio, para un conjunto de credenciales de desarrollador. Puede usar cualquiera de los enfoques para autenticar la aplicación a recursos de Azure durante el desarrollo local.

Cuando se implementa en Azure, este mismo código también puede autenticar la aplicación en otros recursos de Azure. DefaultAzureCredential puede recuperar la configuración del entorno y las configuraciones de identidad administrada para autenticarse en otros servicios automáticamente.

Procedimientos recomendados

  • Usar credenciales deterministas en entornos de producción: considere encarecidamente la posibilidad de pasar de DefaultAzureCredential a una de las siguientes soluciones deterministas en entornos de producción:

    • Una implementación específica de TokenCredential, como ManagedIdentityCredential. Consulte la lista Derivada para ver las opciones.
    • Una implementación de ChainedTokenCredential reducida optimizada para el entorno de Azure en el que se ejecuta tu aplicación. ChainedTokenCredential básicamente crea una lista de permitidos específica de opciones de credenciales aceptables, como ManagedIdentity para producción y VisualStudioCredential para desarrollo.

  • Configure identidades administradas asignadas por el sistema o asignadas por el usuario a los recursos Azure donde se ejecuta el código, si es posible. Configura el acceso de Microsoft Entra ID a esas identidades específicas.

Deshabilitación de la autenticación basada en claves en el recurso

Deshabilite la autenticación basada en claves cuando implemente Microsoft Entra ID y aborde completamente las preocupaciones de compatibilidad o retrocompatibilidad en todas las aplicaciones que consumen el servicio. Cambie la propiedad disableLocalAuth para deshabilitar la autenticación basada en claves.

Para obtener más información sobre cómo desactivar la autenticación local cuando se usa una plantilla de ARM o Bicep, vea Cómo desactivar la autenticación local.

modules/ai-services-template.bicep

@description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id

Descripción de los roles en el contexto del recurso en Azure

Microsoft Entra ID usa el control de acceso basado en rol (RBAC) para la autorización, que controla las acciones que los usuarios pueden realizar en los recursos de Azure. Los roles son fundamentales para administrar el acceso a los recursos en la nube. Un rol es una colección de permisos que definen qué acciones se pueden realizar en recursos Azure específicos. Al asignar roles a usuarios, grupos, entidades de servicio o identidades administradas (conocidas colectivamente como entidades de seguridad), se controla su acceso dentro del entorno de Azure a recursos específicos.

Al asignar un rol, debe especificar la entidad de seguridad, la definición del rol y el ámbito. Esta combinación se conoce como asignación de roles. Foundry Models es una funcionalidad de los recursos de Foundry Tools, por lo que los roles asignados a ese recurso concreto controlan el acceso para la inferencia.

Hay dos tipos de acceso a los recursos:

  • Acceso de administración: acciones relacionadas con la administración del recurso. Estas acciones suelen cambiar el estado del recurso y su configuración. En Azure, estas operaciones son operaciones de plano de control que puede ejecutar mediante el portal de Azure, CLI de Azure o infraestructura como código. Algunos ejemplos son la creación de nuevas implementaciones de modelos, el cambio de las configuraciones de filtrado de contenido, el cambio de la versión del modelo servido o el cambio de la SKU de una implementación.

  • Acceso para desarrolladores: acciones relacionadas con el consumo de los recursos, como invocar la API de finalizaciones de chat. Sin embargo, el usuario no puede cambiar el estado del recurso y su configuración.

En Azure, Microsoft Entra ID siempre realiza operaciones de administración. Los roles como colaborador de Cognitive Services le permiten realizar esas operaciones. Las operaciones de desarrollador se pueden realizar mediante claves de acceso o Microsoft Entra ID. Los roles como el usuario de Cognitive Services le permiten realizar esas operaciones.

Importante

Tener acceso de administración a un recurso no le concede acceso para desarrolladores. El acceso explícito mediante la concesión de roles sigue siendo necesario. Esto es análogo a cómo funcionan los servidores de bases de datos. Tener acceso de administrador al servidor de bases de datos no significa que pueda leer los datos dentro de una base de datos.

Solución de problemas

Antes de solucionar problemas, compruebe que tiene asignados los permisos adecuados:

  1. Vaya al portal Azure y busque el recurso Microsoft Foundry que usa.

  2. En el panel izquierdo, seleccione Control de acceso (IAM) y, a continuación, seleccione Comprobar acceso.

  3. Escriba el nombre del usuario o la identidad que usa para conectarse al servicio.

  4. Compruebe que el rol Usuario de Cognitive Services aparece (o un rol que contiene los permisos necesarios, como se explica en la sección Requisitos previos).

    Importante

    Los roles como Owner o Contributor no proporcionan acceso a través de Microsoft Entra ID.

  5. Si el rol no aparece en la lista, siga los pasos descritos en esta guía antes de continuar.

La tabla siguiente contiene varios escenarios que pueden ayudarle a solucionar problemas Microsoft Entra ID:

Error/Escenario Causa principal Solución
Está usando un SDK. Problemas conocidos Antes de solucionar problemas, instale la versión más reciente del software que usa para conectarse al servicio. Es posible que los errores de autenticación ya se corrigieron en una versión más reciente del software que está usando.
401 Principal does not have access to API/Operation La solicitud indica la autenticación correctamente, pero el usuario principal no tiene los permisos necesarios para usar el punto de conexión de inferencia. Asegúrese de que tiene:
1. Asignó el rol de Usuario de Cognitive Services a su entidad al recurso de Foundry. Tenga en cuenta que el usuario de OpenAI de Cognitive Services solo concede acceso a los modelos de OpenAI. El propietario o colaborador tampoco proporcionan acceso.
1. Espere al menos 5 minutos antes de realizar la primera llamada.
401 HTTP/1.1 401 PermissionDenied La solicitud indica la autenticación correctamente, pero el usuario principal no tiene los permisos necesarios para usar el punto de conexión de inferencia. Asignó el rol de Usuario de Cognitive Services a su entidad en el recurso de Foundry. Los roles como Administrador o Colaborador no conceden acceso de inferencia. Espere al menos 5 minutos antes de realizar la primera llamada.
Estás usando llamadas a la API REST y consigues 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. La solicitud no se puede autenticar con Microsoft Entra ID. Asegúrese de que el Authentication encabezado contiene un token válido con un ámbito https://ai.azure.com/.default.

Paso siguiente

  • Last updated on