Microsoft Entra-verificatie met de Speech SDK

Wanneer u de Speech SDK gebruikt voor toegang tot de Speech-service, zijn er drie verificatiemethoden beschikbaar: servicesleutels, een sleuteltoken en Microsoft Entra-id. In dit artikel wordt beschreven hoe u een Speech-resource configureert en een Speech SDK-configuratieobject maakt voor het gebruik van Microsoft Entra ID voor verificatie.

In dit artikel wordt beschreven hoe u Microsoft Entra-verificatie gebruikt met de Speech SDK. U leert het volgende:

• Een spraakresource maken
• De Spraak-resource configureren voor Microsoft Entra-verificatie
• Een Microsoft Entra-toegangstoken ophalen
• Maak het juiste SDK-configuratieobject.

Voor meer informatie over Microsoft Entra-toegangstokens, inclusief levensduur van tokens, gaat u naar Access-tokens in het Microsoft Identity Platform.

Een spraakresource maken

Als u een Spraak-resource wilt maken in Azure Portal, raadpleegt u De sleutels voor uw resource ophalen

De Spraak-resource configureren voor Microsoft Entra-verificatie

Als u uw Spraak-resource voor Microsoft Entra-verificatie wilt configureren, maakt u een aangepaste domeinnaam en wijst u rollen toe.

Een aangepaste domeinnaam maken

Volg deze stappen om een aangepaste subdomeinnaam te maken voor Azure AI-services voor uw Speech-resource.

Let op

Wanneer u een aangepaste domeinnaam inschakelt, is de bewerking niet omkeerbaar. De enige manier om terug te gaan naar de regionale naam is door een nieuwe Spraak-resource te maken.

Als uw Speech-resource veel aangepaste modellen en projecten bevat die zijn gemaakt via Speech Studio, raden we u ten zeerste aan om de configuratie uit te voeren met een testresource voordat u de resource die in productie wordt gebruikt, wijzigt.

Azure-portal

Voer de volgende stappen uit om een aangepaste domeinnaam te maken met behulp van Azure Portal:

1. Ga naar Azure Portal en meld u aan bij uw account.

2. Selecteer de vereiste spraakresource.

3. Selecteer Netwerken in de groep Resourcebeheer in het linkerdeelvenster.

4. Selecteer Op het tabblad Firewalls en virtuele netwerken de optie Aangepaste domeinnaam genereren. Er wordt een nieuw rechterdeelvenster weergegeven met instructies voor het maken van een uniek aangepast subdomein voor uw resource.

5. Voer in het deelvenster Aangepaste domeinnaam genereren een aangepaste domeinnaam in. Uw volledige aangepaste domein ziet er als volgt uit: https://{your custom name}.cognitiveservices.azure.com.

   Nadat u een aangepaste domeinnaam hebt gemaakt, kan deze niet meer worden gewijzigd.

   Nadat u uw aangepaste domeinnaam hebt ingevoerd, selecteert u Opslaan.

6. Nadat de bewerking is voltooid, selecteert u sleutels en eindpunt in de resourcebeheergroep. Controleer of de naam van het nieuwe eindpunt van uw resource op deze manier wordt gestart: https://{your custom name}.cognitiveservices.azure.com.

PowerShell

Als u een aangepaste domeinnaam wilt maken met behulp van PowerShell, controleert u of uw computer PowerShell versie 7.x of hoger heeft met de Azure PowerShell-module versie 5.1.0 of hoger. Voer de volgende stappen uit om de versies van deze hulpprogramma's te bekijken:

1. Voer in een PowerShell-venster het volgende in:

   $PSVersionTable

   Controleer of de PSVersion waarde 7.x of hoger is. Als u PowerShell wilt upgraden, volgt u de instructies bij het installeren van verschillende versies van PowerShell.

2. Voer in een PowerShell-venster het volgende in:

   Get-Module -ListAvailable Az

   Als er niets wordt weergegeven of als die versie van de Azure PowerShell-module ouder is dan 5.1.0, volgt u de instructies bij Het installeren van de Azure PowerShell-module om een upgrade uit te voeren .

Voordat u verdergaat, voert u de opdracht uit Connect-AzAccount om een verbinding met Azure te maken.

Controleer of er een aangepaste domeinnaam beschikbaar is

Controleer of het aangepaste domein dat u wilt gebruiken beschikbaar is. Met de volgende code wordt bevestigd dat het domein beschikbaar is met behulp van de bewerking Domein beschikbaarheid controleren in de REST API van Azure AI-services.

Notitie

De volgende code werkt niet 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

Als de gewenste naam beschikbaar is, ziet u een antwoord als volgt:

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

Als de naam al is gebruikt, ziet u het volgende antwoord:

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

Uw aangepaste domeinnaam maken

Als u een aangepaste domeinnaam wilt inschakelen voor de geselecteerde Speech-resource, gebruikt u de cmdlet Set-AzCognitiveServicesAccount .

Let op

Nadat de volgende code is uitgevoerd, maakt u een aangepaste domeinnaam voor uw Speech-resource. Houd er rekening mee dat deze naam niet kan worden gewijzigd.

