Autenticación de solicitudes en los servicios de Azure AI

Artículo
10/25/2023

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: Creación de un recurso de multiservicios.

Puede obtener la clave de suscripción en Azure Portal después de crear la cuenta.

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. 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. Las claves están disponibles en Azure Portal para cada recurso que se ha creado. Para utilizar una clave de suscripción para autenticar una solicitud, esta se debe pasar como el encabezado Ocp-Apim-Subscription-Key.

En estas solicitudes de ejemplo, se muestra cómo utilizar el encabezado Ocp-Apim-Subscription-Key. Tenga en cuenta que, cuando utilice este ejemplo, deberá incluir una clave de suscripción válida.

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

En el siguiente vídeo se explica cómo se usa una clave de servicios de Azure AI.

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 utilices la clave de recurso multiservicio para hacer una solicitud a api.cognitive.microsoft.com, debes 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 varios servicios 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:

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

Nota

QnA Maker también utiliza el encabezado de autorización, pero requiere una clave de punto de conexión. Para más información, consulte QnA Maker: Get answer from knowledge base (QnA Maker: Obtención de respuesta de Knowledge Base).

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:

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.

Para empezar, abra Azure Cloud Shell, Después seleccione una suscripción:
```
Set-AzContext -SubscriptionName <SubscriptionName>
```

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>

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.

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.

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.
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.

Obtenga el TenantId:

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

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 KeyVault.

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:

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.

Autenticación de solicitudes en los servicios de Azure AI

Requisitos previos

Encabezados de autenticación

Autentificarse con una clave de recurso de servicio único

Autenticación con un recurso de multiservicios servicios

Regiones admitidas

Solicitudes de ejemplo

Autenticación con token de acceso

Solicitudes de ejemplo

Autenticación con Microsoft Entra ID

Creación de un recurso con un subdominio personalizado

Asignación de un rol a una entidad de servicio

Solicitud de ejemplo

Autorización para obtener acceso a identidades administradas

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

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

Consulte también

Recursos adicionales