Autenticação do Microsoft Entra com o SDK de Fala

Artigo
09/09/2024

Ao usar o SDK de Fala para acessar o serviço de Fala, há três métodos de autenticação disponíveis: chaves de serviço, um token baseado em chave e a ID do Microsoft Entra. Este artigo descreve como configurar um recurso de Fala e criar um objeto de configuração do SDK de Fala para usar a ID do Microsoft Entra para autenticação.

Este artigo mostra como usar a autenticação do Microsoft Entra com o SDK de Fala. Você aprenderá como:

Criar um recurso de Fala
Configurar o recurso de Fala para autenticação do Microsoft Entra
Obter um token de acesso do Microsoft Entra
Criar o objeto de configuração do SDK apropriado.

Para saber mais sobre os tokens de acesso do Microsoft Entra, incluindo o tempo de vida do token, visite tokens do Access na plataforma de identidade da Microsoft.

Criar um recurso de Fala

Para criar um recurso de Fala no portal do Azure, consulte este início rápido.

Configurar o recurso de Fala para autenticação do Microsoft Entra

Para configurar o recurso de Fala para autenticação do Microsoft Entra, crie um nome de domínio personalizado e atribua funções.

Criar um nome de domínio personalizado

Siga as etapas a seguir para criar um nome de subdomínio personalizado para os serviços de IA do Azure para seu recurso de Fala.

Cuidado

Quando você ativa um nome de domínio personalizado, a operação não é reversível. A única maneira de voltar para o nome regional é criar outro recurso de Fala.

Se o recurso de Fala tem muitos modelos e projetos personalizados associados criados por meio do Speech Studio, é altamente recomendável experimentar a configuração com um recurso de teste antes de modificar o recurso usado na produção.

Para criar um nome de domínio personalizado usando o portal do Azure, siga estas etapas:

Vá para o portal do Azure e entre em sua conta do Azure.
Selecione o recurso de Fala necessário.
No grupo Gerenciamento de Recursos no painel esquerdo, selecione Rede.
Na guia Firewalls e redes virtuais, selecione Gerar nome de domínio personalizado. Um novo painel é exibido à direita, com instruções para criar um subdomínio personalizado exclusivo para o recurso.
No painel Gerar nome de domínio personalizado, insira um nome de domínio personalizado. O domínio personalizado completo terá a seguinte aparência: https://{your custom name}.cognitiveservices.azure.com.

Lembre-se de que, após você criar um nome de domínio personalizado, ele não poderá ser alterado.

Depois de inserir o nome de domínio personalizado, selecione Salvar.
Após a conclusão da operação, no grupo Gerenciamento de recursos, selecione Chaves e ponto de extremidade. Confirme se o novo nome do ponto de extremidade do recurso é iniciado dessa maneira: https://{your custom name}.cognitiveservices.azure.com.

Para criar um nome de domínio personalizado usando o PowerShell, confirme se o computador tem o PowerShell versão 7.x ou posterior com o módulo do Azure PowerShell versão 5.1.0 ou posterior. Para ver as versões dessas ferramentas, siga estas etapas:

Em uma janela do PowerShell, digite:

$PSVersionTable

Confirme se o valor de PSVersion é 7.x ou posterior. Para atualizar o PowerShell, siga as instruções em Instalando várias versões do PowerShell.
Em uma janela do PowerShell, digite:

Get-Module -ListAvailable Az

Se nada aparecer ou se a versão do módulo do Azure PowerShell for anterior à 5.1.0, siga as instruções em Instalar o módulo do Azure PowerShell para atualizar.

Antes de continuar, execute Connect-AzAccount para criar uma conexão com o Azure.

Verificar se o nome de domínio personalizado está disponível

Verifique se o domínio personalizado que você deseja usar está disponível. O código a seguir confirma que o domínio está disponível usando a operação Verificar Disponibilidade de Domínio na API REST dos serviços de IA do Azure.

Observação

O código a seguir não funciona no Azure Cloud Shell.

$subscriptionId = "Your Azure subscription Id"
$subdomainName = "custom domain name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
Set-AzContext -SubscriptionId $subscriptionId

# Prepare the OAuth token to use in the request to the Azure AI services REST API.
$Context = Get-AzContext
$AccessToken = (Get-AzAccessToken -TenantId $Context.Tenant.Id).Token
$token = ConvertTo-SecureString -String $AccessToken -AsPlainText -Force