$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

Azure-CLI

Vereisten

• Gebruik de Bash-omgeving in Azure Cloud Shell. Zie quickstart voor Bash in Azure Cloud Shell voor meer informatie.

  

• Installeer de Azure CLI, indien gewenst, om CLI-referentieopdrachten uit te voeren. Als u in Windows of macOS werkt, kunt u Azure CLI uitvoeren in een Docker-container. Zie De Azure CLI uitvoeren in een Docker-container voor meer informatie.

  • Als u een lokale installatie gebruikt, meldt u zich aan bij Azure CLI met behulp van de opdracht az login. Volg de stappen die worden weergegeven in de terminal, om het verificatieproces te voltooien. Raadpleeg Aanmelden bij Azure CLI voor aanvullende aanmeldingsopties.

  • Installeer de Azure CLI-extensie bij het eerste gebruik, wanneer u hierom wordt gevraagd. Raadpleeg Extensies gebruiken met Azure CLI voor meer informatie over extensies.

  • Voer az version uit om de geïnstalleerde versie en afhankelijke bibliotheken te vinden. Voer az upgrade uit om te upgraden naar de nieuwste versie.

Voor deze sectie is de nieuwste versie van de Azure CLI vereist. Als u Azure Cloud Shell gebruikt, is de nieuwste versie al geïnstalleerd.

Controleer of de aangepaste domeinnaam beschikbaar is

Controleer of het aangepaste domein dat u wilt gebruiken, gratis is. Gebruik de methode Beschikbaarheid van domein controleren vanuit de REST API van Azure AI-services.

Kopieer het volgende codeblok, voeg de gewenste aangepaste domeinnaam in en sla het bestand subdomain.jsonop.

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

Kopieer het bestand naar uw huidige map of upload het naar Azure Cloud Shell en voer de volgende opdracht uit. Vervang xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx door de id van uw Azure-abonnement.

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

Als de gewenste naam beschikbaar is, ziet u een antwoord als volgt:

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

Als de naam al is gebruikt, ziet u het volgende antwoord:

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

Een aangepaste domeinnaam inschakelen

Als u een aangepaste domeinnaam wilt gebruiken met de geselecteerde Speech-resource, gebruikt u de opdracht az cognitiveservices account update .

(Als uw Azure-account slechts één actief abonnement heeft, kunt u deze stap overslaan.) Selecteer het Azure-abonnement dat de Speech-resource bevat. Vervang xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx door de id van uw Azure-abonnement.

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

Stel de aangepaste domeinnaam in op de geselecteerde resource. Vervang de voorbeeldparameterwaarden door de werkelijke waarden en voer de volgende opdracht uit.

Let op

Nadat de volgende opdracht is uitgevoerd, maakt u een aangepaste domeinnaam voor uw Spraak-resource. Houd er rekening mee dat deze naam niet kan worden gewijzigd.

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

Rollen toewijzen

Voor Microsoft Entra-verificatie met Spraakresources moet u de rol Cognitive Services Speech Contributor of Cognitive Services Speech User toewijzen.

U kunt rollen toewijzen aan de gebruiker of toepassing met behulp van Azure Portal of PowerShell.

Een Microsoft Entra-toegangstoken ophalen

Als u een Microsoft Entra-toegangstoken in C# wilt ophalen, gebruikt u de Azure Identity-clientbibliotheek.

Hier volgt een voorbeeld van het gebruik van Azure Identity om een Microsoft Entra-toegangstoken op te halen vanuit een interactieve browser:

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;

De tokencontext moet worden ingesteld op 'https://cognitiveservices.azure.com/.default".

Als u een Microsoft Entra-toegangstoken in C++wilt ophalen, gebruikt u de Azure Identity-clientbibliotheek.

Hier volgt een voorbeeld van het gebruik van Azure Identity om een Microsoft Entra-toegangstoken op te halen met uw tenant-id, client-id en referenties voor clientgeheimen:

const std::string tenantId = "Your Tenant ID";
const std::string clientId = "Your Client ID";
const std::string clientSecret = "Your Client Secret";
const std::string tokenContext = "https://cognitiveservices.azure.com/.default";

Azure::Identity::ClientSecretCredential cred(tenantId,
    clientId,
    clientSecret,
    Azure::Identity::ClientSecretCredentialOptions());

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

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

De tokencontext moet worden ingesteld op 'https://cognitiveservices.azure.com/.default".

Als u een Microsoft Entra-toegangstoken in Java wilt ophalen, gebruikt u de Azure Identity-clientbibliotheek.

Hier volgt een voorbeeld van het gebruik van Azure Identity om een Microsoft Entra-toegangstoken op te halen vanuit een 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();

De tokencontext moet worden ingesteld op 'https://cognitiveservices.azure.com/.default".

Gebruik de Azure Identity-clientbibliotheek om een Microsoft Entra-toegangstoken in Python op te halen.

Hier volgt een voorbeeld van het gebruik van Azure Identity om een Microsoft Entra-toegangstoken op te halen vanuit een interactieve browser:

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

