Autenticación de solicitudes en los servicios de Azure AI

Cada solicitud a una instancia de servicios de Azure AI debe incluir un encabezado de autenticación. Este encabezado pasa una clave de suscripción o token de autenticación, que se utiliza para validar su suscripción a un servicio o grupo de servicios. En este artículo, aprenderá sobre tres maneras de autenticar una solicitud y los requisitos para cada una.

• Autenticarse con una clave de recurso monoservicio o multiservicio
• Autenticación con un token
• Autenticación con Microsoft Entra ID

Requisitos previos

Antes de hacer una solicitud, necesita una cuenta de Azure y una suscripción a servicios de Azure AI. Si ya tiene una cuenta, siga adelante y vaya a la sección siguiente. Si no tiene una cuenta, tenemos una guía para que la configure en unos minutos: Cree un recurso de Servicios de Azure AI.

Vaya al recurso en Azure Portal. La sección Claves y puntos de conexión se puede encontrar en la sección Administración de recursos. Copie el punto de conexión y la clave de acceso, ya que los necesitará para autenticar las llamadas API. Puede usar KEY1 o KEY2. Tener siempre dos claves permite rotar y regenerar las claves de forma segura sin provocar una interrupción del servicio.

Encabezados de autenticación

Revisemos rápidamente los encabezados de autenticación disponibles para su uso con servicios de Azure AI.

Encabezado	Descripción
Ocp-Apim-Subscription-Key	Utilice esta cabecera para autenticarse con una clave de recurso para un servicio específico o una clave de recurso multiservicio.
Ocp-Apim-Subscription-Region	Esta cabecera sólo es necesaria cuando se utiliza una clave de recurso multiservicio con el Servicio Traductor de Azure AI. Utiliza esta cabecera para especificar la región del recurso.
Autorización	Utilice este encabezado si usa un token de acceso. En las secciones siguientes se describen los pasos necesarios para realizar un intercambio de tokens. El valor proporcionado sigue este formato: Bearer <TOKEN>.

Autentificarse con una clave de recurso de servicio único

La primera opción es autenticar una solicitud con una clave de recurso para un servicio concreto, como Traductor de Azure AI. Las claves están disponibles en Azure Portal para cada recurso que se ha creado. Vaya al recurso en Azure Portal. La sección Claves y puntos de conexión se puede encontrar en la sección Administración de recursos. Copie el punto de conexión y la clave de acceso, ya que los necesitará para autenticar las llamadas API. Puede usar KEY1 o KEY2. Tener siempre dos claves permite rotar y regenerar las claves de forma segura sin provocar una interrupción del servicio.

Para utilizar una clave de suscripción para autenticar una solicitud, esta se debe pasar como el encabezado Ocp-Apim-Subscription-Key. Esta es una llamada de ejemplo al servicio Traductor de Azure AI:

Esta es una llamada de ejemplo al servicio Traductor:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Autenticación con un recurso de multiservicios servicios

Puede usar una clave de recurso de varios servicios para autenticar las solicitudes. La principal diferencia es que la clave de recursos multiservicio no está vinculada a un servicio concreto, sino que puede utilizarse una única clave para autenticar solicitudes de varios servicios de Azure AI. Consulte los precios de servicios de Azure AI para más información sobre la disponibilidad regional, características admitidas y precios.

La clave de suscripción se proporciona en cada solicitud como encabezado Ocp-Apim-Subscription-Key.

Regiones admitidas

Cuando utilice la clave del recurso Servicios de Azure AI multiservicio para hacer una solicitud a api.cognitive.microsoft.com, debe incluir la región en la URL. Por ejemplo: westus.api.cognitive.microsoft.com.

Cuando utilices una clave de recurso multiservicio con Azure AI Translator, debes especificar la región del recurso con el encabezado Ocp-Apim-Subscription-Region.

Se admite la autenticación de recursos multiservicios en estas regiones:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2
• francecentral
• koreacentral
• northcentralus
• southafricanorth
• uaenorth
• switzerlandnorth

Solicitudes de ejemplo

Esta es una llamada de ejemplo al servicio Traductor de Azure AI:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
-H 'Ocp-Apim-Subscription-Region: YOUR_SUBSCRIPTION_REGION' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Autenticación con token de acceso

Algunos servicios de Azure AI aceptan un token de autenticación y, a veces, es obligatorio. Actualmente, admiten tokens de acceso estos servicios:

• Text Translation API
• Servicios de voz: API de conversión de voz en texto
• Servicios de voz: API de texto a voz

Advertencia

