Microsoft Entra authentication with the Speech SDK

Article
09/20/2024

When using the Speech SDK to access the Speech service, there are three authentication methods available: service keys, a key-based token, and Microsoft Entra ID. This article describes how to configure a Speech resource and create a Speech SDK configuration object to use Microsoft Entra ID for authentication.

This article shows how to use Microsoft Entra authentication with the Speech SDK. You learn how to:

Create a Speech resource
Configure the Speech resource for Microsoft Entra authentication
Get a Microsoft Entra access token
Create the appropriate SDK configuration object.

To learn more about Microsoft Entra access tokens, including token lifetime, visit Access tokens in the Microsoft identity platform.

Create a Speech resource

To create a Speech resource in the Azure portal, see this quickstart.

Configure the Speech resource for Microsoft Entra authentication

To configure your Speech resource for Microsoft Entra authentication, create a custom domain name and assign roles.

Create a custom domain name

Follow these steps to create a custom subdomain name for Azure AI services for your Speech resource.

Caution

When you turn on a custom domain name, the operation is not reversible. The only way to go back to the regional name is to create a new Speech resource.

If your Speech resource has a lot of associated custom models and projects created via Speech Studio, we strongly recommend trying the configuration with a test resource before you modify the resource used in production.

To create a custom domain name using the Azure portal, follow these steps:

Go to the Azure portal and sign in to your Azure account.
Select the required Speech resource.
In the Resource Management group on the left pane, select Networking.
On the Firewalls and virtual networks tab, select Generate Custom Domain Name. A new right panel appears with instructions to create a unique custom subdomain for your resource.
In the Generate Custom Domain Name panel, enter a custom domain name. Your full custom domain will look like: https://{your custom name}.cognitiveservices.azure.cn.

Remember that after you create a custom domain name, it cannot be changed.

After you've entered your custom domain name, select Save.
After the operation finishes, in the Resource management group, select Keys and Endpoint. Confirm that the new endpoint name of your resource starts this way: https://{your custom name}.cognitiveservices.azure.cn.

To create a custom domain name by using PowerShell, confirm that your computer has PowerShell version 7.x or later with the Azure PowerShell module version 5.1.0 or later. To see the versions of these tools, follow these steps:

In a PowerShell window, enter:

$PSVersionTable

Confirm that the PSVersion value is 7.x or later. To upgrade PowerShell, follow the instructions at Installing various versions of PowerShell.
In a PowerShell window, enter:

Get-Module -ListAvailable Az

If nothing appears, or if that version of the Azure PowerShell module is earlier than 5.1.0, follow the instructions at Install the Azure PowerShell module to upgrade.

Before you proceed, run Connect-AzAccount -Environment AzureChinaCloud to create a connection with Azure.

Verify that a custom domain name is available

Check whether the custom domain that you want to use is available. The following code confirms that the domain is available by using the Check Domain Availability operation in the Azure AI services REST API.

$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.chinacloudapi.cn/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

If the desired name is available, you'll see a response like this:

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

If the name is already taken, then you'll see the following response:

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

Create your custom domain name

To turn on a custom domain name for the selected Speech resource, use the Set-AzCognitiveServicesAccount cmdlet.

Caution

After the following code runs successfully, you'll create a custom domain name for your Speech resource. Remember that this name cannot be changed.

$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

Prerequisites

If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.
- If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.
- When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.
- Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

This section requires the latest version of the Azure CLI.

Verify that the custom domain name is available

Check whether the custom domain that you want to use is free. Use the Check Domain Availability method from the Azure AI services REST API.

Copy the following code block, insert your preferred custom domain name, and save to the file subdomain.json.

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

Run the following command. Replace xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with your Azure subscription ID.

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

If the desired name is available, you'll see a response like this:

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

If the name is already taken, then you'll see the following response:

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

Turn on a custom domain name

To use a custom domain name with the selected Speech resource, use the az cognitiveservices account update command.

(If your Azure account has only one active subscription, you can skip this step.) Select the Azure subscription that contains the Speech resource. Replace xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with your Azure subscription ID.

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

