Authentification Microsoft Entra avec le kit de développement logiciel (SDK) Speech

Article
09/03/2024

Lorsque vous utilisez le kit de développement logiciel (SDK) Speech pour accéder au service Speech, trois méthodes d’authentification sont disponibles : les clés de service, un jeton basé sur une clé et Microsoft Entra ID. Cet article explique comment configurer une ressource Speech et créer un objet de configuration du kit de développement logiciel (SDK) Speech afin d’utiliser Microsoft Entra ID pour l’authentification.

Cet article montre comment utiliser l’authentification Microsoft Entra avec le kit de développement logiciel (SDK) Speech. Vous allez apprendre à effectuer les actions suivantes :

Créer une ressource Speech
Configurer la ressource Speech pour l’authentification Microsoft Entra
Obtenir un jeton d’accès Microsoft Entra
Créer l’objet de configuration du SDK approprié

Pour en savoir plus sur les jetons d’accès Microsoft Entra, notamment leur durée de vie, consultez Jetons d’accès de la plateforme d’identités Microsoft.

Créer une ressource Speech

Pour créer une ressource Speech dans le Portail Azure, consultez ce démarrage rapide.

Configurer la ressource Speech pour l’authentification Microsoft Entra

Pour configurer votre ressource Speech pour l’authentification Microsoft Entra, créez un nom de domaine personnalisé et attribuez des rôles.

Créer un nom de domaine personnalisé

Effectuez ces étapes afin de créer un nom de sous-domaine personnalisé pour Azure AI Services pour votre ressource Speech.

Attention

Lorsque vous activez un nom de domaine personnalisé, l’opération n’est pas réversible. La seule façon de revenir au nom régional consiste à créer une ressource Speech.

Si votre ressource Speech comporte un grand nombre de modèles et de projets personnalisés associés créés avec Speech Studio, nous vous recommandons vivement d’essayer la configuration avec une ressource test avant de modifier la ressource utilisée en production.

Pour créer un nom de domaine personnalisé à l’aide du portail Azure, effectuez les étapes suivantes :

Accédez au portail Azure et connectez-vous à votre compte Azure.
Sélectionnez la ressource Speech requise.
Dans le groupe Gestion des ressources dans le volet gauche, sélectionnez Réseau.
Sous l’onglet Pare-feux et réseaux virtuels, sélectionnez Générer un nom de domaine personnalisé. Cela a pour effet d’ouvrir un nouveau panneau contenant des instructions pour créer un sous-domaine personnalisé unique pour votre ressource.
Dans le panneau Générer un nom de domaine personnalisé, entrez un nom de domaine personnalisé. Votre domaine personnalisé complet ressemble à ce qui suit : https://{your custom name}.cognitiveservices.azure.com.

N’oubliez pas : après avoir créé un nom de domaine personnalisé, vous ne pouvez plus le modifier.

Une fois que vous avez entré votre nom de domaine personnalisé, sélectionnez Enregistrer.
Quand l’opération est terminée, dans le groupe Gestion des ressources, sélectionnez Clés et point de terminaison. Confirmez que le nouveau nom de point de terminaison de votre ressource commence ainsi : https://{your custom name}.cognitiveservices.azure.com.

Pour créer un nom de domaine personnalisé avec PowerShell, vérifiez que votre ordinateur dispose de PowerShell version 7.x ou ultérieure avec le module Azure PowerShell version 5.1.0 ou ultérieure. Pour voir les versions de ces outils, procédez comme suit :

Dans une fenêtre PowerShell, entrez :

$PSVersionTable

Confirmez que la valeur PSVersion est 7.x ou une version ultérieure. Pour mettre à niveau PowerShell, suivez les instructions données dans Installation de plusieurs versions de PowerShell.
Dans une fenêtre PowerShell, entrez :

Get-Module -ListAvailable Az

Si rien ne s’affiche ou si la version du module Azure PowerShell affichée est antérieure à 5.1.0, suivez les instructions fournies dans Installer le module Azure PowerShell pour effectuer la mise à niveau.

Avant de poursuivre, exécutez Connect-AzAccount pour créer une connexion avec Azure.

Vérifier la disponibilité d’un nom de domaine personnalisé

Vérifiez si le domaine personnalisé que vous souhaitez utiliser est disponible. Le code suivant confirme que le domaine est disponible en exécutant l’opération Vérifier la disponibilité du domaine dans l’API REST Azure AI Services.

Remarque

Le code suivant ne fonctionne pas dans 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

Si le nom souhaité est disponible, vous obtenez une réponse similaire à celle-ci :

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

Si le nom est déjà utilisé, vous obtenez la réponse suivante :

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

