Share via

Autenticación de Microsoft Entra con el SDK de voz

  • Artículo

Si se usa el SDK de voz para acceder al servicio de voz, hay tres métodos de autenticación disponibles: claves de servicio, un token basado en claves y Microsoft Entra ID. En este artículo se describe cómo configurar un recurso de voz y crear un objeto de configuración del SDK de voz para usar Microsoft Entra ID para la autenticación.

En este artículo se muestra cómo usar la autenticación de Microsoft Entra con el SDK de voz. Aprenderá a:

  • Crear un recurso de voz.
  • Configurar el recurso de voz para la autenticación de Microsoft Entra
  • Obtener un token de acceso de Microsoft Entra
  • Crear el objeto de configuración del SDK adecuado.

Para obtener más información sobre los tokens de acceso de Microsoft Entra, incluyendo la duración del token, visite Tokens de acceso en la Plataforma de identidad de Microsoft.

Creación de un recurso de voz

Para crear un recurso de voz en Azure Portal, consulte Obtención de las claves del recurso.

Configurar el recurso de voz para la autenticación de Microsoft Entra

Para configurar un recurso de voz para la autenticación de Microsoft Entra, cree un nombre de dominio personalizado y asigne roles.

Creación de un nombre de dominio personalizado

Siga estos pasos para crear un nombre de subdominio personalizado para servicios de Azure AI para el recurso de Voz.

Precaución

Cuando se habilita un nombre de dominio personalizado, la operación no es reversible. La única manera de volver a establecer el nombre regional es crear un recurso de voz nuevo.

Si el recurso de voz tiene muchos modelos y proyectos personalizados asociados creados mediante Speech Studio, se recomienda encarecidamente probar la configuración en un recurso de prueba antes de modificar el usado en producción.

Para crear un nombre de dominio personalizado desde Azure Portal, siga estos pasos:

  1. Vaya a Azure Portal e inicie sesión con su cuenta de Azure.

  2. Seleccione el recurso de voz necesario.

  3. En el grupo Administración de recursos del panel izquierdo, seleccione Redes.

  4. En la pestaña Firewalls y redes virtuales, seleccione Generate Custom Domain Name (Generar nombre de dominio personalizado). En el lado derecho aparece un panel con instrucciones para crear un subdominio personalizado único para el recurso.

  5. En el panel Generate Custom Domain Name (Generar nombre de dominio personalizado), escriba un nombre de dominio personalizado. El dominio personalizado completo tiene el siguiente aspecto: https://{your custom name}.cognitiveservices.azure.com.

    Recuerde que después de crear un nombre de dominio personalizado, no se puede cambiar.

    Después de haber escrito su nombre de dominio personalizado, seleccione Guardar.

  6. Una vez finalizada la operación, en el grupo Administración de recursos, seleccione Keys and Endpoint (Claves y punto de conexión). Confirme que el nuevo nombre del punto de conexión del recurso empieza de esta manera: https://{your custom name}.cognitiveservices.azure.com.

Asignación de roles

Para la autenticación de Microsoft Entra con recursos de voz, es preciso que asigne los roles Colaborador de voz de Cognitive Services o Usuario de voz de Cognitive Services.

Se pueden asignar roles tanto al usuario como a la aplicación mediante Azure Portal o PowerShell.

Obtener un token de acceso de Microsoft Entra

Para obtener un token de acceso de Microsoft Entra en C#, use la biblioteca cliente de Azure Identity.

Este es un ejemplo del uso de Azure Identity para obtener un token de acceso de Microsoft Entra desde un explorador interactivo:

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;

El contexto del token debe establecerse en "https://cognitiveservices.azure.com/.default".

Para obtener un token de acceso de Microsoft Entra en C++, use la biblioteca cliente de Azure Identity.

Este es un ejemplo del uso de Azure Identity para obtener un token de acceso de Microsoft Entra con el identificador de inquilino, el identificador de cliente y las credenciales de secreto de cliente:

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

El contexto del token debe establecerse en "https://cognitiveservices.azure.com/.default".

Para obtener un token de acceso de Microsoft Entra en Java, use la biblioteca cliente de Azure Identity.

Este es un ejemplo del uso de Azure Identity para obtener un token de acceso de Microsoft Entra desde un explorador:

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

El contexto del token debe establecerse en "https://cognitiveservices.azure.com/.default".

Para obtener un token de acceso de Microsoft Entra en Java, use la biblioteca cliente de Azure Identity.

Este es un ejemplo del uso de Azure Identity para obtener un token de acceso de Microsoft Entra desde un explorador interactivo:

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

Busque ejemplos que obtengan un token de acceso de Microsoft Entra en la plataforma de identidad de Microsoft.

En el caso de los lenguajes de programación en los que no haya ninguna plataforma de identidad de Microsoft disponible, se puede solicitar directamente un token de acceso.

Obtención del identificador de recurso de Voz

Necesita el identificador de recurso de voz para realizar llamadas SDK mediante la autenticación de Microsoft Entra.

Nota:

En el caso de Reconocimiento de la intención, use el identificador de recursos de predicción de LUIS.

Para obtener el identificador de recurso en Azure Portal:

  1. Vaya a Azure Portal e inicie sesión con su cuenta de Azure.
  2. Seleccione un recurso de Voz.
  3. En el grupo Administración de recursos del panel izquierdo, seleccione Propiedades.
  4. Copie el identificador de recurso.

Creación del objeto de configuración del SDK de Voz

Con un token de acceso de Microsoft Entra, ahora se puede crear un objeto de configuración del SDK de voz.

El método de proporcionar el token y el método para construir el SDK de Voz correspondiente Config objeto varía según el objeto que use.

SpeechRecognizer, SpeechSynthesizer, IntentRecognizer y ConversationTranscriber

En el caso de los objetos SpeechRecognizer, SpeechSynthesizer, IntentRecognizer y ConversationTranscriber compile el token de autorización a partir del identificador de recurso y del token de acceso de Microsoft Entra y, después, úselo para crear un objeto 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

En el caso de TranslationRecognizer, compile el token de autorización a partir del identificador de recurso y del token de acceso de Microsoft Entra y, después, úselo para crear un objeto 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

En el caso del objeto DialogServiceConnection, compile el token de autorización a partir del identificador de recurso y del token de acceso de Microsoft Entra y, después, úselo para crear un objeto CustomCommandsConfig o 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);

Actualmente, DialogServiceConnector no es compatible con Python

VoiceProfileClient

Para usar VoiceProfileClient con la autenticación de Microsoft Entra, utilice el nombre de dominio personalizado creado anteriormente.

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 no está disponible con el SDK de Voz para Python.

Nota:

El ConversationTranslator no admite la autenticación de Microsoft Entra.