Microsoft Entra-Authentifizierung mit Speech SDK

Artikel
09/09/2024

Wenn Sie den Sprach-SDK für den Zugriff auf den Sprachdienst verwenden, stehen drei Authentifizierungsmethoden zur Verfügung: Dienstschlüssel, ein schlüsselbasiertes Token und Microsoft Entra ID. In diesem Artikel wird beschrieben, wie Sie eine Sprach-Ressource konfigurieren und ein Speech-SDK-Konfigurationsobjekt erstellen, um Microsoft Entra ID für die Authentifizierung zu verwenden.

In diesem Artikel erfahren Sie, wie Sie Microsoft Entra-Authentifizierung mit dem Speech-SDK verwenden. Folgendes wird vermittelt:

Erstellen einer Speech-Ressource
Konfigurieren der Speech-Ressource für die Microsoft Entra-Authentifizierung
Erhalten eines Microsoft Entra-Zugriffstokens
Erstellen Sie das entsprechende SDK-Konfigurationsobjekt.

Weitere Informationen zu Microsoft Entra-Zugriffstoken, einschließlich der Tokenlebensdauer, finden Sie unter Microsoft Identity Platform – Zugriffstoken.

Erstellen einer Speech-Ressource

Informationen zum Erstellen einer Speech-Ressource im Azure-Portal finden Sie in diesem Schnellstart.

Konfigurieren der Speech-Ressource für die Microsoft Entra-Authentifizierung

Um Ihre Speech-Ressource für Microsoft Entra-Authentifizierung zu konfigurieren, erstellen Sie einen benutzerdefinierten Domänennamen, und weisen Sie Rollen zu.

Erstellen eines benutzerdefinierten Domänennamens

Führen Sie diese Schritte aus, um einen benutzerdefinierten Unterdomänennamen für Azure KI Services für Ihre Speech-Ressource zu erstellen.

Achtung

Wenn Sie einen benutzerdefinierten Domänennamen aktivieren, kann der Vorgang nicht rückgängig gemacht werden. Sie können den regionalen Namen nur wiederherstellen, indem Sie eine neue Speech-Ressource erstellen.

Wenn Ihrer Speech-Ressource viele benutzerdefinierte Modelle und Projekte zugeordnet sind, die über Speech Studio erstellt wurden, wird dringend empfohlen, die Konfiguration mit einer Testressource auszuprobieren und Produktionsressourcen erst im Anschluss zu bearbeiten.

Befolgen Sie diese Schritte, um einen benutzerdefinierten Domänennamen im Azure-Portal zu erstellen:

Navigieren Sie zum Azure-Portal, und melden Sie sich bei Ihrem Azure-Konto an.
Wählen Sie die erforderliche Speech-Ressource aus.
Wählen Sie in der Gruppe Ressourcenverwaltung im linken Bereich die Option Netzwerk aus.
Wählen Sie auf der Registerkarte Firewalls und virtuelle Netzwerke die Option Benutzerdefinierten Domänennamen generieren aus. Dadurch wird rechts ein Panel mit Anweisungen zum Erstellen einer eindeutigen benutzerdefinierten Unterdomäne für Ihre Ressource geöffnet.
Geben Sie im Bereich Benutzerdefinierten Domänennamen generieren einen benutzerdefinierten Domänennamen ein. Ihre vollständige benutzerdefinierte Domäne sieht wie https://{your custom name}.cognitiveservices.azure.com aus.

Hinweis: Nachdem Sie einen benutzerdefinierten Domänennamen erstellt haben, kann dieser nicht mehr geändert werden.

Nachdem Sie Ihren benutzerdefinierten Domänennamen eingegeben haben, wählen Sie Speichern aus.
Nachdem der Vorgang abgeschlossen ist, wählen Sie in der Gruppe Ressourcenverwaltung die Option Schlüssel und Endpunkt aus. Vergewissern Sie sich, dass der neue Endpunktname Ihrer Ressource mit https://{your custom name}.cognitiveservices.azure.com beginnt.

