Autenticar solicitações para serviços de IA do Azure

  • Artigo

Cada solicitação para um serviço de IA do Azure deve incluir um cabeçalho de autenticação. Esse cabeçalho passa uma chave de recurso ou token de autenticação, que é usado para validar sua assinatura de um serviço ou grupo de serviços. Neste artigo, você aprenderá sobre três maneiras de autenticar uma solicitação e os requisitos para cada uma.

Pré-requisitos

Antes de fazer uma solicitação, você precisa de uma conta do Azure e uma assinatura de serviços de IA do Azure. Se você já tiver uma conta, vá em frente e pule para a próxima seção. Se você não tiver uma conta, temos um guia para configurá-lo em minutos: Criar um recurso de serviços de IA do Azure.

Vá para o seu recurso no portal do Azure. A seção Chaves & Ponto Final pode ser encontrada na seção Gerenciamento de Recursos. Copie seu endpoint e sua chave de acesso, pois você precisará de ambos para autenticar suas chamadas de API. Pode utilizar KEY1 ou KEY2. Ter sempre duas chaves permite-lhe rodar e regenerar chaves de forma segura sem causar uma interrupção do serviço.

Cabeçalhos de autenticação

Vamos analisar rapidamente os cabeçalhos de autenticação disponíveis para uso com os serviços de IA do Azure.

Cabeçalho Description
Ocp-Apim-Subscription-Key Use este cabeçalho para autenticar com uma chave de recurso para um serviço específico ou uma chave de recurso multisserviço.
OCP-Apim-Assinatura-Região Esse cabeçalho só é necessário ao usar uma chave de recurso multisserviço com o serviço Azure AI Translator. Use este cabeçalho para especificar a região de recurso.
Autorização Use este cabeçalho se estiver usando um token de acesso. As etapas para executar uma troca de token são detalhadas nas seções a seguir. O valor fornecido segue este formato: Bearer <TOKEN>.

Autenticar com uma chave de recurso de serviço único

A primeira opção é autenticar uma solicitação com uma chave de recurso para um serviço específico, como o Azure AI Translator. As chaves estão disponíveis no portal do Azure para cada recurso que você criou. Vá para o seu recurso no portal do Azure. A seção Chaves & Ponto Final pode ser encontrada na seção Gerenciamento de Recursos. Copie seu endpoint e sua chave de acesso, pois você precisará de ambos para autenticar suas chamadas de API. Pode utilizar KEY1 ou KEY2. Ter sempre duas chaves permite-lhe rodar e regenerar chaves de forma segura sem causar uma interrupção do serviço.

Para usar uma chave de recurso para autenticar uma solicitação, ela deve ser passada como o Ocp-Apim-Subscription-Key cabeçalho. Esta é uma chamada de exemplo para o serviço Azure AI Translator:

Esta é uma chamada de exemplo para o serviço Tradutor:

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 com uma chave de recurso multisserviço

Você pode usar uma chave de recurso multisserviço para autenticar solicitações. A principal diferença é que a chave de recurso multisserviço não está vinculada a um serviço específico, em vez disso, uma única chave pode ser usada para autenticar solicitações para vários serviços de IA do Azure. Consulte Preços dos serviços de IA do Azure para obter informações sobre disponibilidade regional, recursos suportados e preços.

A chave de recurso é fornecida em cada solicitação como o Ocp-Apim-Subscription-Key cabeçalho.

Regiões suportadas

Ao usar a chave de recurso multisserviço dos serviços de IA do Azure para fazer uma solicitação ao api.cognitive.microsoft.com, você deve incluir a região na URL. Por exemplo: westus.api.cognitive.microsoft.com.

Ao usar uma chave de recurso multisserviço com o Azure AI Translator, você deve especificar a região de recurso com o Ocp-Apim-Subscription-Region cabeçalho.

A autenticação de recursos multisserviço é suportada nestas regiões:

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

Pedidos de amostra

Esta é uma chamada de exemplo para o serviço Azure AI 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

Autenticar com um token de acesso

Alguns serviços de IA do Azure aceitam, e em alguns casos exigem, um token de acesso. Atualmente, esses serviços oferecem suporte a tokens de acesso:

  • API de Tradução de Texto
  • Serviços de fala: API de fala para texto
  • Serviços de fala: API de conversão de texto em fala

Aviso

Os serviços que suportam tokens de acesso podem mudar ao longo do tempo, verifique a referência da API para um serviço antes de usar esse método de autenticação.

As chaves de recurso de serviço único e multisserviço podem ser trocadas por tokens de autenticação. Os tokens de autenticação são válidos por 10 minutos. Eles são armazenados no formato JSON Web Token (JWT) e podem ser consultados programaticamente usando as bibliotecas JWT.

Os tokens de acesso são incluídos em uma solicitação como cabeçalho Authorization . O valor do token fornecido deve ser precedido por Bearer, por exemplo: Bearer YOUR_AUTH_TOKEN.

Pedidos de amostra

Use este URL para trocar uma chave de recurso por um token de acesso: 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 regiões multisserviço suportam troca de tokens:

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

Depois de obter um token de acesso, você precisará passá-lo em cada solicitação como cabeçalho Authorization . Esta é uma chamada de exemplo para o serviço Azure AI 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

Autenticar com o Microsoft Entra ID

Importante

A autenticação do Microsoft Entra sempre precisa ser usada junto com o nome de subdomínio personalizado do seu recurso do Azure. Os pontos de extremidade regionais não oferecem suporte à autenticação do Microsoft Entra.

Nas seções anteriores, mostramos como autenticar em serviços de IA do Azure usando uma chave de assinatura de serviço único ou multisserviço. Embora essas chaves forneçam um caminho rápido e fácil para iniciar o desenvolvimento, elas ficam aquém em cenários mais complexos que exigem o controle de acesso baseado em função do Azure (Azure RBAC). Vamos dar uma olhada no que é necessário para autenticar usando o Microsoft Entra ID.

