Autenticazione di Microsoft Entra con Speech SDK

Articolo
09/09/2024

Quando si usa Speech SDK per accedere al servizio Voce, sono disponibili tre metodi di autenticazione: chiavi del servizio, token basato su chiave e Microsoft Entra ID. Questo articolo spiega come configurare una risorsa Voce e creare un oggetto di configurazione di Speech SDK per poter usare Microsoft Entra ID per l'autenticazione.

Questo articolo mostra come usare l'autenticazione di Microsoft Entra con Speech SDK. Scopri come:

Creare una risorsa Voce
Configurare la risorsa Voce per l'autenticazione di Microsoft Entra
Ottenere un token di accesso di Microsoft Entra
Creare l'oggetto di configurazione dell'SDK appropriato.

Per altre informazioni sui token di accesso di Microsoft Entra, inclusa la durata dei token, vedere Token di accesso in Microsoft Identity Platform.

Creare una risorsa Voce

Per creare una risorsa Voce nel portale di Azure, vedere questa guida rapida.

Configurare la risorsa Voce per l'autenticazione di Microsoft Entra

Per configurare la risorsa Voce per l'autenticazione di Microsoft Entra, creare un nome di dominio personalizzato e assegnare i ruoli.

Creare un nome di dominio personalizzato

Seguire questa procedura per creare un nome di sottodominio personalizzato per i servizi di intelligenza artificiale di Azure per la risorsa Voce.

Attenzione

Quando si attiva un nome di dominio personalizzato, l'operazione non è reversibile. L'unico modo per tornare al nome locale consiste nel creare una nuova risorsa Voce.

Se la risorsa Voce ha molti modelli e progetti personalizzati associati creati tramite Speech Studio, è consigliabile provare la configurazione con una risorsa di test prima di modificare la risorsa usata nell'ambiente di produzione.

Per creare un nome di dominio personalizzato usando il portale di Azure, seguire questa procedura:

Passare al portale di Azure e accedere all'account Azure.
Selezionare la risorsa Voce necessaria.
Nel gruppo Gestione risorse nel riquadro sinistro, selezionare Rete.
Nella scheda Firewall e reti virtuali selezionare Genera nome di dominio personalizzato. Verrà visualizzato un nuovo pannello a destra con le istruzioni per creare un sottodominio personalizzato univoco per la risorsa.
Nel pannello Genera nome di dominio personalizzato immettere un nome di dominio personalizzato. Il dominio personalizzato completo sarà simile al seguente: https://{your custom name}.cognitiveservices.azure.com.

Tenere presente che, dopo aver creato un nome di dominio personalizzato, questo non può essere modificato.

Dopo aver immesso il nome di dominio personalizzato, selezionare Salva.
Al termine dell'operazione, nel gruppo Gestione risorse selezionare Chiavi ed endpoint. Verificare che il nuovo nome endpoint della risorsa inizi in questo modo: https://{your custom name}.cognitiveservices.azure.com.

Per creare un nome di dominio personalizzato usando PowerShell, verificare che nel computer sia presente PowerShell versione 7.x o successiva con il modulo Azure PowerShell versione 5.1.0 o successiva. Per visualizzare le versioni di questi strumenti, seguire questa procedura:

In una finestra di PowerShell immettere:

$PSVersionTable

Verificare che il valore di PSVersion sia 7.x o versione successiva. Per aggiornare PowerShell, seguire le istruzioni in Installazione di varie versioni di PowerShell.
In una finestra di PowerShell immettere:

Get-Module -ListAvailable Az

Se non viene visualizzato alcun elemento o se la versione del modulo di Azure PowerShell è precedente alla 5.1.0, seguire le istruzioni in Installare il modulo Azure PowerShell per eseguire l'aggiornamento.

Prima di procedere, eseguire Connect-AzAccount per creare una connessione con Azure.

Verificare che un nome di dominio personalizzato sia disponibile

