Autentikasi Microsoft Entra dengan Speech SDK

Saat menggunakan Speech SDK untuk mengakses layanan Ucapan, ada tiga metode autentikasi yang tersedia: kunci layanan, token berbasis kunci, dan ID Microsoft Entra. Artikel ini menjelaskan cara mengonfigurasi sumber daya Ucapan dan membuat objek konfigurasi Speech SDK untuk menggunakan ID Microsoft Entra untuk autentikasi.

Artikel ini memperlihatkan cara menggunakan autentikasi Microsoft Entra dengan Speech SDK. Anda akan mempelajari cara untuk:

• Membuat sumber daya Ucapan
• Mengonfigurasi sumber daya Ucapan untuk autentikasi Microsoft Entra
• Mendapatkan token akses Microsoft Entra
• Buat objek konfigurasi SDK yang sesuai.

Untuk mempelajari selengkapnya tentang token akses Microsoft Entra, termasuk masa pakai token, kunjungi Token akses di platform identitas Microsoft.

Membuat sumber daya Ucapan

Untuk membuat sumber daya Ucapan di portal Microsoft Azure, lihat Mendapatkan kunci untuk sumber daya Anda

Mengonfigurasi sumber daya Ucapan untuk autentikasi Microsoft Entra

Untuk mengonfigurasi sumber daya Ucapan Anda untuk autentikasi Microsoft Entra, buat nama domain kustom dan tetapkan peran.

Buat nama domain kustom

Ikuti langkah-langkah ini untuk membuat nama subdomain kustom untuk layanan Azure AI untuk sumber daya Ucapan Anda.

Perhatian

Saat Anda mengaktifkan nama domain kustom, operasi tersebut tidak dapat dibatalkan. Satu-satunya cara untuk kembali ke nama regional adalah dengan membuat sumber Ucapan baru.

Jika sumber daya Ucapan Anda memiliki banyak model dan proyek kustom terkait yang dibuat melalui Speech Studio, sebaiknya coba konfigurasi dengan sumber daya pengujian sebelum Anda mengubah sumber daya yang digunakan dalam produksi.

Portal Azure

Untuk membuat nama domain kustom dengan menggunakan portal Azure, ikuti langkah-langkah berikut:

1. Buka portal Azure dan masuk ke akun Azure Anda.

2. Pilih sumber Ucapan yang diperlukan.

3. Di grup Pengelolaan Sumber Daya di panel kiri, pilih Jaringan.

4. Pada tab Firewalls dan jaringan virtual, pilih Buat Nama Domain Kustom. Panel kanan baru muncul dengan petunjuk untuk membuat subdomain kustom yang unik untuk sumber daya Anda.

5. Di panel Buat Nama Domain Kustom, masukkan nama domain kustom. Domain kustom lengkap Anda akan terlihat seperti: https://{your custom name}.cognitiveservices.azure.com.

   Ingatlah bahwa setelah Anda membuat nama domain kustom, nama itu tidak dapat diubah.

   Setelah Anda memasukkan nama domain kustom, pilih Simpan.

6. Setelah operasi selesai, dalam grup Pengelolaan sumber daya, pilih Kunci dan Titik Akhir. Konfirmasikan bahwa nama titik akhir baru sumber daya Anda dimulai dengan cara ini: https://{your custom name}.cognitiveservices.azure.com.

PowerShell

Untuk membuat nama domain kustom dengan menggunakan PowerShell, konfirmasikan bahwa komputer Anda memiliki PowerShell versi 7.x atau yang lebih baru dengan modul Azure PowerShell versi 5.1.0 atau yang lebih baru. Untuk melihat versi alat ini, ikuti langkah-langkah berikut:

1. Di jendela PowerShell, masukkan:

   $PSVersionTable

   Konfirmasikan bahwa nilai PSVersion adalah 7.x atau lebih baru. Untuk meningkatkan versi PowerShell, ikuti petunjuk di Memasang berbagai versi PowerShell.

2. Di jendela PowerShell, masukkan:

   Get-Module -ListAvailable Az

   Jika tidak ada yang muncul, atau jika versi modul Azure PowerShell lebih awal dari 5.1.0, ikuti petunjuk di Memasang modul Azure PowerShell untuk meningkatkan.

Sebelum Anda melanjutkan, jalankan Connect-AzAccount untuk membuat sambungan dengan Azure.

