Autentikasi Azure Active Directory dengan Speech SDK

Saat menggunakan Speech SDK untuk mengakses layanan Azure Cognitive Service untuk Ucapan, ada tiga metode autentikasi yang tersedia: kunci layanan, token berbasis kunci, dan Azure Active Directory (Azure AD). Artikel ini menjelaskan cara mengonfigurasi sumber daya Ucapan dan membuat objek konfigurasi Speech SDK supaya dapat menggunakan Azure AD untuk autentikasi.

Artikel ini menunjukkan cara menggunakan autentikasi Azure AD dengan Speech SDK. Anda akan mempelajari cara:

• Membuat sumber daya Ucapan
• Mengonfigurasi sumber daya Ucapan untuk autentikasi Azure AD
• Dapatkan token akses Azure AD
• Buat objek konfigurasi SDK yang sesuai.

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 Azure AD

Untuk mengonfigurasikan sumber daya Ucapan Anda untuk autentikasi Azure AD, buat nama domain kustom dan tetapkan peran.

Buat nama domain kustom

Ikuti langkah-langkah ini untuk membuat nama subdomain kustom untuk Cognitive Services 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 Microsoft 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 Cognitive Services REST API.

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 Cognitive 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 Cognitive 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 lebih lanjut, lihat Mulai Cepat Azure Cloud Shell - Bash.

  

• Jika Anda lebih memilih untuk menjalankan perintah referensi CLI secara lokal, pasang Azure CLI. Jika Anda menggunakan 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 diminta, instal ekstensi Azure CLI saat pertama kali menggunakannya. 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 Cognitive Services REST API.

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 Azure AD dengan sumber daya Ucapan, Anda harus menetapkan Kontributor Ucapan Cognitive Services atau peran Pengguna Ucapan Cognitive Services.

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

Dapatkan token akses Azure AD

Untuk mendapatkan token akses Azure AD di C#, gunakan Pustaka Klien Azure Identity.

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

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

Untuk mendapatkan token akses Azure AD di C++, gunakan Pustaka Klien Azure Identity.

Berikut adalah contoh penggunaan Azure Identity untuk mendapatkan token akses Azure AD 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 Azure AD di Java, gunakan Pustaka Klien Azure Identity.

Berikut adalah contoh penggunaan Azure Identity untuk mendapatkan token akses Azure AD 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 Azure AD di Java, gunakan Pustaka Klien Azure Identity.

Berikut adalah contoh penggunaan Azure Identity untuk mendapatkan token akses Azure AD 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 Azure AD di 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 untuk melakukan panggilan SDK menggunakan autentikasi Azure AD.

Catatan

Untuk Pengenalan Niat gunakan ID sumber daya Prediksi LUIS Anda.

portal Microsoft 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 Azure AD, Anda kini dapat membuat objek konfigurasi Speech SDK.

Metode penyediaan token, dan metode untuk membangun objek Config Speech SDK yang sesuai bervariasi bergantung pada objek yang akan Anda gunakan.

SpeechRecognizer, IntentRecognizer, ConversationTranscriber, dan SpeechSynthesizer

Untuk objek SpeechRecognizer, IntentRecognizer, ConversationTranscriber, dan SpeechSynthesizer, buat token otorisasi dari ID sumber daya dan token akses Azure AD, lalu gunakan token otorisasi tersebut untuk membuat objek 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

Untuk objek TranslationRecognizer, buat token otorisasi dari ID sumber daya dan token akses Azure AD, lalu gunakan token otorisasi tersebut untuk membuat objek 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

Untuk objek DialogServiceConnection, buat token otorisasi dari ID sumber daya dan token akses Azure AD, lalu gunakan token otorisasi tersebut untuk membuat objek CustomCommandsConfig 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 Azure AD, 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 ini tidak mendukung autentikasi Azure AD.