Compartilhar via

Autenticar solicitações do Foundry Tools

Cada solicitação às Ferramentas Foundry deve incluir um cabeçalho de autenticação. Este cabeçalho transmite uma chave de recurso ou um 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.

Pré-requisitos

Antes de fazer uma solicitação, você precisa de uma assinatura do Azure e de um recurso do Foundry. Se você precisar de um recurso do Foundry, consulte o guia criar um recurso do Foundry .

Cabeçalhos de autenticação

Vamos revisar rapidamente os cabeçalhos de autenticação disponíveis para uso com as Foundry Tools.

Cabeçalho 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 do Foundry.
Ocp-Apim-Subscription-Region Esse cabeçalho só é necessário ao usar uma chave de recurso do Foundry com o Tradutor 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>.

Autenticação 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 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 precisa ser transmitida como o cabeçalho Ocp-Apim-Subscription-Key. Esta é uma chamada de exemplo para o serviço tradutor 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 do Foundry

Você pode usar uma chave de recurso do Foundry para autenticar solicitações para várias Ferramentas do Foundry. As credenciais de autenticação não estão vinculadas a um serviço específico. Veja Preço do Foundry Tools 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 do Foundry para fazer uma solicitação a api.cognitive.microsoft.com, é necessário incluir a região na URL. Por exemplo: westus.api.cognitive.microsoft.com.

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

Há suporte para autenticação de recurso de fundição nessas 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

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

Algumas ferramentas da Foundry 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
  • Discursos: API de transcrição de fala em texto
  • Discursos: API de texto para fala

Aviso

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

As chaves dos recursos dos serviços Foundry e IA 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 esta 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"

Essas regiões dão suporte à troca de tokens para recursos do Foundry:

  • 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. Esta é uma chamada de exemplo para o serviço tradutor 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

Autenticar-se 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 usando chaves de API. Embora essas chaves forneçam um caminho rápido e fácil para iniciar o desenvolvimento, elas ficam aquém em cenários que exigem o RBAC (controle de acesso baseado em função) do Azure. Vamos dar uma olhada no que é necessário para autenticar com mais segurança 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 acesso para chamar as Ferramentas Foundry. 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 do Foundry que não tenha um nome de subdomínio personalizado, siga as instruções em subdomínios personalizados do Foundry Tools para habilitar o subdomínio personalizado para o seu recurso.

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

    Set-AzContext -SubscriptionName <SubscriptionName>

  2. Em seguida, crie um recurso do Foundry 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>

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

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

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

  3. 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. O ACCOUNT_ID será a ID do recurso do Azure do recurso Foundry que você criou. Você pode encontrar o ID de recurso 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 é usado para chamar a API do Azure Vision.

  1. Obtenha sua TenantId:

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

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

  3. Chame a API do Azure 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, 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

As Ferramentas Foundry suportam a 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 do Foundry usando as 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 (Máquina Virtual)

Antes de usar identidades gerenciadas para recursos do Azure para autorizar o acesso aos recursos do Foundry de sua VM, você deve habilitar identidades gerenciadas para recursos do Azure na VM. Para saber como habilitar identidades gerenciadas para recursos do Azure, confira:

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 com segurança aplicativos do Microsoft Foundry. 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.

Conteúdo relacionado

  • Last updated on