Biblioteca de clientes da Identidade de Comunicação do Azure para .NET – versão 1.2.0

Artigo
04/18/2023

A Identidade de Comunicação do Azure está gerenciando tokens para Serviços de Comunicação do Azure.

Código-fonte | Documentação do produto | Amostras

Introdução

Instalar o pacote

Instale a biblioteca de clientes da Identidade de Comunicação do Azure para .NET com o NuGet:

dotnet add package Azure.Communication.Identity

Pré-requisitos

Você precisa de uma assinatura do Azure e de um Recurso do Serviço de Comunicação para usar esse pacote.

Para criar um novo Serviço de Comunicação, você pode usar o Portal do Azure, o Azure PowerShell ou a biblioteca de clientes de gerenciamento do .NET.

Autenticar o cliente

O cliente de identidade pode ser autenticado usando uma cadeia de conexão adquirida de um Recursos de Comunicação do Azure no Portal do Azure.

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

Ou, como alternativa, usar o ponto de extremidade e a chave de acesso adquiridos de recursos de comunicação do Azure no Portal do Azure.

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

Os clientes também têm a opção de autenticar usando um token válido do Active Directory.

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

Principais conceitos

CommunicationIdentityClient fornece as funcionalidades para gerenciar tokens de acesso do usuário: criando novos e revogando-os.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Exemplos

Criando um novo usuário

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

Obtendo um token para um usuário 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}");

Também é possível criar um token de acesso à Identidade de Comunicação personalizando o tempo de expiração. O período de validade do token deve estar dentro do intervalo de [1,24] horas. Se não for fornecido, o valor padrão de 24 horas será usado.

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}");

Criando um usuário e um token na mesma solicitação

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}");

Revogando tokens de um usuário

Caso os tokens de um usuário sejam comprometidos ou precisem ser revogados:

Response revokeResponse = await client.RevokeTokensAsync(user);

Excluir um usuário

Response deleteResponse = await client.DeleteUserAsync(user);

Trocando Azure AD token de acesso de um usuário do Teams por um token de acesso da Identidade de Comunicação

O CommunicationIdentityClient pode ser usado para trocar um token de acesso Azure AD de um usuário do Teams por um novo token de acesso da Identidade de Comunicação com um tempo de expiração correspondente.

A GetTokenForTeamsUser função aceita os seguintes parâmetros encapsulados no recipiente de opções GetTokenForTeamsUserOptions :

teamsUserAadToken Token de acesso do Azure Active Directory de um usuário do Teams
clientIdID do cliente de um aplicativo Azure AD a ser verificado em relação à declaração appId no token de acesso Azure AD
userObjectIdID de objeto de um usuário do Azure AD (Usuário do Teams) a ser verificado em relação à declaração OID no token de acesso Azure AD

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

Solução de problemas

Todas as operações de serviço de token de usuário lançarão uma RequestFailedException em caso de falha.

// 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);
}

Próximas etapas

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.