Autenticación de solicitudes en Azure Cognitive Services

  • Artículo
  • Tiempo de lectura: 9 minutos

Cada solicitud a una instancia de Azure Cognitive Services 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.

Requisitos previos

Antes de hacer una solicitud, necesita una cuenta de Azure y una suscripción a Azure Cognitive Services. 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 una cuenta de Cognitive Services para Azure.

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 Azure Cognitive Services.

Encabezado Descripción
Ocp-Apim-Subscription-Key Utilice este encabezado para autenticarse con una clave de suscripción para un servicio específico o una clave de suscripción a varios servicios.
Ocp-Apim-Subscription-Region Este encabezado solo es necesario cuando se utiliza una clave de suscripción multiservicio con el servicio de Traductor. Utilice este encabezado para especificar la región de la suscripción.
Authorization 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>.

Autenticación con una clave de suscripción a un servicio único

La primera opción es autenticar una solicitud con una clave de suscripción para un servicio específico, 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 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 a Bing Web Search API:

curl -X GET 'https://api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

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

Autenticación con una clave de suscripción a varios servicios

Advertencia

En este momento, la clave de varios servicios no admite: QnA Maker, Immersive Reader, Personalizer ni Anomaly Detector.

Esta opción también utiliza una clave de suscripción para autenticar las solicitudes. La principal diferencia es que una clave de suscripción no está asociada a un servicio específico, sino que se puede utilizar una única clave para autenticar solicitudes de varios servicios de Cognitive Services. Consulte los precios de Cognitive Services 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.

Clave de suscripción a varios servicios para Cognitive Services

Regiones admitidas

Cuando utilice la clave de suscripción a varios servicios para realizar una solicitud a api.cognitive.microsoft.com, debe incluir la región en la dirección URL. Por ejemplo: westus.api.cognitive.microsoft.com.

Cuando utilice la clave de suscripción a varios servicios con Traductor, debe especificar la región de suscripción 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 a Bing Web Search API:

curl -X GET 'https://YOUR-REGION.api.cognitive.microsoft.com/bing/v7.0/search?q=Welsch%20Pembroke%20Corgis' \
-H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' | json_pp

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 Cognitive Services aceptan un token de autenticación y, a veces, es obligatorio. Actualmente, admiten tokens de acceso estos servicios:

  • Text Translation API
  • Servicios Voz: Speech-to-text REST API
  • Servicios Voz: Text-to-speech REST API

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 suscripción de servicio único como las de varios servicios se pueden intercambiar 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

Use esta dirección URL para intercambiar una clave de suscripción 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 Azure Active Directory

Importante

La autenticación con AAD 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 AAD.

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

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 Cognitive Services de Azure. 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.

Creación de un recurso con un subdominio personalizado

El primer paso es crear un subdominio personalizado. Si desea usar un recurso de Cognitive Services existente que no tenga un nombre de subdominio personalizado, siga las instrucciones de Subdominios personalizados para Cognitive Services 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 Cognitive Services 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 AAD.

    $SecureStringPassword = ConvertTo-SecureString -String <YOUR_PASSWORD> -AsPlainText -Force

$app = New-AzADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -Password $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 AAD.

    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 Cognitive Services 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:

    Nota

    Si está usando Azure Cloud Shell, la clase SecureClientSecret no está disponible.

    $authContext = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext" -ArgumentList "https://login.windows.net/<TENANT_ID>"
$secureSecretObject = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.SecureClientSecret" -ArgumentList $SecureStringPassword   
$clientCredential = New-Object "Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential" -ArgumentList $app.ApplicationId, $secureSecretObject
$token=$authContext.AcquireTokenAsync("https://cognitiveservices.azure.com/", $clientCredential).Result
$token
  1. Llame a la API Computer Vision:
    $url = $account.Endpoint+"vision/v1.0/models"
$result = Invoke-RestMethod -Uri $url  -Method Get -Headers @{"Authorization"=$token.CreateAuthorizationHeader()} -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 AAD. 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

Cognitive Services admite la autenticación de Azure Active Directory (Azure AD) con identidades administradas para los recursos de Azure. Las identidades administradas para recursos de Azure pueden autorizar el acceso a los recursos de Cognitive Services con credenciales de Azure AD 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 Azure AD, 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 Cognitive Services 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.

Consulte también