Speech SDK를 사용한 Microsoft Entra 인증

Speech SDK를 사용하여 Speech Service에 액세스하는 경우 서비스 키, 키 기반 토큰 및 Microsoft Entra ID의 세 가지 인증 방법을 사용할 수 있습니다. 이 문서에서는 인증에 Microsoft Entra ID를 사용하도록 음성 리소스를 구성하고 음성 SDK 구성 개체를 만드는 방법을 설명합니다.

이 문서에서는 Speech SDK와 함께 Microsoft Entra 인증을 사용하는 방법을 보여 줍니다. 다음 방법에 대해 설명합니다.

• 음성 리소스 만들기
• Microsoft Entra 인증을 위한 Speech 리소스 구성
• Microsoft Entra 액세스 토큰 가져오기
• 적절한 SDK 구성 개체를 만듭니다.

토큰 수명을 포함하여 Microsoft Entra 액세스 토큰에 대해 자세히 알아보려면 Microsoft ID 플랫폼 액세스 토큰을 방문하세요.

음성 리소스 만들기

Azure Portal에서 음성 리소스를 만들려면 리소스에 대한 키 가져오기를 참조하세요.

Microsoft Entra 인증을 위한 Speech 리소스 구성

Microsoft Entra 인증을 위한 음성 리소스를 구성하려면 사용자 지정 도메인 이름을 만들고 역할을 할당합니다.

사용자 지정 도메인 이름 만들기

음성 리소스에 대한 Azure AI 서비스용 사용자 지정 하위 도메인 이름을 만들려면 다음 단계를 따릅니다.

주의

사용자 지정 도메인 이름을 설정하면 작업을 되돌릴 수 없습니다. 지역 이름으로 되돌리는 유일한 방법은 새 음성 리소스를 만드는 것입니다.

Speech 리소스에 Speech Studio를 통해 생성된 많은 관련 사용자 지정 모델 및 프로젝트가 있는 경우 프로덕션에 사용되는 리소스를 수정하기 전에 테스트 리소스로 구성을 시도하는 것이 좋습니다.

Azure Portal

Azure Portal을 사용하여 사용자 지정 도메인 이름을 만들려면 다음 단계를 따릅니다.

1. Azure Portal로 이동하여 Azure 계정에 로그인합니다.

2. 필요한 Speech 리소스를 선택합니다.

3. 왼쪽 창의 리소스 관리 그룹에서 네트워킹을 선택합니다.

4. 방화벽 및 가상 네트워크 탭에서 사용자 지정 도메인 이름 생성을 선택합니다. 리소스에 대한 고유한 사용자 지정 하위 도메인을 만드는 지침이 포함된 새 패널이 오른쪽에 나타납니다.

5. 사용자 지정 도메인 이름 생성 패널에서 사용자 지정 도메인 이름을 입력합니다. 전체 사용자 지정 도메인의 형식은 다음과 같습니다. https://{your custom name}.cognitiveservices.azure.com

   사용자 지정 도메인 이름을 만든 후에는 변경할 수 없습니다.

   사용자 지정 도메인 이름을 입력한 후 저장을 선택합니다.

6. 작업이 완료되면 리소스 관리 그룹에서 키 및 엔드포인트를 선택합니다. 리소스의 새 엔드포인트 이름이 https://{your custom name}.cognitiveservices.azure.com 형식으로 시작하는지 확인합니다.

PowerShell

PowerShell을 사용하여 사용자 지정 도메인 이름을 만들려면 컴퓨터에 Azure PowerShell 모듈 버전 5.1.0 이상이 포함된 PowerShell 버전 7.x 이상이 있는지 확인합니다. 이러한 도구의 버전을 확인하려면 다음 단계를 수행합니다.

1. PowerShell 창에서 다음을 입력합니다.

   $PSVersionTable

   PSVersion 값이 7.x 이상인지 확인합니다. PowerShell을 업그레이드하려면 다양한 버전의 PowerShell 설치 지침을 따르세요.

2. PowerShell 창에서 다음을 입력합니다.

   Get-Module -ListAvailable Az

   아무 것도 표시되지 않거나 해당 버전의 Azure PowerShell 모듈이 5.1.0 이전인 경우 Azure PowerShell 모듈 설치의 지침에 따라 업그레이드합니다.

계속하기 전에 Connect-AzAccount를 실행하여 Azure와의 연결을 만듭니다.

사용자 지정 도메인 이름을 사용할 수 있는지 확인