Verifikasi bahwa nama domain kustom tersedia

Periksa apakah domain kustom yang ingin Anda gunakan tersedia. Kode berikut mengonfirmasi bahwa domain tersedia dengan menggunakan operasi Periksa Ketersediaan Domain di REST API layanan Azure AI.

Catatan

Kode berikut tidak akan berfungsi di 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

Jika nama yang diinginkan tersedia, Anda akan melihat respons seperti ini:

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

Jika nama sudah diambil, maka Anda akan melihat respons berikut:

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

Buat nama domain kustom Anda

Untuk mengaktifkan nama domain kustom untuk sumber daya Ucapan yang dipilih, gunakan cmdlet Set-AzCognitiveServicesAccount.

Perhatian

Setelah kode berikut berhasil dijalankan, Anda akan membuat nama domain kustom untuk sumber daya Ucapan Anda. Ingatlah bahwa nama ini tidak dapat diubah.

$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

Prasyarat

• Gunakan lingkungan Bash di Azure Cloud Shell. Untuk informasi selengkapnya, lihat Mulai Cepat untuk Bash di Azure Cloud Shell.

  

• Jika Anda lebih suka menjalankan perintah referensi CLI secara lokal, instal Azure CLI. Jika Anda menjalankan Windows atau macOS, pertimbangkan untuk menjalankan Azure CLI dalam kontainer Docker. Untuk informasi lebih lanjut, lihat Cara menjalankan Azure CLI di kontainer Docker.

  • Jika Anda menggunakan instalasi lokal, masuk ke Azure CLI dengan menggunakan perintah login az. Untuk menyelesaikan proses autentikasi, ikuti langkah-langkah yang ditampilkan di terminal Anda. Untuk opsi masuk lainnya, lihat Masuk dengan Azure CLI.

  • Saat Anda diminta, instal ekstensi Azure CLI pada penggunaan pertama. Untuk informasi selengkapnya tentang ekstensi, lihat Menggunakan ekstensi dengan Azure CLI.

  • Jalankan versi az untuk menemukan versi dan pustaka dependen yang diinstal. Untuk meningkatkan ke versi terbaru, jalankan peningkatan az.

Artikel ini memerlukan Azure CLI versi terbaru. Jika menggunakan Azure Cloud Shell, versi terbaru sudah terpasang.

Verifikasi bahwa nama domain kustom tersedia

Periksa apakah domain kustom yang ingin Anda gunakan gratis. Gunakan metode Periksa Ketersediaan Domain dari REST API layanan Azure AI.

Salin blok kode berikut, masukkan nama domain kustom pilihan Anda, dan simpan ke file subdomain.json.

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

Salin file ke folder Anda saat ini atau unggah ke Azure Cloud Shell dan jalankan perintah berikut. Ganti xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx dengan ID langganan Azure Anda.

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

Jika nama yang diinginkan tersedia, Anda akan melihat respons seperti ini:

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

Jika nama sudah diambil, maka Anda akan melihat respons berikut:

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

Aktifkan nama domain kustom

Untuk menggunakan nama domain kustom dengan sumber Ucapan yang dipilih, gunakan perintah az cognitiveservices account update.

(Jika akun Azure Anda hanya memiliki satu langganan aktif, Anda dapat melewati langkah ini.) Pilih langganan Azure yang berisi sumber daya Ucapan. Ganti xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx dengan ID langganan Azure Anda.

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

Setel nama domain kustom ke sumber daya yang dipilih. Ganti nilai parameter sampel dengan yang sebenarnya dan jalankan perintah berikut.

Perhatian

Setelah berhasil menjalankan perintah berikut, Anda akan membuat nama domain kustom untuk sumber daya Ucapan Anda. Ingatlah bahwa nama ini tidak dapat diubah.

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

Menetapkan peran

Untuk autentikasi Microsoft Entra dengan sumber daya Ucapan, Anda perlu menetapkan peran Kontributor Ucapan Cognitive Services atau Pengguna Ucapan Cognitive Services.

Anda dapat menetapkan peran ke pengguna atau aplikasi menggunakan portal Azure atau PowerShell.

Mendapatkan token akses Microsoft Entra

Untuk mendapatkan token akses Microsoft Entra di C#, gunakan Pustaka Klien Identitas Azure.