Créer votre nom de domaine personnalisé

Pour activer un nom de domaine personnalisé pour la ressource Speech sélectionnée, utilisez l’applet de commande Set-AzCognitiveServicesAccount.

Attention

Une fois que le code suivant s’est exécuté correctement, vous allez créer un nom de domaine personnalisé pour votre ressource Speech. N’oubliez pas que ce nom n’est pas modifiable.

$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érequis

Utilisez l’environnement Bash dans Azure Cloud Shell. Pour plus d’informations, consultez Démarrage rapide pour Bash dans Azure Cloud Shell.
Si vous préférez exécuter les commandes de référence de l’interface de ligne de commande localement, installez l’interface Azure CLI. Si vous exécutez sur Windows ou macOS, envisagez d’exécuter Azure CLI dans un conteneur Docker. Pour plus d’informations, consultez Guide pratique pour exécuter Azure CLI dans un conteneur Docker.
- Si vous utilisez une installation locale, connectez-vous à Azure CLI à l’aide de la commande az login. Pour finir le processus d’authentification, suivez les étapes affichées dans votre terminal. Pour connaître les autres options de connexion, consultez Se connecter avec Azure CLI.
- Lorsque vous y êtes invité, installez l’extension Azure CLI lors de la première utilisation. Pour plus d’informations sur les extensions, consultez Utiliser des extensions avec Azure CLI.
- Exécutez az version pour rechercher la version et les bibliothèques dépendantes installées. Pour effectuer une mise à niveau vers la dernière version, exécutez az upgrade.

Cette section nécessite la dernière version d’Azure CLI. Si vous utilisez Azure Cloud Shell, sachez que la version la plus récente est déjà installée.

Vérifier la disponibilité du nom de domaine personnalisé

Vérifiez si le domaine personnalisé que vous souhaitez utiliser est disponible. Utilisez la méthode Vérifier la disponibilité du domaine de l’API REST Azure AI Services.

Copiez le bloc de code suivant, insérez le nom de domaine personnalisé de votre choix, puis enregistrez le tout dans le fichier subdomain.json.

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

Copiez le fichier dans votre dossier actif ou chargez-le dans Azure Cloud Shell et exécutez la commande suivante. Remplacez xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx par l’identifiant de votre abonnement 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

Si le nom souhaité est disponible, vous obtenez une réponse similaire à celle-ci :

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

Si le nom est déjà utilisé, vous obtenez la réponse suivante :

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

Activer un nom de domaine personnalisé

Pour utiliser un nom de domaine personnalisé avec la ressource Speech sélectionnée, utilisez la commande az cognitiveservices account update.

(Si votre compte Azure n’a qu’un seul abonnement actif, vous pouvez ignorer cette étape.) Sélectionnez l’abonnement Azure qui contient la ressource Speech. Remplacez xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx par l’identifiant de votre abonnement Azure.

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

Définissez le nom de domaine personnalisé pour la ressource sélectionnée. Remplacez les exemples de valeurs de paramètre par les valeurs réelles, puis exécutez la commande suivante.

Attention

Une fois que la commande suivante s’est exécutée correctement, vous allez créer un nom de domaine personnalisé pour votre ressource Speech. N’oubliez pas que ce nom n’est pas modifiable.

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

Attribuer des rôles

Pour l’authentification Microsoft Entra avec des ressources Speech, vous devez affecter le rôle de Contributeur Speech Azure Cognitive Services ou d’Utilisateur Speech Azure Cognitive Services.

Vous pouvez assigner des rôles à l’utilisateur ou à l’application à l’aide du portail Azure ou de PowerShell.

Obtenir un jeton d’accès Microsoft Entra

Pour obtenir un jeton d’accès Microsoft Entra dans C#, utilisez la Bibliothèque de client Azure Identity.

Voici un exemple d’utilisation d’Azure Identity pour obtenir un jeton d’accès Microsoft Entra à partir d’un navigateur interactif :

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;

Le contexte du jeton doit avoir la valeur "https://cognitiveservices.azure.com/.default".

Pour obtenir un jeton d’accès Microsoft Entra dans C++, utilisez la Bibliothèque de client Azure Identity.

Voici un exemple d’utilisation d’Azure Identity pour obtenir un jeton d’accès Microsoft Entra avec votre ID de locataire, ID client et les informations d’identification de la clé secrète client :

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

Le contexte du jeton doit avoir la valeur "https://cognitiveservices.azure.com/.default".

Pour obtenir un jeton d’accès Microsoft Entra dans Java, utilisez la Bibliothèque de client Azure Identity.

