Compartir a través de

Autenticación de solicitudes en Foundry Tools

Cada solicitud a Foundry Tools 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 realizar una solicitud, necesita una suscripción de Azure y un recurso Foundry. Si necesita un recurso Foundry, consulte la guía crear un recurso Foundry.

Encabezados de autenticación

Vamos a revisar rápidamente los encabezados de autenticación disponibles para su uso con las herramientas de Foundry.

Encabezado Descripción
Ocp-Apim-Subscription-Key Use este encabezado para autenticarse con una clave de recurso para un servicio específico o una clave de recurso foundry.
Ocp-Apim-Subscription-Region Este encabezado solo es necesario cuando se usa una clave de recurso Foundry con Azure Translator. Utilice esta cabecera para especificar la región del recurso.
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>.

Autenticarse con una clave de recurso de servicio único

La primera opción es autenticar una solicitud con una clave de recurso para un servicio específico, como Azure Translator. 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. Se trata de una llamada de ejemplo al servicio Azure Translator:

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

Autenticar con una clave de recurso Foundry

Puede usar una clave de Recurso Foundry para autenticar solicitudes para varias Herramientas de Foundry. Las credenciales de autenticación no están vinculadas a un servicio específico. Consulte Precios de Foundry Tools para obtener información sobre la disponibilidad regional, las características admitidas y los precios.

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

Regiones admitidas

Al utilizar la clave del recurso Foundry para realizar una solicitud a api.cognitive.microsoft.com, debe incluir la región como parte de la dirección URL. Por ejemplo: westus.api.cognitive.microsoft.com.

Al usar una clave de recurso Foundry con Azure Translator, debe especificar la región del recurso en el encabezado Ocp-Apim-Subscription-Region.

La autenticación de recursos de Foundry se admite 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

Se trata de una llamada de ejemplo al servicio Azure Translator:

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

Algunas herramientas de Foundry aceptan y, en algunos casos, requieren un token de acceso. Actualmente, admiten tokens de acceso estos servicios:

  • Text Translation API
  • Discursos: API de conversión de voz a texto
  • Voz: API de texto a voz

Advertencia

Los servicios que admiten tokens de acceso pueden cambiar con el tiempo, por lo que debe comprobar la referencia de API de un servicio antes de usar este método de autenticación.

Las claves de recursos de los servicios de fundición e IA 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

Utilice 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 admiten el intercambio de tokens para los recursos de Foundry:

  • 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. Se trata de una llamada de ejemplo al servicio Azure Translator:

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

Autentíquese 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 autenticarse mediante claves de API. Aunque estas claves proporcionan una ruta de acceso rápida y sencilla para iniciar el desarrollo, quedan cortas en escenarios que requieren el control de acceso basado en roles de Azure (Azure RBAC). Echemos un vistazo a lo que se necesita para autenticarse de forma más segura mediante el identificador entra de Microsoft.

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 Foundry Tools. 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 foundry existente que no tenga un nombre de subdominio personalizado, siga las instrucciones de Subdominios personalizados de Foundry Tools 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 Foundry 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. El ACCOUNT_ID será el identificador de recurso de Azure del recurso foundry que creó. Puede encontrar el identificador de recurso de Azure en "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. A continuación, el token proporcionado se usa para llamar a Azure Vision API.

  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 Azure Vision API:

    $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

Foundry Tools admite la autenticación de Microsoft Entra con identidades administradas para recursos de Azure. Las identidades administradas para recursos de Azure pueden autorizar el acceso a recursos de Foundry mediante credenciales de Microsoft Entra desde aplicaciones que se ejecutan en máquinas virtuales (VM) de Azure, aplicaciones de funciones, conjuntos de escalado de máquinas virtuales y otros servicios. Mediante el uso de identidades administradas para los recursos de Azure junto con la autenticación de Microsoft Entra, puede evitar el almacenamiento de credenciales con sus aplicaciones que se ejecutan en la nube.

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

Para poder usar identidades administradas para recursos de Azure para autorizar el acceso a los recursos de Foundry desde la máquina virtual, debe habilitar las identidades administradas para los recursos de Azure en la máquina virtual. Para obtener información sobre cómo habilitar identidades administradas para 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

Puede usar Azure Key Vault para desarrollar aplicaciones de Microsoft Foundry de forma segura. 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.

Contenido relacionado

  • Last updated on