Los servicios que admiten los tokens de acceso pueden cambiar con el tiempo. Consulte la referencia de la API de los servicios antes de utilizar este método de autenticación.

Tanto las claves de un solo servicio como las de recursos multiservicio pueden intercambiarse por tokens de autenticación. Los token de autenticación tienen una validez de 10 minutos. Se almacenan en formato JSON Web Token (JWT) y se pueden consultar mediante programación con las bibliotecas JWT.

Los tokens de acceso se incluyen en una solicitud como encabezado Authorization. El valor del token proporcionado debe ir precedido de Bearer, por ejemplo: Bearer YOUR_AUTH_TOKEN.

Solicitudes de ejemplo

Utiliza esta URL para intercambiar una clave de recurso por un token de acceso: https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken.

curl -v -X POST \
"https://YOUR-REGION.api.cognitive.microsoft.com/sts/v1.0/issueToken" \
-H "Content-type: application/x-www-form-urlencoded" \
-H "Content-length: 0" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Estas regiones de varios servicios admiten el intercambio de tokens:

• australiaeast
• brazilsouth
• canadacentral
• centralindia
• eastasia
• eastus
• japaneast
• northeurope
• southcentralus
• southeastasia
• uksouth
• westcentralus
• westeurope
• westus
• westus2

Después de obtener un token de acceso, deberá pasarlo en cada solicitud como encabezado Authorization. Esta es una llamada de ejemplo al servicio Traductor de Azure AI:

curl -X POST 'https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=de' \
-H 'Authorization: Bearer YOUR_AUTH_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '[{ "text": "How much for the cup of coffee?" }]' | json_pp

Autenticación con Microsoft Entra ID

Importante

La autenticación con Microsoft Entra siempre debe usarse junto con el nombre de subdominio personalizado del recurso de Azure. Los puntos de conexión regionales no admiten la autenticación con Microsoft Entra.

En las secciones anteriores, le mostramos cómo realizar la autenticación en servicios de Azure AI mediante una clave de suscripción de un solo servicio o de varios servicios. Aunque estas claves proporcionan una ruta rápida y fácil para iniciar el desarrollo, se quedan cortas en escenarios más complejos que requieren el control de acceso basados en roles de Azure (Azure RBAC). Echemos un vistazo a lo que se necesita para autenticarse con Microsoft Entra ID.

En las secciones siguientes, usará el entorno de Azure Cloud Shell o la CLI de Azure para crear un subdominio, asignar roles y obtener un token de portador para llamar a servicios de Azure AI. Si se bloquea, se proporcionan vínculos en cada sección con todas las opciones disponibles para cada comando de Azure Cloud Shell o la CLI de Azure.

Importante

Si su organización realiza la autenticación a través de Microsoft Entra ID, debe deshabilitar la autenticación local (autenticación con claves) para que los usuarios de la organización siempre deban usar Microsoft Entra ID.

Creación de un recurso con un subdominio personalizado

El primer paso es crear un subdominio personalizado. Si desea usar un recurso de servicios de Azure AI existente que no tenga un nombre de subdominio personalizado, siga las instrucciones de Subdominios personalizados para servicios de Azure AI para habilitar el subdominio personalizado para el recurso.

1. Para empezar, abra Azure Cloud Shell, Después seleccione una suscripción:

   Set-AzContext -SubscriptionName <SubscriptionName>
   

2. A continuación, cree un recurso de servicios de Azure AI con un subdominio personalizado. El nombre del subdominio debe ser único globalmente y no puede incluir caracteres especiales, como: ".", "!", ",".

   $account = New-AzCognitiveServicesAccount -ResourceGroupName <RESOURCE_GROUP_NAME> -name <ACCOUNT_NAME> -Type <ACCOUNT_TYPE> -SkuName <SUBSCRIPTION_TYPE> -Location <REGION> -CustomSubdomainName <UNIQUE_SUBDOMAIN>
   

3. Si se realiza correctamente, el punto de conexión debe mostrar el nombre de subdominio único del recurso.

Asignación de un rol a una entidad de servicio

Ahora que tiene un subdominio personalizado asociado al recurso, deberá asignar un rol a una entidad de servicio.

Nota

Tenga en cuenta que las asignaciones de roles de Azure pueden tardar hasta cinco minutos en propagarse.

1. En primer lugar, vamos a registrar una aplicación de Microsoft Entra.

   $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force
   
   $app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword
   

   Va a necesitar el valor de ApplicationID en el paso siguiente.