Vergewissern Sie sich, dass auf Ihrem Computer PowerShell 7.x oder höher mit dem Azure PowerShell-Modul 5.1.0 oder höher installiert ist. Andernfalls können Sie keinen benutzerdefinierten Domänennamen mit PowerShell erstellen. Befolgen Sie diese Schritte, um die Versionen dieser Tools anzuzeigen:

Geben Sie in einem PowerShell-Fenster Folgendes ein:

$PSVersionTable

Überprüfen Sie, ob der Wert von PSVersion 7.x oder höher ist. Befolgen Sie die Anweisungen unter Installieren verschiedener Versionen von PowerShell, um ein Upgrade für PowerShell durchzuführen.
Geben Sie in einem PowerShell-Fenster Folgendes ein:

Get-Module -ListAvailable Az

Wenn nichts angezeigt wird oder die Version des Azure PowerShell-Moduls niedriger als 5.1.0 ist, befolgen Sie die Anweisungen unter installieren des Azure PowerShell-Moduls, um das Upgrade durchzuführen.

Bevor Sie fortfahren, führen Sie Connect-AzAccount aus, um eine Verbindung mit Azure herzustellen.

Vergewissern Sie sich, dass ein benutzerdefinierter Domänenname verfügbar ist

Überprüfen Sie die Verfügbarkeit der benutzerdefinierten Domäne, die Sie verwenden möchten. Der folgende Code überprüft mit der Methode checkDomainAvailability der Azure KI Services-REST-API, ob die Domäne verfügbar ist.

Hinweis

Dieser Code funktioniert nicht 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

Wenn der gewünschte Name verfügbar ist, wird eine Antwort wie diese angezeigt:

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

Wenn der Name bereits verwendet wird, wird die folgende Antwort angezeigt:

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

Erstellen Ihres benutzerdefinierten Domänennamens

Verwenden Sie das Cmdlet Set-AzCognitiveServicesAccount, um einen benutzerdefinierten Domänennamen für die ausgewählte Speech-Ressource zu aktivieren.

Achtung

Nach erfolgreicher Ausführung des folgenden Codes können Sie einen benutzerdefinierten Domänennamen für Ihre Speech-Ressource erstellen. Dieser Name kann jedoch nicht geändert werden.

$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

Voraussetzungen

Verwenden Sie die Bash-Umgebung in Azure Cloud Shell. Weitere Informationen finden Sie unter Schnellstart für Bash in Azure Cloud Shell.
Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI. Wenn Sie Windows oder macOS ausführen, sollten Sie die Azure CLI in einem Docker-Container ausführen. Weitere Informationen finden Sie unter Ausführen der Azure CLI in einem Docker-Container.
- Wenn Sie eine lokale Installation verwenden, melden Sie sich mithilfe des Befehls az login bei der Azure CLI an. Führen Sie die in Ihrem Terminal angezeigten Schritte aus, um den Authentifizierungsprozess abzuschließen. Informationen zu anderen Anmeldeoptionen finden Sie unter Anmelden mit der Azure CLI.
- Installieren Sie die Azure CLI-Erweiterung beim ersten Einsatz, wenn Sie dazu aufgefordert werden. Weitere Informationen zu Erweiterungen finden Sie unter Verwenden von Erweiterungen mit der Azure CLI.
- Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.

Für diesen Abschnitt ist die aktuelle Version der Azure CLI erforderlich. Bei Verwendung von Azure Cloud Shell ist die aktuelle Version bereits installiert.

Überprüfen der Verfügbarkeit des benutzerdefinierten Domänennamens

Überprüfen Sie die Verfügbarkeit der benutzerdefinierten Domäne, die Sie verwenden möchten. Verwenden Sie hierfür die checkDomainAvailability-Methode der Azure KI Services-REST-API.

Kopieren Sie den folgenden Codeblock, fügen Sie Ihren bevorzugten benutzerdefinierten Domänennamen ein, und speichern Sie ihn in der Datei subdomain.json.

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