# Prepare and send the request to the Azure AI services REST API.
$uri = "https://management.azure.com/subscriptions/" + $subscriptionId + `
    "/providers/Microsoft.CognitiveServices/checkDomainAvailability?api-version=2017-04-18"
$body = @{
subdomainName = $subdomainName
type = "Microsoft.CognitiveServices/accounts"
}
$jsonBody = $body | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri $uri -ContentType "application/json" -Authentication Bearer `
    -Token $token -Body $jsonBody | Format-List

Se o nome desejado estiver disponível, você verá uma resposta como esta:

isSubdomainAvailable : True
reason               :
type                 :
subdomainName        : my-custom-name

Se o nome já estiver em uso, você verá a seguinte resposta:

isSubdomainAvailable : False
reason               : Sub domain name 'my-custom-name' is already used. Please pick a different name.
type                 :
subdomainName        : my-custom-name

Criar o nome de domínio personalizado

Para ativar um nome de domínio personalizado para o recurso de Fala selecionado, use o cmdlet Set-AzCognitiveServicesAccount.

Cuidado

Depois que o código a seguir for executado com êxito, você criará um nome de domínio personalizado para o recurso de Fala. Lembre-se de que o nome não pode ser alterado.

$resourceGroup = "Resource group name where Speech resource is located"
$speechResourceName = "Your Speech resource name"
$subdomainName = "custom domain name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
$subscriptionId = "Your Azure subscription Id"
Set-AzContext -SubscriptionId $subscriptionId