Nas seções a seguir, você usará o ambiente do Azure Cloud Shell ou a CLI do Azure para criar um subdomínio, atribuir funções e obter um token de portador para chamar os serviços de IA do Azure. Se você ficar preso, os links são fornecidos em cada seção com todas as opções disponíveis para cada comando no Azure Cloud Shell/CLI do Azure.

Importante

Se a sua organização estiver a fazer autenticação através do Microsoft Entra ID, deve desativar a autenticação local (autenticação com chaves) para que os utilizadores na organização utilizem sempre o Microsoft Entra ID.

Criar um recurso com um subdomínio personalizado

O primeiro passo é criar um subdomínio personalizado. Se você quiser usar um recurso de serviços de IA do Azure existente que não tenha nome de subdomínio personalizado, siga as instruções em Subdomínios personalizados de serviços de IA do Azure para habilitar o subdomínio personalizado para seu recurso.

  1. Comece abrindo o Azure Cloud Shell. Em seguida, selecione uma assinatura:

    Set-AzContext -SubscriptionName <SubscriptionName>

  2. Em seguida, crie um recurso de serviços de IA do Azure com um subdomínio personalizado. O nome do subdomínio precisa ser globalmente exclusivo e não pode incluir caracteres especiais, como: ".", "!", ",".

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

  3. Se for bem-sucedido, o Endpoint deverá mostrar o nome de subdomínio exclusivo do seu recurso.

Atribuir uma função a uma entidade de serviço

Agora que você tem um subdomínio personalizado associado ao seu recurso, precisará atribuir uma função a uma entidade de serviço.

Nota

Lembre-se de que as atribuições de função do Azure podem levar até cinco minutos para se propagar.

  1. Primeiro, vamos registrar um aplicativo Microsoft Entra.

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

$app = New-AzureADApplication -DisplayName <APP_DISPLAY_NAME> -IdentifierUris <APP_URIS> -PasswordCredentials $SecureStringPassword

    Você precisará do ApplicationId na próxima etapa.

  2. Em seguida, você precisa criar uma entidade de serviço para o aplicativo Microsoft Entra.

    New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>

    Nota

    Se você registrar um aplicativo no portal do Azure, esta etapa será concluída para você.

  3. A última etapa é atribuir a função "Usuário de Serviços Cognitivos" à entidade de serviço (com escopo para o recurso). Ao atribuir uma função, você está concedendo acesso da entidade de serviço a esse recurso. Você pode conceder à mesma entidade de serviço acesso a vários recursos em sua assinatura.

    Nota

    O ObjectId da entidade de serviço é usado, não o ObjectId para o aplicativo. O ACCOUNT_ID será a ID de recurso do Azure da conta de serviços de IA do Azure que você criou. Você pode encontrar a ID do recurso do Azure em "propriedades" do recurso no portal do Azure.

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

Pedido de amostra

Neste exemplo, uma senha é usada para autenticar a entidade de serviço. O token fornecido é então usado para chamar a API de Visão Computacional.

  1. Obtenha o seu TenantId:

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

  2. Obtenha um 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

    Sempre que você usar senhas em um script, a opção mais segura é usar o módulo de Gerenciamento de Segredos do PowerShell e integrar com uma solução como o Azure Key Vault.

  3. Chame a API de Visão por Computador:

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

Como alternativa, a entidade de serviço pode ser autenticada com um certificado. Além da entidade de serviço, a entidade de usuário também é suportada por ter permissões delegadas por meio de outro aplicativo Microsoft Entra. Nesse caso, em vez de senhas ou certificados, os usuários seriam solicitados para autenticação de dois fatores ao adquirir token.

Autorizar o acesso a identidades gerenciadas

Os serviços de IA do Azure suportam a autenticação Microsoft Entra com identidades geridas para recursos do Azure. As identidades gerenciadas para recursos do Azure podem autorizar o acesso aos recursos dos serviços de IA do Azure usando credenciais do Microsoft Entra de aplicativos em execução em máquinas virtuais (VMs) do Azure, aplicativos de função, conjuntos de dimensionamento de máquinas virtuais e outros serviços. Usando identidades gerenciadas para recursos do Azure junto com a autenticação do Microsoft Entra, você pode evitar armazenar credenciais com seus aplicativos executados na nuvem.

Habilitar identidades gerenciadas em uma VM

Antes de poder usar identidades gerenciadas para recursos do Azure para autorizar o acesso aos recursos de serviços de IA do Azure a partir de sua VM, você deve habilitar identidades gerenciadas para recursos do Azure na VM. Para saber como habilitar identidades gerenciadas para Recursos do Azure, consulte:

Para obter mais informações sobre identidades gerenciadas, consulte Identidades gerenciadas para recursos do Azure.

Usar o cofre de chaves do Azure para acessar credenciais com segurança

Você pode usar o Azure Key Vault para desenvolver com segurança aplicativos de serviços de IA do Azure. O Cofre de Chaves permite que você armazene suas credenciais de autenticação na nuvem e reduz as chances de que segredos possam ser vazados acidentalmente, porque você não armazenará informações de segurança em seu aplicativo.

A autenticação é feita através do Microsoft Entra ID. A autorização pode ser feita por meio do controle de acesso baseado em função do Azure (Azure RBAC) ou da política de acesso do Cofre da Chave. O RBAC do Azure pode ser usado para o gerenciamento dos cofres e acessar dados armazenados em um cofre, enquanto a política de acesso ao cofre de chaves só pode ser usada ao tentar acessar dados armazenados em um cofre.

Consulte também