Partilhar via

Autenticar pedidos para a Foundry Tools

Cada pedido às Foundry Tools 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 fazeres um pedido, precisas de uma subscrição do Azure e de um recurso do Foundry. Se precisar de um recurso Foundry, consulte o guia de criação de recursos Foundry .

Cabeçalhos de autenticação

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

Cabeçalho Descrição
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 Foundry.
OCP-Apim-Assinatura-Região Este cabeçalho só é necessário quando se utiliza uma chave de recurso Foundry com o Azure 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 um pedido com uma chave de recurso para um serviço específico, como o Azure 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 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 Foundry

Pode usar uma chave de recurso Foundry para autenticar pedidos de múltiplas ferramentas Foundry. As credenciais de autenticação não estão vinculadas a um serviço específico. Consulte os preços da Foundry Tools para informações sobre disponibilidade regional, funcionalidades suportadas 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 Foundry para fazer um pedido a api.cognitive.microsoft.com, deve incluir a região na URL. Por exemplo: westus.api.cognitive.microsoft.com.

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

A autenticação de recursos por Foundry é 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 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

Algumas Foundry Tools 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
  • Discursos: API de voz para texto
  • Discursos: API de Texto para Fala

Aviso

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

As chaves de recursos da Plataforma Foundry e dos serviços de 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 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 suportam a troca de tokens por recursos da 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á passá-lo em cada solicitação como cabeçalho Authorization . Esta é uma chamada de exemplo para o serviço 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

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 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 controle de acesso baseado em função do Azure (Azure RBAC). Vamos dar uma olhada no que é necessário para autenticar com mais segurança usando o Microsoft Entra ID.

Nas secções seguintes, irá usar o ambiente Azure Cloud Shell ou a Azure CLI para criar um subdomínio, atribuir papéis e obter um token portador para chamar as Foundry Tools. 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 quiser usar um recurso Foundry existente que não tenha um nome de subdomínio personalizado, siga as instruções nos subdomínios personalizados das Foundry Tools para ativar subdomínios personalizados para o seu recurso.

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

    Set-AzContext -SubscriptionName <SubscriptionName>

  2. De seguida, crie um recurso Foundry 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 registar uma aplicação 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á o ID do recurso Azure do recurso Foundry que criaste. 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 Azure Vision.

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

O Foundry Tools suporta autenticação Microsoft Entra com identidades geridas para recursos Azure. Identidades geridas para recursos Azure podem autorizar o acesso a recursos Foundry usando credenciais Microsoft Entra a partir de aplicações a correr em máquinas virtuais Azure (VMs), aplicações de funções, conjuntos de escalas 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 máquina virtual (VM)

Antes de poder usar identidades geridas para recursos Azure para autorizar o acesso a recursos Foundry a partir da sua VM, deve ativar identidades geridas para recursos 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

Pode usar o Azure Key Vault para desenvolver aplicações Microsoft Foundry de forma segura. 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.

Conteúdos relacionados

  • Last updated on