# Set the custom domain name to the selected resource.
# WARNING: THIS CANNOT BE CHANGED OR UNDONE!
Set-AzCognitiveServicesAccount -ResourceGroupName $resourceGroup `
    -Name $speechResourceName -CustomSubdomainName $subdomainName

Pré-requisitos

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
- Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Esta seção exige a última versão da CLI do Azure. Se você está usando o Azure Cloud Shell, a última versão já está instalada.

Verificar se o nome de domínio personalizado está disponível

Verifique se o domínio personalizado que deseja usar está disponível. Use o método Verificar Disponibilidade do Domínio da API REST dos serviços de IA do Azure.

Copie o bloco de código a seguir, insira o nome de domínio personalizado de sua experiência e salve-o no arquivo subdomain.json.

{
    "subdomainName": "custom domain name",
    "type": "Microsoft.CognitiveServices/accounts"
}

Copie o arquivo para a pasta atual ou carregue-o no Azure Cloud Shell e execute o comando a seguir. Substitua xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx por sua ID da assinatura do Azure.

az rest --method post --url "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/Microsoft.CognitiveServices/checkDomainAvailability?api-version=2017-04-18" --body @subdomain.json

Se o nome desejado estiver disponível, você verá uma resposta como esta:

{
  "isSubdomainAvailable": true,
  "reason": null,
  "subdomainName": "my-custom-name",
  "type": null
}

Se o nome já estiver em uso, você verá a seguinte resposta:

{
  "isSubdomainAvailable": false,
  "reason": "Sub domain name 'my-custom-name' is already used. Please pick a different name.",
  "subdomainName": "my-custom-name",
  "type": null
}

Ativar um nome de domínio personalizado

Para usar um nome de domínio personalizado com o recurso de Fala selecionado, use o comando az cognitiveservices account update.

(Se sua conta do Azure tiver apenas uma assinatura ativa, você poderá ignorar esta etapa.) Selecione a assinatura do Azure que contém o recurso de Fala. Substitua xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx por sua ID da assinatura do Azure.

az account set --subscription xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Defina o nome de domínio personalizado do recurso selecionado. Substitua os valores de parâmetro de exemplo pelos reais e execute o comando a seguir.

Cuidado

Após a execução bem-sucedida do comando a seguir, você criará um nome de domínio personalizado para o recurso de Fala. Lembre-se de que o nome não pode ser alterado.

az cognitiveservices account update --name my-speech-resource-name --resource-group my-resource-group-name --custom-domain my-custom-name

Atribuir funções

Para autenticação do Microsoft Entra com recursos de Fala, você precisa atribuir a função de Usuário de Fala dos Serviços Cognitivos ou de Usuário de Fala dos Serviços Cognitivos.

Você pode atribuir funções ao usuário ou ao aplicativo usando o portal do Azure ou o PowerShell.

Obter um token de acesso do Microsoft Entra

Para obter um token de acesso do Microsoft Entra em C#, use a Biblioteca de Clientes de Identidade do Azure.

Aqui está um exemplo de como usar a Identidade do Azure para obter um token de acesso do Microsoft Entra de um navegador interativo:

TokenRequestContext context = new Azure.Core.TokenRequestContext(new string[] { "https://cognitiveservices.azure.com/.default" });
InteractiveBrowserCredential browserCredential = new InteractiveBrowserCredential();
var browserToken = browserCredential.GetToken(context);
string aadToken = browserToken.Token;

Observação

O contexto do token deve ser definido como "https://cognitiveservices.azure.com/.default".

Para obter um token de acesso do Microsoft Entra no C++, use a Biblioteca de Clientes de Identidade do Azure.

Aqui está um exemplo de como usar a Identidade do Azure para obter um token de acesso do Microsoft Entra com a ID do locatário, a ID do cliente e as credenciais de segredo do cliente:

const std::string tokenContext = "https://cognitiveservices.azure.com/.default";

Azure::Identity::DefaultAzureCredential();

Azure::Core::Credentials::TokenRequestContext context;
context.Scopes.push_back(tokenContext);

auto token = cred.GetToken(context, Azure::Core::Context());

Observação

O contexto do token deve ser definido como "https://cognitiveservices.azure.com/.default".

Para obter um token de acesso do Microsoft Entra em Java, use a Biblioteca de Clientes de Identidade do Azure.

Veja um exemplo de como usar a Identidade do Azure para obter um token de acesso do Microsoft Entra de um navegador:

TokenRequestContext context = new TokenRequestContext();
context.addScopes("https://cognitiveservices.azure.com/.default");

InteractiveBrowserCredentialBuilder builder = new InteractiveBrowserCredentialBuilder();
InteractiveBrowserCredential browserCredential = builder.build();

AccessToken browserToken = browserCredential.getToken(context).block();
String token = browserToken.getToken();

Observação

O contexto do token deve ser definido como "https://cognitiveservices.azure.com/.default".

Para obter um token de acesso do Microsoft Entra em Java, use a Biblioteca de Clientes de Identidade do Azure.

Aqui está um exemplo de como usar a Identidade do Azure para obter um token de acesso do Microsoft Entra de um navegador interativo:

from azure.identity import  InteractiveBrowserCredential
ibc = InteractiveBrowserCredential()
aadToken = ibc.get_token("https://cognitiveservices.azure.com/.default")

Encontre exemplos que obtêm um token de acesso do Microsoft Entra em exemplos de código da plataforma de identidade da Microsoft.

Para linguagens de programação nas quais uma biblioteca de cliente da plataforma de identidade da Microsoft não está disponível, você pode solicitar um token de acesso diretamente.

Obter a ID do recurso de Fala

Você precisa da ID do recurso de Fala para fazer chamadas do SDK usando a autenticação do Microsoft Entra.

Observação

Para o Reconhecimento de intenção, use sua ID de recurso de Previsão LUIS.

Azure portal
PowerShell

Para obter a ID do recurso no portal do Azure:

Vá para o portal do Azure e entre em sua conta do Azure.
Selecionar um recurso de Fala.
No grupo Gerenciamento de Recursos no painel esquerdo, selecione Propriedades.
Copie a ID do recurso

Para obter a ID do recurso usando o PowerShell, confirme se você tem o PowerShell versão 7. x ou posterior com o módulo Azure PowerShell versão 5.1.0 ou posterior. Para ver as versões dessas ferramentas, siga estas etapas:

Em uma janela do PowerShell, digite:

$PSVersionTable

Confirme se o valor de PSVersion é 7.x ou posterior. Para atualizar o PowerShell, siga as instruções em Instalando várias versões do PowerShell.
Em uma janela do PowerShell, digite:

Get-Module -ListAvailable Az

Se nada aparecer ou se a versão do módulo do Azure PowerShell for anterior à 5.1.0, siga as instruções em Instalar o módulo do Azure PowerShell para atualizar.

Agora execute Connect-AzAccount para criar uma conexão com o Azure.

Connect-AzAccount
$subscriptionId = "Your Azure subscription Id"
$resourceGroup = "Resource group name where Speech resource is located"
$speechResourceName = "Your Speech resource name"

# Select the Azure subscription that contains the Speech resource.
# You can skip this step if your Azure account has only one active subscription.
Set-AzContext -SubscriptionId $subscriptionId

# Get the Speech resource 
$resource = Get-AzCognitiveServicesAccount -Name $speechResourceName -ResourceGroupName $resourceGroup

# Get the resource ID:
$resourceId = resource.Id

Criar o objeto de configuração do SDK de Fala

Com um token de acesso do Microsoft Entra, agora você pode criar um objeto de configuração do SDK de Fala.

O método de fornecer o token e o método para construir o objeto Config do SDK de Fala correspondente varia de acordo com o objeto que você está usando.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

Para os objetos SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber, crie o token de autorização a partir da ID do recurso e do token de acesso do Microsoft Entra e, em seguida, use-o para criar um objeto SpeechConfig.

string resourceId = "Your Resource ID";
string aadToken = "Your Microsoft Entra access token";
string region =  "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
var authorizationToken = $"aad#{resourceId}#{aadToken}";
var speechConfig = SpeechConfig.FromAuthorizationToken(authorizationToken, region);

std::string resourceId = "Your Resource ID";
std::string aadToken = "Your Microsoft Entra access token";
std::string region = "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
auto speechConfig = SpeechConfig::FromAuthorizationToken(authorizationToken, region);

String resourceId = "Your Resource ID";
String region = "Your Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
String authorizationToken = "aad#" + resourceId + "#" + token;
SpeechConfig speechConfig = SpeechConfig.fromAuthorizationToken(authorizationToken, region);

resourceId = "Your Resource ID"
region = "Your Region"
# You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
speechConfig = SpeechConfig(auth_token=authorizationToken, region=region)

TranslationRecognizer

Para o TranslationRecognizer, crie o token de autorização com base na ID do recurso e no token de acesso do Microsoft Entra e, em seguida, use-o para criar um objeto SpeechTranslationConfig.

string resourceId = "Your Resource ID";
string aadToken = "Your Microsoft Entra access token";
string region =  "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
var authorizationToken = $"aad#{resourceId}#{aadToken}";
var speechConfig = SpeechTranslationConfig.FromAuthorizationToken(authorizationToken, region);

std::string resourceId = "Your Resource ID";
std::string aadToken = "Your Microsoft Entra access token";
std::string region = "Your Speech Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
auto speechConfig = SpeechTranslationConfig::FromAuthorizationToken(authorizationToken, region);

String resourceId = "Your Resource ID";
String region = "Your Region";

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
String authorizationToken = "aad#" + resourceId + "#" + token;
SpeechTranslationConfig translationConfig = SpeechTranslationConfig.fromAuthorizationToken(authorizationToken, region);

resourceId = "Your Resource ID"
region = "Your Region"

# You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
translationConfig = SpeechTranslationConfig(auth_token=authorizationToken, region=region)

VoiceProfileClient

Para usar o VoiceProfileClient com a autenticação do Microsoft Entra, use o nome de domínio personalizado criado acima.

string customDomainName = "Your Custom Name";
string hostName = $"https://{customDomainName}.cognitiveservices.azure.com/";
string token = "Your Microsoft Entra access token";

var config =  SpeechConfig.FromHost(new Uri(hostName));

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
var authorizationToken = $"aad#{resourceId}#{aadToken}";
config.AuthorizationToken = authorizationToken;

std::string customDomainName = "Your Custom Name";
std::string aadToken = "Your Microsoft Entra access token";

auto speechConfig = SpeechConfig::FromHost("https://" + customDomainName + ".cognitiveservices.azure.com/");

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
speechConfig->SetAuthorizationToken(authorizationToken);

String aadToken = "Your Microsoft Entra access token";
String customDomainName = "Your Custom Name";
String hostName = "https://" + customDomainName + ".cognitiveservices.azure.com/";
SpeechConfig speechConfig = SpeechConfig.fromHost(new URI(hostName));

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and Microsoft Entra access token.
String authorizationToken = "aad#" + resourceId + "#" + token;

speechConfig.setAuthorizationToken(authorizationToken);

O VoiceProfileClient não está disponível com o SDK de Fala para Python.

Observação

O ConversationTranslator não é compatível com a autenticação Microsoft Entra.

Compartilhar via

Autenticação do Microsoft Entra com o SDK de Fala

Criar um recurso de Fala

Configurar o recurso de Fala para autenticação do Microsoft Entra

Criar um nome de domínio personalizado

Verificar se o nome de domínio personalizado está disponível

Criar o nome de domínio personalizado

Pré-requisitos

Verificar se o nome de domínio personalizado está disponível

Ativar um nome de domínio personalizado

Atribuir funções

Obter um token de acesso do Microsoft Entra

Obter a ID do recurso de Fala

Criar o objeto de configuração do SDK de Fala

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

TranslationRecognizer

VoiceProfileClient

Comentários

Recursos adicionais