Biblioteca cliente de Azure Communication Identity para .NET: versión 1.2.0

Artículo
04/18/2023

Azure Communication Identity administra tokens para Azure Communication Services.

Código | fuente Documentación | del producto Muestras

Introducción

Instalar el paquete

Instale la biblioteca cliente de Azure Communication Identity para .NET con NuGet:

dotnet add package Azure.Communication.Identity

Prerrequisitos

Necesita una suscripción de Azure y un recurso de Communication Service para usar este paquete.

Para crear un servicio de comunicación, puede usar Azure Portal, el Azure PowerShell o la biblioteca cliente de administración de .NET.

Autenticar el cliente

El cliente de identidad se puede autenticar mediante una cadena de conexión adquirida desde un recurso de comunicación de Azure en Azure Portal.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);

También puede usar el punto de conexión y la clave de acceso adquiridas desde recursos de comunicación de Azure en Azure Portal.

var endpoint = new Uri("https://my-resource.communication.azure.com");
var accessKey = "<access_key>";
var client = new CommunicationIdentityClient(endpoint, new AzureKeyCredential(accessKey));

Los clientes también tienen la opción de autenticarse mediante un token de Active Directory válido.

var endpoint = new Uri("https://my-resource.communication.azure.com");
TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(endpoint, tokenCredential);

Conceptos clave

CommunicationIdentityClient proporciona las funcionalidades para administrar tokens de acceso de usuario: crear nuevos y revocarlos.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente sean seguros para subprocesos e independientes entre sí (guía). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Ejemplos

Creación de un nuevo usuario

Response<CommunicationUserIdentifier> userResponse = await client.CreateUserAsync();
CommunicationUserIdentifier user = userResponse.Value;
Console.WriteLine($"User id: {user.Id}");

Obtención de un token para un usuario existente

Response<AccessToken> tokenResponse = await client.GetTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat });
string token = tokenResponse.Value.Token;
DateTimeOffset expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"Token: {token}");
Console.WriteLine($"Expires On: {expiresOn}");

También es posible crear un token de acceso de Communication Identity personalizando la hora de expiración. El período de validez del token debe estar dentro de [1,24] intervalo de horas. Si no se proporciona, se usará el valor predeterminado de 24 horas.

TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
Response<AccessToken> tokenResponse = await client.GetTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat }, tokenExpiresIn);
string token = tokenResponse.Value.Token;
DateTimeOffset expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"Token: {token}");
Console.WriteLine($"Expires On: {expiresOn}");

Creación de un usuario y un token en la misma solicitud

Response<CommunicationUserIdentifierAndToken> response = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.Chat });
var (user, token) = response.Value;
Console.WriteLine($"User id: {user.Id}");
Console.WriteLine($"Token: {token.Token}");

TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
Response<CommunicationUserIdentifierAndToken> response = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.Chat }, tokenExpiresIn);
var (user, token) = response.Value;
Console.WriteLine($"User id: {user.Id}");
Console.WriteLine($"Token: {token.Token}");

Revocar los tokens de un usuario

En caso de que los tokens de un usuario estén en peligro o deban revocarse:

Response revokeResponse = await client.RevokeTokensAsync(user);

Eliminar un usuario

Response deleteResponse = await client.DeleteUserAsync(user);

Intercambio de token de acceso de Azure AD de un usuario de Teams para un token de acceso de identidad de comunicación

CommunicationIdentityClient se puede usar para intercambiar un token de acceso de Azure AD de un usuario de Teams para un nuevo token de acceso de Communication Identity con una hora de expiración coincidente.

La GetTokenForTeamsUser función acepta los parámetros siguientes encapsulados en el GetTokenForTeamsUserOptions contenedor de opciones:

teamsUserAadToken Token de acceso de Azure Active Directory de un usuario de Teams
clientId Identificador de cliente de una aplicación de Azure AD que se va a comprobar con la notificación appId en el token de acceso de Azure AD
userObjectId Identificador de objeto de un usuario de Azure AD (usuario de Teams) que se va a comprobar con la notificación OID en el token de acceso de Azure AD

Response<AccessToken> tokenResponse = await client.GetTokenForTeamsUserAsync(new GetTokenForTeamsUserOptions(teamsUserAadToken, clientId, userObjectId));
string token = tokenResponse.Value.Token;
Console.WriteLine($"Token: {token}");

Solución de problemas

Todas las operaciones de servicio de token de usuario producirán una excepción RequestFailedException en caso de error.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);

try
{
    Response<CommunicationUserIdentifier> response = await client.CreateUserAsync();
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.Message);
}

Pasos siguientes

Más información sobre los tokens de acceso de usuario de comunicación

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.