Controllare se il dominio personalizzato che si vuole usare è disponibile. Il codice seguente conferma che il dominio è disponibile usando l'operazione Verifica disponibilità dominio nell'API REST dei servizi di intelligenza artificiale di Azure.

Nota

Il codice seguente non funziona in 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 il nome desiderato è disponibile, verrà visualizzata una risposta simile alla seguente:

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

Se il nome è già in uso, verrà visualizzata la risposta seguente:

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

Creare il nome di dominio personalizzato

Per attivare un nome di dominio personalizzato per la risorsa Voce selezionata, usare il cmdlet Set-AzCognitiveServicesAccount.

Attenzione

Dopo aver eseguito il codice seguente, si creerà un nome di dominio personalizzato per la risorsa Voce. Tenere presente che questo nome non può essere modificato.

$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

Prerequisiti

Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Avvio rapido su Bash in Azure Cloud Shell.
Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.
- Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Accedere tramite l'interfaccia della riga di comando di Azure.
- Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare le estensioni con l'interfaccia della riga di comando di Azure.
- Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

Questa sezione richiede la versione più recente dell'interfaccia della riga di comando di Azure. Se si sta usando Azure Cloud Shell, la versione più recente è già installata.

Verificare che il nome di dominio personalizzato sia disponibile

Controllare se il dominio personalizzato che si vuole usare è gratuito. Usare il metodo Verifica disponibilità del dominio dall'API REST dei servizi di intelligenza artificiale di Azure.

Copiare il blocco di codice seguente, inserire il nome di dominio personalizzato preferito e salvare nel file subdomain.json.

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

Copiare il file nella cartella corrente o caricarlo in Azure Cloud Shell ed eseguire il comando seguente. Sostituire xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx con l'ID della sottoscrizione di 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 il nome desiderato è disponibile, verrà visualizzata una risposta simile alla seguente:

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

Se il nome è già in uso, verrà visualizzata la risposta seguente:

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

Attivare un nome di dominio personalizzato

Per usare un nome di dominio personalizzato con la risorsa Voce selezionata, usare il comando az cognitiveservices account update.

Se l'account di Azure ha una sola sottoscrizione attiva, è possibile ignorare questo passaggio. Selezionare la sottoscrizione di Azure che contiene la risorsa Voce. Sostituire xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx con l'ID della sottoscrizione di Azure.

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

Impostare il nome di dominio personalizzato sulla risorsa selezionata. Sostituire i valori dei parametri di esempio con quelli effettivi ed eseguire il comando seguente.

Attenzione

Dopo aver completato l'esecuzione del comando seguente, si creerà un nome di dominio personalizzato per la risorsa Voce. Tenere presente che questo nome non può essere modificato.

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

Assegnazione di ruoli

Per l'autenticazione di Microsoft Entra con le risorse Voce, è necessario assegnare il ruolo di collaboratore Voce dei Servizi cognitivi o utente Voce di Servizi cognitivi.

È possibile assegnare ruoli all'utente o all'applicazione usando il portale di Azure o PowerShell.

Ottenere un token di accesso di Microsoft Entra

Per ottenere un token di accesso di Microsoft Entra in C#, usare la libreria client delle identità di Azure.

Ecco un esempio dell'uso dell’identità di Azure per ottenere un token di accesso di Microsoft Entra da un browser interattivo:

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;

Nota

Il contesto del token deve essere impostato su "https://cognitiveservices.azure.com/.default".

Per ottenere un token di accesso di Microsoft Entra in C++, usare la libreria client delle identità di Azure.

Ecco un esempio dell'uso dell’identità di Azure per ottenere un token di accesso di Microsoft Entra con l'ID tenant, l'ID client e le credenziali del segreto client:

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());

Nota

Il contesto del token deve essere impostato su "https://cognitiveservices.azure.com/.default".

Per ottenere un token di accesso di Microsoft Entra in Java, usare la libreria client delle identità di Azure.