Voici un exemple d’utilisation d’Azure Identity pour obtenir un jeton d’accès Microsoft Entra à partir d’un navigateur :

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

Le contexte du jeton doit avoir la valeur "https://cognitiveservices.azure.com/.default".

Pour obtenir un jeton d’accès Microsoft Entra dans Python, utilisez la Bibliothèque de client Azure Identity.

Voici un exemple d’utilisation d’Azure Identity pour obtenir un jeton d’accès Microsoft Entra à partir d’un navigateur interactif :

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

Vous trouverez des exemples qui obtiennent un jeton d’accès Microsoft Entra dans Exemples de code pour la plateforme d’identités Microsoft.

Pour les langages de programmation dans lesquels aucune bibliothèque de client de plateforme d’identités Microsoft n’est disponible, vous pouvez demander directement un jeton d’accès.

Obtenir l’ID de ressource Speech

Vous avez besoin de votre ID de ressource Speech pour effectuer des appels de kit de développement logiciel (SDK) à l’aide de l’authentification Microsoft Entra.

Remarque

Pour Reconnaissance de l’intention, utilisez votre ID de ressource de prédiction LUIS.

Azure portal
PowerShell

Pour récupérer l’ID de ressource dans le portail Azure :

Accédez au portail Azure et connectez-vous à votre compte Azure.
Sélectionnez une ressource Speech.
Dans le groupe Gestion des ressources dans le volet gauche, sélectionnez Propriétés.
Copiez l’ID de ressource.

Pour obtenir l’ID de ressource à l’aide de PowerShell, vérifiez que vous disposez de PowerShell version 7.x ou ultérieure avec le module Azure PowerShell version 5.1.0 ou ultérieure. Pour voir les versions de ces outils, procédez comme suit :

Dans une fenêtre PowerShell, entrez :

$PSVersionTable

Confirmez que la valeur PSVersion est 7.x ou une version ultérieure. Pour mettre à niveau PowerShell, suivez les instructions données dans Installation de plusieurs versions de PowerShell.
Dans une fenêtre PowerShell, entrez :

Get-Module -ListAvailable Az

Si rien ne s’affiche ou si la version du module Azure PowerShell affichée est antérieure à 5.1.0, suivez les instructions fournies dans Installer le module Azure PowerShell pour effectuer la mise à niveau.

Maintenant, exécutez Connect-AzAccount pour créer une connexion avec 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

Créer l’objet de configuration du SDK Speech

Avec un jeton d’accès Microsoft Entra, vous pouvez désormais créer un objet de configuration du kit de développement logiciel (SDK) Speech.

La méthode de fourniture du jeton, ainsi que la méthode permettant de construire l’objet Config du Kit de développement logiciel (SDK) Speech correspondant, varient en fonction de l’objet que vous utilisez.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

Pour les objets SpeechRecognizer, SpeechSynthesizer, IntentRecognizer et ConversationTranscriber, générez le jeton d’autorisation à partir de l’ID de ressource et du jeton d’accès Microsoft Entra, puis utilisez-le pour créer un objet SpeechConfig.

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

Pour TranslationRecognizer, générez le jeton d’autorisation à partir de l’ID de ressource et du jeton d’accès Microsoft Entra, puis utilisez-le pour créer un objet SpeechTranslationConfig.

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

Pour l’objet DialogServiceConnection, générez le jeton d’autorisation à partir de l’ID de ressource et du jeton d’accès Microsoft Entra, puis utilisez-le pour créer un objet CustomCommandsConfig ou BotFrameworkConfig.

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 n’est actuellement pas pris en charge en Python

VoiceProfileClient

Pour utiliser VoiceProfileClient avec l’authentification Microsoft Entra, utilisez le nom de domaine personnalisé créé ci-dessus.

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

VoiceProfileClient n’est pas disponible avec le SDK Speech pour Python.

Remarque

ConversationTranslator ne prend pas en charge l’authentification Microsoft Entra.

Partager via

Authentification Microsoft Entra avec le kit de développement logiciel (SDK) Speech

Créer une ressource Speech

Configurer la ressource Speech pour l’authentification Microsoft Entra

Créer un nom de domaine personnalisé

Vérifier la disponibilité d’un nom de domaine personnalisé

Créer votre nom de domaine personnalisé

Prérequis

Vérifier la disponibilité du nom de domaine personnalisé

Activer un nom de domaine personnalisé

Attribuer des rôles

Obtenir un jeton d’accès Microsoft Entra

Obtenir l’ID de ressource Speech

Créer l’objet de configuration du SDK Speech

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

TranslationRecognizer

DialogServiceConnector

VoiceProfileClient

Commentaires

Ressources supplémentaires