사용하려는 사용자 지정 도메인을 사용할 수 있는지 확인합니다. 다음 코드는 Azure AI 서비스 REST API의 도메인 가용성 확인 작업을 사용하여 도메인을 사용할 수 있는지 확인합니다.

참고 항목

다음 코드는 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

원하는 이름을 사용할 수 있는 경우 다음과 같은 응답이 표시됩니다.

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

이름이 이미 사용 중인 경우 다음 응답이 표시됩니다.

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

사용자 지정 도메인 이름 만들기

선택한 Speech 리소스에 대해 사용자 지정 도메인 이름을 설정하려면 Set-AzCognitiveServicesAccount cmdlet을 사용합니다.

주의

다음 코드가 성공적으로 실행되면 Speech 리소스에 대한 사용자 지정 도메인 이름을 생성합니다. 이 이름은 변경할 수 없습니다.

$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

사전 요구 사항

• Azure Cloud Shell에서 Bash 환경을 사용합니다. 자세한 내용은 Azure Cloud Shell의 Bash에 대한 빠른 시작을 참조하세요.

  

• CLI 참조 명령을 로컬에서 실행하려면 Azure CLI를 설치합니다. Windows 또는 macOS에서 실행 중인 경우 Docker 컨테이너에서 Azure CLI를 실행하는 것이 좋습니다. 자세한 내용은 Docker 컨테이너에서 Azure CLI를 실행하는 방법을 참조하세요.

  • 로컬 설치를 사용하는 경우 az login 명령을 사용하여 Azure CLI에 로그인합니다. 인증 프로세스를 완료하려면 터미널에 표시되는 단계를 수행합니다. 다른 로그인 옵션은 Azure CLI를 사용하여 로그인을 참조하세요.

  • 메시지가 표시되면 처음 사용할 때 Azure CLI 확장을 설치합니다. 확장에 대한 자세한 내용은 Azure CLI에서 확장 사용을 참조하세요.

  • az version을 실행하여 설치된 버전과 종속 라이브러리를 찾습니다. 최신 버전으로 업그레이드하려면 az upgrade를 실행합니다.

이 섹션에는 최신 버전의 Azure CLI가 필요합니다. Azure Cloud Shell을 사용하는 경우 최신 버전이 이미 설치되어 있습니다.

사용자 지정 도메인 이름을 사용할 수 있는지 확인

사용하려는 사용자 지정 도메인을 사용할 수 있는지 확인합니다. Azure AI 서비스 REST API에서 도메인 가용성 확인 방법을 사용합니다.

다음 코드 블록을 복사하고 원하는 사용자 지정 도메인 이름을 삽입한 후 subdomain.json 파일에 저장합니다.

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

파일을 현재 폴더에 복사하거나 Azure Cloud Shell에 업로드하고 다음 명령을 실행합니다. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 를 Azure 구독 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

원하는 이름을 사용할 수 있는 경우 다음과 같은 응답이 표시됩니다.

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

이름이 이미 사용 중인 경우 다음 응답이 표시됩니다.

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

사용자 지정 도메인 이름 설정

선택한 Speech 리소스에 사용자 지정 도메인 이름을 사용하려면 az cognitiveservices account update 명령을 사용합니다.

(Azure 계정에 활성 구독이 하나만 있는 경우 이 단계를 건너뛸 수 있습니다.) Speech 리소스가 포함된 Azure 구독을 선택합니다. xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 를 Azure 구독 ID로 바꿉니다.

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

사용자 지정 도메인 이름을 선택한 리소스로 설정합니다. 샘플 매개 변수 값을 실제 값으로 바꾸고 다음 명령을 실행합니다.

주의

다음 명령을 성공적으로 실행한 후 Speech 리소스에 대한 사용자 지정 도메인 이름을 생성합니다. 이 이름은 변경할 수 없습니다.

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

역할 할당

음성 리소스를 사용한 Microsoft Entra 인증의 경우 Cognitive Services 음성 기여자 또는 Cognitive Services 음성 사용자 역할을 할당해야 합니다.

Azure Portal 또는 PowerShell을 사용하여 사용자 또는 애플리케이션에 역할을 할당할 수 있습니다.

Microsoft Entra 액세스 토큰 가져오기

C#에서 Microsoft Entra 액세스 토큰을 가져오려면 Azure ID 클라이언트 라이브러리를 사용합니다.

다음은 Azure ID를 사용하여 대화형 브라우저에서 Microsoft Entra 액세스 토큰을 가져오는 예입니다.

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;

