Azure Active Directory Authentication with the Speech SDK

When using the Speech SDK to access the Speech service, there are three authentication methods available: service keys, a key-based token, and Azure Active Directory (Azure AD). This article describes how to configure a Speech resource and create a Speech SDK configuration object to use Azure AD for authentication.

This article shows how to use Azure AD authentication with the Speech SDK. You'll learn how to:

• Create a Speech resource
• Configure the Speech resource for Azure AD authentication
• Get an Azure AD access token
• Create the appropriate SDK configuration object.

To learn more about Azure AD 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 Get the keys for your resource

Configure the Speech resource for Azure AD authentication

To configure your Speech resource for Azure AD 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.

Azure portal

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

1. Go to the Azure portal and sign in to your Azure account.

2. Select the required Speech resource.

3. In the Resource Management group on the left pane, select Networking.

4. 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.

5. 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.com.

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

   After you've entered your custom domain name, select Save.

6. 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.com.

PowerShell

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:

1. 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.

2. 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 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.

Note

The following code will not work 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

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

Azure CLI

Prerequisites

• Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

  

• 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. If you're using Azure Cloud Shell, the latest version is already installed.

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"
}

Copy the file to your current folder or upload it to Azure Cloud Shell and run the following command. Replace xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with your Azure subscription 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

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 Azure AD 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 an Azure AD access token

To get an Azure AD access token in C#, use the Azure Identity Client Library.

Here's an example of using Azure Identity to get an Azure AD access token from an interactive 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;

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

To get an Azure AD access token in C++, use the Azure Identity Client Library.

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

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

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

To get an Azure AD access token in Java, use the Azure Identity Client Library.

Here's an example of using Azure Identity to get an Azure AD access token from a 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();

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

To get an Azure AD access token in Java, use the Azure Identity Client Library.

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

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

Find samples that get an Azure AD 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 Azure AD authentication.

Note

For Intent Recognition use your LUIS Prediction resource ID.

Azure portal

To get the resource ID in the Azure portal:

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

PowerShell

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:

1. 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.

2. 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
$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 an Azure AD 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'll be using.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

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

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

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

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

For the DialogServiceConnection object, build the authorization token from the resource ID and the Azure AD access token and then use it to create a CustomCommandsConfig or a BotFrameworkConfig object.

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

The DialogServiceConnector is not currently supported in Python

VoiceProfileClient

To use the VoiceProfileClient with Azure AD authentication, use the custom domain name created above.

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

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

Note

The ConversationTranslator doesn't support Azure AD authentication.