Zoek voorbeelden die een Microsoft Entra-toegangstoken ophalen in codevoorbeelden van het Microsoft Identity Platform.

Voor programmeertalen waar een Clientbibliotheek van Microsoft Identity Platform niet beschikbaar is, kunt u rechtstreeks een toegangstoken aanvragen.

De spraakresource-id ophalen

U hebt uw Spraak-resource-id nodig om SDK-aanroepen te doen met behulp van Microsoft Entra-verificatie.

Notitie

Voor intentieherkenning gebruikt u uw LUIS-voorspellingsresource-id.

Azure-portal

De resource-id ophalen in Azure Portal:

1. Ga naar Azure Portal en meld u aan bij uw account.
2. Selecteer een spraakresource.
3. Selecteer Eigenschappen in de groep Resourcebeheer in het linkerdeelvenster.
4. De resource-id kopiëren

PowerShell

Als u de resource-id wilt ophalen met PowerShell, controleert u of u PowerShell versie 7.x of hoger hebt met de Azure PowerShell-module versie 5.1.0 of hoger. Voer de volgende stappen uit om de versies van deze hulpprogramma's te bekijken:

1. Voer in een PowerShell-venster het volgende in:

   $PSVersionTable

   Controleer of de PSVersion waarde 7.x of hoger is. Als u PowerShell wilt upgraden, volgt u de instructies bij het installeren van verschillende versies van PowerShell.

2. Voer in een PowerShell-venster het volgende in:

   Get-Module -ListAvailable Az

   Als er niets wordt weergegeven of als die versie van de Azure PowerShell-module ouder is dan 5.1.0, volgt u de instructies bij Het installeren van de Azure PowerShell-module om een upgrade uit te voeren .

Voer nu uit Connect-AzAccount om een verbinding met Azure te maken.

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

Het Speech SDK-configuratieobject maken

Met een Microsoft Entra-toegangstoken kunt u nu een Speech SDK-configuratieobject maken.

De methode voor het opgegeven token en de methode voor het maken van het bijbehorende Speech SDK-object Config verschilt per object dat u gebruikt.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

Voor SpeechRecognizer, SpeechSynthesizer, IntentRecognizerConversationTranscriber objecten, bouwt u het autorisatietoken op basis van de resource-id en het Microsoft Entra-toegangstoken en gebruikt u het vervolgens om een SpeechConfig object te maken.

string resourceId = "Your Resource ID";
string aadToken = "Your Azure AD access token";
string region =  "Your Speech Region";

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

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

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and AAD 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 AAD 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 AAD access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
speechConfig = SpeechConfig(auth_token=authorizationToken, region=region)

TranslationRecognizer

Bouw voor het TranslationRecognizerautorisatietoken het autorisatietoken op basis van de resource-id en het Microsoft Entra-toegangstoken en gebruik het vervolgens om een SpeechTranslationConfig object te maken.

string resourceId = "Your Resource ID";
string aadToken = "Your Azure AD access token";
string region =  "Your Speech Region";

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

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

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and AAD 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 AAD 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 AAD access token.
authorizationToken = "aad#" + resourceId + "#" + aadToken.token
translationConfig = SpeechTranslationConfig(auth_token=authorizationToken, region=region)

DialogServiceConnector

Bouw voor het DialogServiceConnection object het autorisatietoken op basis van de resource-id en het Microsoft Entra-toegangstoken en gebruik het vervolgens om een CustomCommandsConfig of een BotFrameworkConfig object te maken.

string resourceId = "Your Resource ID";
string aadToken = "Your Azure AD access token";
string region =  "Your Speech Region";
string appId = "Your app ID";

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

std::string resourceId = "Your Resource ID";
std::string aadToken = "Your Azure AD access token";
std::string region = "Your Speech Region";
std::string appId = "Your app Id";

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

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

// You need to include the "aad#" prefix and the "#" (hash) separator between resource ID and AAD access token.
String authorizationToken = "aad#" + resourceId + "#" + token;
CustomCommandsConfig dialogServiceConfig = CustomCommandsConfig.fromAuthorizationToken(appId, authorizationToken, region);

DialogServiceConnector wordt momenteel niet ondersteund in Python

VoiceProfileClient

Als u de VoiceProfileClient verificatie met Microsoft Entra wilt gebruiken, gebruikt u de aangepaste domeinnaam die hierboven is gemaakt.

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

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

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

std::string customDomainName = "Your Custom Name";
std::string aadToken = "Your Azure AD 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 AAD access token.
auto authorizationToken = "aad#" + resourceId + "#" + aadToken;
speechConfig->SetAuthorizationToken(authorizationToken);

String aadToken = "Your Azure AD 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 AAD access token.
String authorizationToken = "aad#" + resourceId + "#" + token;

speechConfig.setAuthorizationToken(authorizationToken);

De VoiceProfileClient is niet beschikbaar met de Speech SDK voor Python.

Notitie

Microsoft ConversationTranslator Entra-verificatie wordt niet ondersteund.