Berikut adalah contoh penggunaan Azure Identity untuk mendapatkan token akses Microsoft Entra dari browser interaktif:

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;

Konteks token harus diatur ke "https://cognitiveservices.azure.com/.default".

Untuk mendapatkan token akses Microsoft Entra di C++, gunakan Pustaka Klien Identitas Azure.

Berikut adalah contoh penggunaan Azure Identity untuk mendapatkan token akses Microsoft Entra dengan ID penyewa, ID klien, dan kredensial rahasia klien Anda:

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

Konteks token harus diatur ke "https://cognitiveservices.azure.com/.default".

Untuk mendapatkan token akses Microsoft Entra di Java, gunakan Pustaka Klien Identitas Azure.

Berikut adalah contoh penggunaan Azure Identity untuk mendapatkan token akses Microsoft Entra dari 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();

Konteks token harus diatur ke "https://cognitiveservices.azure.com/.default".

Untuk mendapatkan token akses Microsoft Entra di Java, gunakan Pustaka Klien Identitas Azure.

Berikut adalah contoh penggunaan Azure Identity untuk mendapatkan token akses Microsoft Entra dari browser interaktif:

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

Temukan sampel yang mendapatkan token akses Microsoft Entra dalam sampel kode platform identitas Microsoft.

Untuk bahasa pemrograman di mana pustaka klien platform identitas Microsoft tidak tersedia, Anda dapat langsung meminta token akses.

Dapatkan ID sumber daya Ucapan

Anda memerlukan ID sumber daya Ucapan Anda untuk melakukan panggilan SDK menggunakan autentikasi Microsoft Entra.

Catatan

Untuk Pengenalan Niat gunakan ID sumber daya Prediksi LUIS Anda.

Portal Azure

Untuk mendapatkan ID sumber daya di portal Azure:

1. Buka portal Azure dan masuk ke akun Azure Anda.
2. Pilih sumber daya Ucapan.
3. Di grup Pengelolaan Sumber Daya di panel kiri, pilih Properti.
4. Salin ID Sumber Daya

PowerShell

Untuk mendapatkan ID sumber daya menggunakan PowerShell, konfirmasikan bahwa Anda memiliki PowerShell versi 7.x atau yang lebih baru dengan modul Azure PowerShell versi 5.1.0 atau yang lebih baru. Untuk melihat versi alat ini, ikuti langkah-langkah berikut:

1. Di jendela PowerShell, masukkan:

   $PSVersionTable

   Konfirmasikan bahwa nilai PSVersion adalah 7.x atau lebih baru. Untuk meningkatkan versi PowerShell, ikuti petunjuk di Memasang berbagai versi PowerShell.

2. Di jendela PowerShell, masukkan:

   Get-Module -ListAvailable Az

   Jika tidak ada yang muncul, atau jika versi modul Azure PowerShell lebih awal dari 5.1.0, ikuti petunjuk di Memasang modul Azure PowerShell untuk meningkatkan.

Kini jalankan Connect-AzAccount untuk membuat koneksi dengan 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

Membuat objek konfigurasi Speech SDK

Dengan token akses Microsoft Entra, Anda sekarang dapat membuat objek konfigurasi Speech SDK.

Metode penyediaan token, dan metode untuk membuat objek Speech SDK Config yang sesuai bervariasi menurut objek yang Anda gunakan.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

Untuk SpeechRecognizerobjek , SpeechSynthesizer, IntentRecognizer, ConversationTranscriber , buat token otorisasi dari ID sumber daya dan token akses Microsoft Entra lalu gunakan untuk membuat SpeechConfig objek.

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

TranslationRecognizerUntuk , buat token otorisasi dari ID sumber daya dan token akses Microsoft Entra lalu gunakan untuk membuat SpeechTranslationConfig objek.

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

Untuk objek , DialogServiceConnection buat token otorisasi dari ID sumber daya dan token akses Microsoft Entra lalu gunakan untuk membuat CustomCommandsConfig objek atau 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 tidak didukung saat ini di Python

VoiceProfileClient

Untuk menggunakan VoiceProfileClient dengan autentikasi Microsoft Entra, gunakan nama domain kustom yang dibuat di atas.

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 ini tidak tersedia dengan Speech SDK untuk Python.

Catatan

ConversationTranslator tidak mendukung autentikasi Microsoft Entra.