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

Artigo
09/04/2024

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

Autenticar com uma chave de recurso de serviço único ou multisserviço
Autenticar com um token
Autenticar com a ID do Microsoft Entra

Pré-requisitos

Antes de fazer uma solicitação, você precisará de uma conta do Azure e uma assinatura dos serviços de IA do Azure. Se você já tiver uma conta, pule para a próxima seção. Caso não tenha uma conta, temos um guia para ajudá-lo a configurá-la em questão de minutos: Como criar um recurso de Serviços de IA do Azure.

Acesse o seu recurso no portal do Azure. A seção Chaves e Ponto de Extremidade pode ser encontrada na seção Gerenciamento de Recursos. Copie o ponto de extremidade e as chave de acesso, pois você precisará de ambos para autenticar suas chamadas à API. Você pode usar KEY1 ou KEY2. Ter sempre duas chaves permite girar e regenerar chaves com segurança, sem causar interrupção de 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.

parâmetro	Descrição
Ocp-Apim-Subscription-Key	Use esse cabeçalho para autenticar com uma chave de recurso para um serviço específico ou uma chave de recurso multisserviço.
Ocp-Apim-Subscription-Region	Este cabeçalho só é necessário ao usar uma chave de recurso multisserviço com o serviço do Tradutor de IA do Azure. Use esse cabeçalho para especificar a região do recurso.
Autorização	Use esse cabeçalho se você está usando um token de acesso. As etapas para executar uma troca de tokens estã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 Tradutor de IA do Azure. As chaves estão disponíveis no portal do Azure para cada recurso que você criou. Acesse o seu recurso no portal do Azure. A seção Chaves e Ponto de Extremidade pode ser encontrada na seção Gerenciamento de Recursos. Copie o ponto de extremidade e as chave de acesso, pois você precisará de ambos para autenticar suas chamadas à API. Você pode usar KEY1 ou KEY2. Ter sempre duas chaves permite girar e regenerar chaves com segurança, sem causar interrupção de serviço.

Para usar uma chave de recurso para autenticar uma solicitação, ela deve ser transmitida como cabeçalho Ocp-Apim-Subscription-Key. Essa é uma chamada de exemplo para o serviço do Tradutor de IA do Azure:

Essa é uma chamada de exemplo para o serviço do 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. Confira os preços dos serviços de IA do Azure para obter informações sobre disponibilidade regional, recursos com suporte e preços.

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

Regiões com suporte

Ao usar a chave de recurso de vários serviços dos Serviços de IA do Azure para fazer uma solicitação para api.cognitive.microsoft.com, incluía a região no URL. Por exemplo: westus.api.cognitive.microsoft.com.

Ao utilizar uma chave de recursos multisserviço com o Tradutor de IA do Azure, deve especificar a região do recurso com o cabeçalho Ocp-Apim-Subscription-Region.

A autenticação de recursos de vários serviços tem suporte nestas regiões:

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

Solicitações de exemplo

Essa é uma chamada de exemplo para o serviço do Tradutor de IA do Azure:

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, estes serviços dão suporte a tokens de acesso:

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

Aviso

Os serviços que dão suporte a tokens de acesso podem mudar ao longo do tempo; confira a referência de API de um serviço antes de usar esse método de autenticação.

As chaves de recurso de serviço único e de 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 JWT (Token Web JSON) e podem ser consultados programaticamente usando as bibliotecas JWT.

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

Solicitações de exemplo

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 de vários serviços dão suporte à 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á transmiti-lo em cada solicitação como o cabeçalho Authorization. Essa é uma chamada de exemplo para o serviço do Tradutor de IA do Azure:

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

Autenticação com o Microsoft Entra ID

Importante

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

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

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 paralisado, 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 sua organização estiver autenticando pela ID do Microsoft Entra, você deverá desabilitar a autenticação local (autenticação com chaves) para que os usuários da organização sempre usem a ID do Microsoft Entra.

Crie um recurso com um subdomínio personalizado

A primeira etapa é criar um subdomínio personalizado. Se você quiser usar um recurso existente de serviços de IA do Azure que não tenha um 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.

Comece abrindo o Azure Cloud Shell. Em seguida, selecione uma assinatura:
```
Set-AzContext -SubscriptionName <SubscriptionName>
```

Em seguida, crie um recurso de serviços de IA do Azure com um subdomínio personalizado. O nome do subdomínio deve 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>

Se for bem-sucedido, o Ponto de extremidade deverá mostrar o nome do subdomínio exclusivo para 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.

Observação

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

Primeiro, vamos registrar um aplicativo do 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.

Em seguida, você precisa criar uma entidade de serviço para o aplicativo Microsoft Entra.
```
New-AzADServicePrincipal -ApplicationId <APPLICATION_ID>
```
Observação

Se você registrar um aplicativo no portal do Azure, esta etapa será concluída para você.
A última etapa é atribuir a função "Usuário de Serviços Cognitivos do Azure" à entidade de serviço (com escopo definido para o recurso). Ao atribuir uma função, você está concedendo acesso principal de serviço a este recurso. Você pode conceder ao mesmo acesso de emtodade de serviço a vários recursos em sua assinatura.

Observação

O ObjectId da entidade de serviço é usada, não o ObjectId do aplicativo. 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 nas "Propriedades" do recurso no portal do Azure.
```
New-AzRoleAssignment -ObjectId <SERVICE_PRINCIPAL_OBJECTID> -Scope <ACCOUNT_ID> -RoleDefinitionName "Cognitive Services User"
```

Solicitação de exemplo

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

Obtenha sua TenantId:

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

Obter 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

Observação

Sempre que utilizar palavras-passe num script, a opção mais segura é utilizar o módulo PowerShell Secrets Management e integrar-se com uma solução como o Azure Key Vault.

Chamar a API da Pesquisa Visual Computacional:

$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 segurança do usuário também tem suporte por ter permissões delegadas por outro aplicativo do Microsoft Entra. Nesse caso, em vez de senhas ou certificados, os usuários devem solicitar a autenticação de dois fatores ao adquirir o token.

Autorizar o acesso a identidades gerenciadas

Os serviços de IA do Azure dão suporte à autenticação do Microsoft Entra com identidades gerenciadas 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 VMs (máquinas virtuais) do Azure, aplicativos de funções, 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 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 saber mais sobre identidades gerenciadas, confira 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 aplicativos de serviços de IA do Azure com segurança. O Key Vault permite armazenar suas credenciais de autenticação na nuvem e reduz a probabilidade de vazamento acidental dos segredos, pois as informações de segurança não são armazenadas no aplicativo.

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

Compartilhar via

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

Pré-requisitos

Cabeçalhos de autenticação

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

Autenticar com uma chave de recurso multisserviço

Regiões com suporte

Solicitações de exemplo

Autenticar com um token de acesso

Solicitações de exemplo

Autenticação com o Microsoft Entra ID

Crie um recurso com um subdomínio personalizado

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

Solicitação de exemplo

Autorizar o acesso a identidades gerenciadas

Habilitar identidades gerenciadas em uma VM

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

Confira também

Comentários

Recursos adicionais