Set the custom domain name to the selected resource. Replace the sample parameter values with the actual ones and run the following command.

Caution

After successful execution of the following command, you'll create a custom domain name for your Speech resource. Remember that this name cannot be changed.

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

Assign roles

For Microsoft Entra authentication with Speech resources, you need to assign either the Cognitive Services Speech Contributor or Cognitive Services Speech User role.

You can assign roles to the user or application using the Azure portal or PowerShell.

Get a Microsoft Entra access token

To get a Microsoft Entra access token in C#, use the Azure Identity Client Library.

Here's an example of using Azure Identity to get a Microsoft Entra access token from an interactive browser:

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

Note

The token context must be set to "https://cognitiveservices.azure.cn/.default".

To get a Microsoft Entra access token in C++, use the Azure Identity Client Library.

Here's an example of using Azure Identity to get a Microsoft Entra access token with your tenant ID, client ID, and client secret credentials:

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

Azure::Identity::DefaultAzureCredential();

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

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

Note

The token context must be set to "https://cognitiveservices.azure.cn/.default".

To get a Microsoft Entra access token in Java, use the Azure Identity Client Library.

Here's an example of using Azure Identity to get a Microsoft Entra access token from a browser:

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

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

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

Note

The token context must be set to "https://cognitiveservices.azure.cn/.default".

To get a Microsoft Entra access token in Python, use the Azure Identity Client Library.

Here's an example of using Azure Identity to get a Microsoft Entra access token from an interactive browser:

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

Find samples that get a Microsoft Entra access token in Microsoft identity platform code samples.

For programming languages where a Microsoft identity platform client library isn't available, you can directly request an access token.

Get the Speech resource ID

You need your Speech resource ID to make SDK calls using Microsoft Entra authentication.

Note

For Intent Recognition use your LUIS Prediction resource ID.

Azure portal
PowerShell

To get the resource ID in the Azure portal:

Go to the Azure portal and sign in to your Azure account.
Select a Speech resource.
In the Resource Management group on the left pane, select Properties.
Copy the Resource ID

To get the resource ID using PowerShell, confirm that you have PowerShell version 7.x or later with the Azure PowerShell module version 5.1.0 or later. To see the versions of these tools, follow these steps:

In a PowerShell window, enter:

$PSVersionTable

Confirm that the PSVersion value is 7.x or later. To upgrade PowerShell, follow the instructions at Installing various versions of PowerShell.
In a PowerShell window, enter:

Get-Module -ListAvailable Az

If nothing appears, or if that version of the Azure PowerShell module is earlier than 5.1.0, follow the instructions at Install the Azure PowerShell module to upgrade.

Now run Connect-AzAccount to create a connection with Azure.

Connect-AzAccount -Environment AzureChinaCloud
$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

Create the Speech SDK configuration object

With a Microsoft Entra access token, you can now create a Speech SDK configuration object.

The method of providing the token, and the method to construct the corresponding Speech SDK Config object varies by the object you're using.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

For SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber objects, build the authorization token from the resource ID and the Microsoft Entra access token and then use it to create a SpeechConfig object.

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

For the TranslationRecognizer, build the authorization token from the resource ID and the Microsoft Entra access token and then use it to create a SpeechTranslationConfig object.

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

To use the VoiceProfileClient with Microsoft Entra authentication, use the custom domain name created above.

string customDomainName = "Your Custom Name";
string hostName = $"https://{customDomainName}.cognitiveservices.azure.cn/";
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.cn/");

// 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.cn/";
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);

The VoiceProfileClient isn't available with the Speech SDK for Python.

Note

The ConversationTranslator doesn't support Microsoft Entra authentication.

Microsoft Entra authentication with the Speech SDK

Create a Speech resource

Configure the Speech resource for Microsoft Entra authentication

Create a custom domain name

Assign roles

Get a Microsoft Entra access token

Get the Speech resource ID

Create the Speech SDK configuration object

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

TranslationRecognizer

VoiceProfileClient

Additional resources