Kopieren Sie die Datei in den aktuellen Ordner, oder laden Sie sie in Azure Cloud Shell hoch, und führen Sie den folgenden Befehl aus. Ersetzen Sie xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx durch Ihre Azure-Abonnement-ID.

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

Wenn der gewünschte Name verfügbar ist, wird eine Antwort wie diese angezeigt:

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

Wenn der Name bereits verwendet wird, wird die folgende Antwort angezeigt:

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

Aktivieren eines benutzerdefinierten Domänennamens

Verwenden Sie den Befehl az cognitiveservices account update, um einen benutzerdefinierten Domänennamen für die ausgewählte Speech-Ressource zu aktivieren.

(Wenn Ihr Azure-Konto nur über ein aktives Abonnement verfügt, können Sie diesen Schritt überspringen.) Wählen Sie das Azure-Abonnement aus, das die Sprachressource enthält. Ersetzen Sie xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx durch Ihre Azure-Abonnement-ID.

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

Legen Sie den benutzerdefinierten Domänennamen auf die ausgewählte Ressource fest. Ersetzen Sie die Beispielparameterwerte durch die tatsächlichen Parameterwerte, und führen Sie den folgenden Befehl aus.

Achtung

Nach erfolgreicher Ausführung des folgenden Befehls können Sie einen benutzerdefinierten Domänennamen für Ihre Speech-Ressource erstellen. Dieser Name kann jedoch nicht geändert werden.

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

Zuweisen von Rollen

Für die Microsoft Entra-Authentifizierung mit Sprachressourcen müssen Sie entweder die Rolle Cognitive Services Sprachmitwirkender oder Cognitive Services Sprachbenutzer zuweisen.

In demAzure-Portal oder PowerShellkönnen Sie dem Benutzer oder der Anwendung Rollen zuweisen.

Erhalten eines Microsoft Entra-Zugriffstokens

Verwenden Sie die Azure Identity Client Library, um ein Microsoft Entra-Zugriffstoken in C# abzurufen.

Hier finden Sie ein Beispiel für die Verwendung von Azure Identity zum Abrufen eines Microsoft Entra Zugriffstokens aus einem interaktiven 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;

Hinweis

Der Tokenkontext muss auf „https://cognitiveservices.azure.com/.default" festgelegt werden.

Verwenden Sie die Azure Identity Client Library, um ein Microsoft Entra-Zugriffstoken in C++ abzurufen.

Hier finden Sie ein Beispiel für die Verwendung von Azure Identity zum Abrufen eines Microsoft Entra-Zugriffstokens mit Ihrer Mandanten-ID, Client-ID und den Anmeldeinformationen Ihres geheimen Clientschlüssels:

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

Hinweis

Der Tokenkontext muss auf „https://cognitiveservices.azure.com/.default" festgelegt werden.

Verwenden Sie die Azure Identity Client Library, um ein Microsoft Entra-Zugriffstoken in Java abzurufen.

Hier finden Sie ein Beispiel für die Verwendung von Azure Identity zum Abrufen eines Microsoft Entra Zugriffstokens aus einem 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();

Hinweis

Der Tokenkontext muss auf „https://cognitiveservices.azure.com/.default" festgelegt werden.

Verwenden Sie die Azure Identity Client Library, um ein Microsoft Entra-Zugriffstoken in Python abzurufen.

Hier finden Sie ein Beispiel für die Verwendung von Azure Identity zum Abrufen eines Microsoft Entra Zugriffstokens aus einem interaktiven Browser:

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

Beispiele zum Abrufen eines Microsoft Entra Zugriffstokens finden Sie in Microsoft Identity Platform Codebeispielen.

Für Programmiersprachen, in Microsoft Identity Platform Clientbibliothek nicht verfügbar ist, können Sie direkt ein Zugriffstoken anfordern.

Erhalten der Sprachressourcen-ID

Sie benötigen Ihre Speech-Ressourcen-ID, um SDK-Aufrufe mithilfe Microsoft Entra-Authentifizierung tätigen zu können.