Ecco un esempio dell'uso dell’identità di Azure per ottenere un token di accesso di Microsoft Entra da un browser:

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();

Nota

Il contesto del token deve essere impostato su "https://cognitiveservices.azure.com/.default".

Per ottenere un token di accesso di Microsoft Entra in Python, usare la libreria client delle identità di Azure.

Ecco un esempio dell'uso dell’identità di Azure per ottenere un token di accesso di Microsoft Entra da un browser interattivo:

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

Gli esempi di codice che consentono di ottenere un token di accesso di Microsoft Entra sono disponibili in Esempi di codice per Microsoft Identity Platform.

Per i linguaggi di programmazione in cui non è disponibile una libreria client di Microsoft Identity Platform, è possibile richiedere un token di accesso direttamente.

Ottenere l'ID della risorsa Voce

È necessario l'ID della risorsa Voce per effettuare chiamate SDK usando l'autenticazione di Microsoft Entra.

Nota

Per Riconoscimento finalità usare l'ID della risorsa di stima LUIS.

Azure portal
PowerShell

Per ottenere l'ID della risorsa nel portale di Azure:

Passare al portale di Azure e accedere all'account Azure.
Selezionare una risorsa Voce.
Nel gruppo Gestione risorse nel riquadro sinistro, selezionare Proprietà.
Copiare l'ID risorsa

Per ottenere l'ID della risorsa usando PowerShell, verificare di disporre di PowerShell versione 7.x o successiva con il modulo Azure PowerShell versione 5.1.0 o successiva. Per visualizzare le versioni di questi strumenti, seguire questa procedura:

In una finestra di PowerShell immettere:

$PSVersionTable

Verificare che il valore di PSVersion sia 7.x o versione successiva. Per aggiornare PowerShell, seguire le istruzioni in Installazione di varie versioni di PowerShell.
In una finestra di PowerShell immettere:

Get-Module -ListAvailable Az

Se non viene visualizzato alcun elemento o se la versione del modulo di Azure PowerShell è precedente alla 5.1.0, seguire le istruzioni in Installare il modulo Azure PowerShell per eseguire l'aggiornamento.

Eseguire quindi Connect-AzAccount per creare una connessione con 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

Creare l'oggetto di configurazione di Speech SDK

Con un token di accesso di Microsoft Entra è ora possibile creare un oggetto di configurazione di Speech SDK.

Il metodo per fornire il token e il metodo per costruire l'oggetto Config di Speech SDK corrispondente variano in base all'oggetto usato.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

Per gli oggetti SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber, creare il token di autorizzazione dall'ID della risorsa e dal token di accesso di Microsoft Entra e quindi usarlo per creare un oggetto 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

Per TranslationRecognizer, creare il token di autorizzazione dall'ID della risorsa e dal token di accesso di Microsoft Entra e quindi usarlo per creare un oggetto 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

Per usare VoiceProfileClient l’autenticazione di Microsoft Entra, usare il nome di dominio personalizzato creato in precedenza.

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

VoiceProfileClient non è disponibile con Speech SDK per Python.

Nota

ConversationTranslator non supporta l'autenticazione di Microsoft Entra.

Condividi tramite

Autenticazione di Microsoft Entra con Speech SDK

Creare una risorsa Voce

Configurare la risorsa Voce per l'autenticazione di Microsoft Entra

Creare un nome di dominio personalizzato

Verificare che un nome di dominio personalizzato sia disponibile

Creare il nome di dominio personalizzato

Prerequisiti

Verificare che il nome di dominio personalizzato sia disponibile

Attivare un nome di dominio personalizzato

Assegnazione di ruoli

Ottenere un token di accesso di Microsoft Entra

Ottenere l'ID della risorsa Voce

Creare l'oggetto di configurazione di Speech SDK

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

TranslationRecognizer

VoiceProfileClient

Commenti e suggerimenti

Risorse aggiuntive