2. Después, tiene que crear una entidad de servicio para la aplicación de Microsoft Entra.

   New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
   

   Nota:

   Si registra una aplicación en Azure Portal, este paso se completa automáticamente.

3. El último paso es asignar el rol "Usuario de Cognitive Services" a la entidad de servicio (en el ámbito del recurso). Mediante la asignación de un rol, concede acceso a la entidad de servicio a este recurso. Puede conceder a la misma entidad de servicio acceso a varios recursos de la suscripción.

   Nota

   Se utiliza el valor de ObjectId de la entidad de servicio, no el valor de ObjectId de la aplicación. ACCOUNT_ID será el identificador de recurso de Azure de la cuenta de servicios de Azure AI que ha creado. Puede encontrar el identificador de recurso de Azure en las "propiedades" del recurso en Azure Portal.

   New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
   

Solicitud de ejemplo

En este ejemplo, se usa una contraseña para autenticar la entidad de servicio. El token proporcionado se usa para llamar a la API Computer Vision.

1. Obtenga el TenantId:

   $context=Get-AzContext
   $context.Tenant.Id
   

2. Obtenga un token:

   $tenantId = $context.Tenant.Id
   $clientId = $app.ApplicationId
   $clientSecret = "<YOUR_PASSWORD>"
   $resourceUrl = "https://cognitiveservices.azure.com/"
   
   $tokenEndpoint = "https://login.microsoftonline.com/$tenantId/oauth2/token"
   $body = @{
       grant_type    = "client_credentials"
       client_id     = $clientId
       client_secret = $clientSecret
       resource      = $resourceUrl
   }
   
   $responseToken = Invoke-RestMethod -Uri $tokenEndpoint -Method Post -Body $body
   $accessToken = $responseToken.access_token
   

   Nota:

   Cada vez que use contraseñas en un script, la opción más segura es el uso del módulo de administración de secretos de PowerShell y la integración con una solución como Azure Key Vault.

3. Llame a la API Computer Vision:

   $url = $account.Endpoint+"vision/v1.0/models"
   $result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"="Bearer $accessToken"} -Verbose
   $result | ConvertTo-Json
   

Como alternativa, la entidad de servicio se puede autenticar con un certificado. Además de la entidad de servicio, la entidad de seguridad de usuario también se admite si tiene permisos delegados a través de otra aplicación de Microsoft Entra. En este caso, en lugar de contraseñas o certificados, se les pedirá a los usuarios la autenticación en dos fases al adquirir el token.

Autorización para obtener acceso a identidades administradas

Servicios de Azure AI admite la autenticación de Microsoft Entra con identidades administradas para los recursos de Azure. Las identidades administradas para recursos de Azure pueden autorizar el acceso a los recursos de servicios de Azure AI con credenciales de Microsoft Entra desde aplicaciones que se ejecutan en máquinas virtuales (VM) de Azure, aplicaciones de función, conjuntos de escalado de máquinas virtuales y otros servicios. Si usa identidades administradas para recursos de Azure junto con autenticación de Microsoft Entra, puede evitar el almacenamiento de credenciales con las aplicaciones que se ejecutan en la nube.

Habilitación de identidades administradas en una máquina virtual

Para poder usar identidades administradas para recursos de Azure a fin de autorizar el acceso los recursos de servicios de Azure AI desde la VM, primero debe habilitar las identidades administradas para los recursos de Azure en la VM. Para aprender a habilitar las identidades administradas para los recursos de Azure, consulte:

• Azure Portal
• Azure PowerShell
• CLI de Azure
• Plantilla de Azure Resource Manager
• Bibliotecas cliente de Azure Resource Manager

Para más información sobre las identidades administradas, consulte Identidades administradas para recursos de Azure.

Uso de Azure Key Vault para acceder de forma segura a las credenciales

Azure Key Vault se puede usar para desarrollar de forma segura aplicaciones de servicios de Azure AI. Key Vault permite almacenar las credenciales de autenticación en la nube y reduce las posibilidades de que se filtren secretos accidentalmente, ya que no se almacenará información de seguridad en la aplicación.

La autenticación se realiza a través de Microsoft Entra ID. La autorización puede realizarse mediante el control de acceso basado en rol de Azure (RBAC de Azure) o la directiva de acceso de Key Vault. Azure RBAC se puede utilizar tanto para la administración de los almacenes como para acceder a los datos almacenados en un almacén, mientras que la directiva de acceso del almacén de claves solo se puede usar cuando se intenta acceder a los datos almacenados en un almacén.

Consulte también

• ¿Qué son los servicios de Azure AI?
• Precios de los servicios de Azure AI
• Subdominios personalizados