Hinweis

Für eine Sprechabsichtserkennung verwenden Sie Ihre LUIS-Vorhersage-Ressourcen-ID.

Azure portal
PowerShell

So erhalten Sie die Ressourcen-ID im Azure-Portal:

Navigieren Sie zum Azure-Portal, und melden Sie sich bei Ihrem Azure-Konto an.
Wählen Sie eine Sprachressource aus.
Wählen Sie in der Gruppe Ressourcenverwaltung im linken Bereich die Option Eigenschaften aus.
Kopieren Sie die Ressourcen-ID

Um die Ressourcen-ID mithilfe von PowerShell zu erhalten, vergewissern Sie sich, dass Sie über PowerShell-Version 7.x oder eine höhere Version mit der Azure PowerShell-Modulversion 5.1.0 oder einer höheren Version verfügen. Befolgen Sie diese Schritte, um die Versionen dieser Tools anzuzeigen:

Geben Sie in einem PowerShell-Fenster Folgendes ein:

$PSVersionTable

Überprüfen Sie, ob der Wert von PSVersion 7.x oder höher ist. Befolgen Sie die Anweisungen unter Installieren verschiedener Versionen von PowerShell, um ein Upgrade für PowerShell durchzuführen.
Geben Sie in einem PowerShell-Fenster Folgendes ein:

Get-Module -ListAvailable Az

Wenn nichts angezeigt wird oder die Version des Azure PowerShell-Moduls niedriger als 5.1.0 ist, befolgen Sie die Anweisungen unter installieren des Azure PowerShell-Moduls, um das Upgrade durchzuführen.

Führen Sie daraufhin zum Starten Connect-AzAccount aus, um eine Verbindung mit Azure herzustellen.

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

Erstellen des Sprach-SDK-Konfigurationsobjekts

Mit einem Microsoft Entra Zugriffstoken können Sie jetzt ein Speech-SDK-Konfigurationsobjekt erstellen.

Die Methode zum Bereitstellen des Tokens und die Methode zum Erstellen des entsprechenden Sprach-SDK-Objekts Config variieren je nach dem Objekt, das Sie verwenden.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

Erstellen Sie für Objekte vom Typ SpeechRecognizer, SpeechSynthesizer, IntentRecognizer und ConversationTranscriber das Autorisierungstoken aus der Ressourcen-ID und dem Microsoft Entra-Zugriffstoken, und verwenden Sie es dann, um ein SpeechConfig-Objekt zu erstellen.

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

Erstellen Sie für TranslationRecognizer das Autorisierungstoken aus der Ressourcen-ID und dem Microsoft Entra-Zugriffstoken, und verwenden Sie es dann, um ein SpeechTranslationConfig-Objekt zu erstellen.

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

Verwenden Sie den oben erstellten benutzerdefinierten Domänennamen, um VoiceProfileClient mit der Microsoft Entra-Authentifizierung zu verwenden.

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 ist nicht mit dem Sprach-SDK für Python verfügbar.

Hinweis

ConversationTranslator unterstützt die Microsoft Entra-Authentifizierung nicht.

Freigeben über

Microsoft Entra-Authentifizierung mit Speech SDK

Erstellen einer Speech-Ressource

Konfigurieren der Speech-Ressource für die Microsoft Entra-Authentifizierung

Erstellen eines benutzerdefinierten Domänennamens

Vergewissern Sie sich, dass ein benutzerdefinierter Domänenname verfügbar ist

Erstellen Ihres benutzerdefinierten Domänennamens

Voraussetzungen

Überprüfen der Verfügbarkeit des benutzerdefinierten Domänennamens

Aktivieren eines benutzerdefinierten Domänennamens

Zuweisen von Rollen

Erhalten eines Microsoft Entra-Zugriffstokens

Erhalten der Sprachressourcen-ID

Erstellen des Sprach-SDK-Konfigurationsobjekts

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

TranslationRecognizer

VoiceProfileClient

Feedback

Zusätzliche Ressourcen