토큰 컨텍스트는 "https://cognitiveservices.azure.com/.default"로 설정해야 합니다.

C++에서 Microsoft Entra 액세스 토큰을 가져오려면 Azure ID 클라이언트 라이브러리를 사용합니다.

다음은 Azure ID를 사용하여 테넌트 ID, 클라이언트 ID 및 클라이언트 암호 자격 증명이 있는 Microsoft Entra 액세스 토큰을 가져오는 예입니다.

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

토큰 컨텍스트는 "https://cognitiveservices.azure.com/.default"로 설정해야 합니다.

Java에서 Microsoft Entra 액세스 토큰을 가져오려면 Azure ID 클라이언트 라이브러리를 사용합니다.

다음은 Azure ID를 사용하여 브라우저에서 Microsoft Entra 액세스 토큰을 가져오는 예입니다.

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

토큰 컨텍스트는 "https://cognitiveservices.azure.com/.default"로 설정해야 합니다.

Python에서 Microsoft Entra 액세스 토큰을 가져오려면 Azure ID 클라이언트 라이브러리를 사용합니다.

다음은 Azure ID를 사용하여 대화형 브라우저에서 Microsoft Entra 액세스 토큰을 가져오는 예입니다.

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

Microsoft ID 플랫폼 코드 샘플에서 Microsoft Entra 액세스 토큰을 가져오는 샘플을 찾으세요.

Microsoft ID 플랫폼 클라이언트 라이브러리를 사용할 수 없는 프로그래밍 언어의 경우 직접 액세스 토큰을 요청할 수 있습니다.

음성 리소스 ID 가져오기

Microsoft Entra 인증을 사용하여 SDK를 호출하려면 음성 리소스 ID가 필요합니다.

참고 항목

의도 인식의 경우 LUIS 예측 리소스 ID를 사용합니다.

Azure Portal

Azure Portal에서 리소스 ID를 가져오려면 다음을 수행합니다.

1. Azure Portal로 이동하여 Azure 계정에 로그인합니다.
2. 음성 리소스를 선택합니다.
3. 왼쪽 창의 리소스 관리 그룹에서 속성을 선택합니다.
4. 리소스 ID를 복사합니다.

PowerShell

PowerShell을 사용하여 리소스 ID를 가져오려면 Azure PowerShell 모듈 버전 5.1.0 이상이 포함된 PowerShell 버전 7.x 이상이 있는지 확인합니다. 이러한 도구의 버전을 확인하려면 다음 단계를 수행합니다.

1. PowerShell 창에서 다음을 입력합니다.

   $PSVersionTable

   PSVersion 값이 7.x 이상인지 확인합니다. PowerShell을 업그레이드하려면 다양한 버전의 PowerShell 설치 지침을 따르세요.

2. PowerShell 창에서 다음을 입력합니다.

   Get-Module -ListAvailable Az

   아무 것도 표시되지 않거나 해당 버전의 Azure PowerShell 모듈이 5.1.0 이전인 경우 Azure PowerShell 모듈 설치의 지침에 따라 업그레이드합니다.

이제 Connect-AzAccount를 실행하여 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

Speech SDK 구성 개체 만들기

Microsoft Entra 액세스 토큰을 사용하여 이제 Speech SDK 구성 개체를 만들 수 있습니다.

토큰을 제공하는 방법과 해당 Speech SDK Config 개체를 구성하는 방법은 사용할 개체에 따라 다릅니다.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer, ConversationTranscriber

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer 및 ConversationTranscriber 개체의 경우 리소스 ID와 Microsoft Entra 액세스 토큰에서 권한 부여 토큰을 빌드한 다음, 이를 사용하여 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

TranslationRecognizer의 경우 리소스 ID 및 Microsoft Entra 액세스 토큰에서 권한 부여 토큰을 빌드한 다음, 이를 사용하여 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

DialogServiceConnection 개체의 경우 리소스 ID 및 Microsoft Entra 액세스 토큰에서 권한 부여 토큰을 빌드한 다음 이를 사용하여 CustomCommandsConfig 또는 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는 현재 Python에서 지원되지 않습니다.

VoiceProfileClient

Microsoft Entra 인증과 함께 VoiceProfileClient를 사용하려면 위에서 만든 사용자 지정 도메인 이름을 사용합니다.

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는 Python용 Speech SDK에서 사용할 수 없습니다.

참고 항목

ConversationTranslator는 Microsoft Entra 인증을 지원하지 않습니다.