Compartilhar via

Crie e gerencie tokens de acesso para usuários finais

Os tokens de acesso permitem que os SDKs dos Serviços de Comunicação do Azure autentiquem diretamente nos Serviços de Comunicação do Azure como uma identidade específica. Você precisa criar tokens de acesso para usuários finais se quiser que eles participem de uma chamada ou tópico de chat no seu aplicativo.

Esse artigo descreve como usar os SDKs dos Serviços de Comunicação do Azure para criar identidades e gerenciar seus tokens de acesso. Para casos de uso de produção, recomendamos que você gere tokens de acesso em um serviço do lado do servidor, conforme descrito em Arquitetura de cliente e servidor.

Pré-requisitos

Configure seu ambiente

Adicionar a extensão

Adicione a extensão dos Serviços de Comunicação do Azure para a CLI do Azure usando o comando az extension.

az extension add --name communication

Entrar na CLI do Azure

Será necessário entrar na CLI do Azure. Você pode fazer login executando o comando az login no terminal e, em seguida, fornecer suas credenciais.

(Opcional) Use operações de identidade da CLI do Azure sem passar uma cadeia de conexão

Você pode configurar a variável de ambiente AZURE_COMMUNICATION_CONNECTION_STRING para usar operações de identidade da CLI do Azure sem precisar usar --connection_string para passar a cadeia de conexão. Para configurar uma variável de ambiente, abra uma janela de console e selecione seu sistema operacional nas seguintes guias. Substitua <yourConnectionString> pela cadeia de conexão real.

Abra uma janela de console e digite o seguinte comando:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Depois de adicionar a variável de ambiente, talvez seja necessário reiniciar quaisquer programas em execução que precisem ler a variável de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

Armazene seu token de acesso em uma variável de ambiente

Para configurar uma variável de ambiente, abra uma janela de console e selecione seu sistema operacional nas guias abaixo. Substitua <yourAccessToken> por seu token de acesso real.

Abra uma janela de console e digite o seguinte comando:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Depois de adicionar a variável de ambiente, talvez seja necessário reiniciar quaisquer programas em execução que precisem ler a variável de ambiente, incluindo a janela do console. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

Operações

Criar uma identidade

Para criar tokens de acesso, você precisará de uma identidade. O Serviços de Comunicação do Azure mantém um diretório de identidade leve para essa finalidade. Use o método user create para criar uma entrada no diretório com um Id exclusivo. A identidade será necessária posteriormente para emitir tokens de acesso.

az communication identity user create --connection-string "<yourConnectionString>"
  • Substitua <yourConnectionString> por sua cadeia de conexão.

Crie uma identidade e emita um token de acesso na mesma solicitação

Execute o seguinte comando para criar uma identidade dos Serviços de Comunicação e emitir um token de acesso para ela ao mesmo tempo. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações com suporte em Autenticar nos Serviços de Comunicação do Azure.

az communication identity token issue --scope chat --connection-string "<yourConnectionString>"

Faça essa substituição no código:

  • Substitua <yourConnectionString> por sua cadeia de conexão.

Emitir token de acesso

Execute o seguinte comando para emitir um token de acesso para sua identidade dos Serviços de Comunicação. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações com suporte em Autenticar nos Serviços de Comunicação do Azure.

az communication identity token issue --scope chat --user "<userId>" --connection-string "<yourConnectionString>"

Faça essa substituição no código:

  • Substitua <yourConnectionString> por sua cadeia de conexão.
  • Substitua <userId> por seu userId.

Os tokens de acesso são credenciais de curta duração que precisam ser reemitidas. Deixar de fazer isso pode causar a interrupção da experiência dos usuários do aplicativo. A propriedade expires_on response indica o tempo de vida do token de acesso.

Emitir token de acesso com vários escopos

Execute o seguinte comando para emitir um token de acesso com vários escopos para sua identidade dos Serviços de Comunicação. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações com suporte no modelo de identidade.

az communication identity token issue --scope chat voip --user "<userId>" --connection-string "<yourConnectionString>"

Faça essa substituição no código:

  • Substitua <yourConnectionString> por sua cadeia de conexão.
  • Substitua <userId> por seu userId.

Os tokens de acesso são credenciais de curta duração que precisam ser reemitidas. Deixar de fazer isso pode causar a interrupção da experiência dos usuários do aplicativo. A propriedade expires_on response indica o tempo de vida do token de acesso.

Troque um token de acesso Microsoft Entra do usuário do Teams por um token de acesso de Identidade de Comunicação

Use o comando token get-for-teams-user para emitir um token de acesso para o usuário do Teams que pode ser usado com os SDKs dos Serviços de Comunicação do Azure.

az communication identity token get-for-teams-user --aad-token "<yourAadToken>" --client "<yourAadApplication>" --aad-user "<yourAadUser>" --connection-string "<yourConnectionString>"

Faça essa substituição no código:

  • Substitua <yourConnectionString> por sua cadeia de conexão.
  • Substitua <yourAadUser> por sua userId do Microsoft Entra.
  • Substitua <yourAadApplication> pela ID do aplicativo do Microsoft Entra.
  • Substitua <yourAadToken> pelo token de acesso do Microsoft Entra.

Revogar tokens de acesso

Pode ser necessário revogar explicitamente um token de acesso. Por exemplo, você faria isso quando os usuários do aplicativo alterassem a senha que usam para autenticar seu serviço. O comando token revoke invalida todos os tokens de acesso ativos que foram emitidos para a identidade.

az communication identity token revoke --user "<userId>" --connection-string "<yourConnectionString>"

Faça essa substituição no código:

  • Substitua <yourConnectionString> por sua cadeia de conexão.
  • Substitua <userId> por seu userId.

Excluir uma identidade

Ao excluir uma identidade, você revoga todos os tokens de acesso ativos e impede a emissão futura de tokens de acesso para a identidade. Fazer isso também remove todo o conteúdo persistente associado à identidade.

az communication identity user delete --user "<userId>" --connection-string "<yourConnectionString>"

Faça essa substituição no código:

  • Substitua <yourConnectionString> por sua cadeia de conexão.
  • Substitua <userId> por seu userId.

Pré-requisitos

Código Final

Localize o código finalizado no GitHub.

Configure seu ambiente

Criar um aplicativo em C#

  1. Em uma janela de prompt de comando, como cmd, PowerShell ou Bash, execute o dotnet newcomando para criar um novo aplicativo de console com o nome AccessTokensQuickstart. Esse comando cria um projeto Hello World C# simples com um único arquivo de origem, Program.cs.

    dotnet new console -o AccessTokensQuickstart

  2. Mude seu diretório para a pasta do aplicativo recém-criada e use o comando dotnet build para compilar seu aplicativo.

    cd AccessTokensQuickstart
dotnet build

    Uma saída Hello World simples será exibida. Se for exibido corretamente, sua configuração está funcionando e você pode começar a escrever seu código dos Serviços de Comunicação do Azure.

Instalar o pacote

Ainda no diretório do aplicativo, instale o pacote da biblioteca de identidade dos Serviços de Comunicação do Azure para .NET usando o comando dotnet add package.

dotnet add package Azure.Communication.Identity

Configurar a estrutura do aplicativo

No diretório do projeto, conclua as seguintes etapas:

  1. Abra o arquivo Program.cs em um editor de texto.
  2. Adicione uma diretiva using para incluir o namespace Azure.Communication.Identity.
  3. Para oferecer suporte ao código assíncrono, atualize a declaração do método Main.

Para começar, execute o seguinte código:

using System;
using Azure;
using Azure.Core;
using Azure.Communication.Identity;

namespace AccessTokensQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            Console.WriteLine("Azure Communication Services - Access Tokens Quickstart");

            // Quickstart code goes here
        }
    }
}

Autenticar o cliente

Inicialize um CommunicationIdentityClient com a sua cadeia de conexão. O código a seguir, que você adiciona ao método Main, recupera a cadeia de conexão para o recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING.

Para obter mais informações, veja Criar e gerenciar recursos de Serviços de Comunicação do Azure > Armazenar sua sequência de conexão.

// This code demonstrates how to retrieve your connection string
// from an environment variable.
string connectionString = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_CONNECTION_STRING");
var client = new CommunicationIdentityClient(connectionString);

Como alternativa, você pode separar o ponto de extremidade e a chave de acesso executando o seguinte código:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
string endpoint = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ENDPOINT");
string accessKey = Environment.GetEnvironmentVariable("COMMUNICATION_SERVICES_ACCESSKEY");
var client = new CommunicationIdentityClient(new Uri(endpoint), new AzureKeyCredential(accessKey));

Se você já configurou um aplicativo Microsoft Entra, você pode autenticar usando o ID do Microsoft Entra.

TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);

Criar uma identidade

Para criar tokens de acesso, você precisará de uma identidade. O Serviços de Comunicação do Azure mantém um diretório de identidade leve para essa finalidade. Use o método createUser para criar uma nova entrada no diretório com um único Id. Use a identidade posteriormente para emitir tokens de acesso.

var identityResponse = await client.CreateUserAsync();
var identity = identityResponse.Value;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");

Armazene a identidade recebida com mapeamento para os usuários do seu aplicativo (por exemplo, armazenando-a no banco de dados do servidor do aplicativo).

(Versão prévia) Criar uma identidade com um ID personalizado associado

Importante

Esse recurso está disponível a partir da versão 1.4.0-beta1do SDK.

Observação

Esse recurso está atualmente em versão prévia.

Você pode criar uma identidade com um customId associado para mapear as identidades de usuário do seu aplicativo com as identidades dos Serviços de Comunicação do Azure. Se você chamar o CreateUser método novamente com o mesmo customId, ele retornará o mesmo user.Id. Isso elimina a necessidade de armazenar o mapeamento por conta própria.

Response<CommunicationUserIdentifier> user = await client.CreateUserAsync(customId: "alice@contoso.com");
Console.WriteLine($"\nCreated an identity with ID: {user.Id}");

(Versão prévia) Obter detalhes de identidade

Importante

Esse recurso está disponível a partir da versão 1.4.0-beta1do SDK.

Observação

Esse recurso está atualmente em versão prévia.

Você pode usar o GetUserDetail método para recuperar informações sobre um usuário, incluindo o customIdlastTokenIssuedAt.

Response<CommunicationUserIdentifier> user = await client.CreateUserAsync(customId: "alice@contoso.com");
var userDetails = client.GetUserDetail(user);
Console.WriteLine($"User ID: {userDetails.Id}");
Console.WriteLine($"Custom ID: {userDetails.CustomId}");
Console.WriteLine($"Last token issued at: {userDetails.LastTokenIssuedAt}");

Emitir um token de acesso

Depois de obter uma identidade de Serviços de Comunicação, use o método GetToken para emitir um token de acesso para ela. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações com suporte no modelo de identidade. Você também pode construir uma nova instância de communicationUser com base em uma representação de cadeia de caracteres de uma identidade do Serviço de Comunicação do Azure.

// Issue an access token with a validity of 24 hours and the "voip" scope for an identity
var tokenResponse = await client.GetTokenAsync(identity, scopes: new [] { CommunicationTokenScope.VoIP });

// Get the token from the response
var token =  tokenResponse.Value.Token;
var expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Os tokens de acesso são credenciais de curta duração que precisam ser reemitidas. Não fazer isso pode causar uma interrupção na experiência do usuário do seu aplicativo. A propriedade expiresOn indica o tempo de vida do token de acesso.

Definir um tempo de expiração de token personalizado

O tempo de expiração do token padrão é de 24 horas, mas você pode configurá-lo fornecendo um valor entre uma hora e 24 horas para o parâmetro opcional tokenExpiresIn. Ao solicitar um novo token, especifique a duração típica esperada de uma sessão de comunicação para o tempo de expiração do token.

// Issue an access token with a validity of an hour and the "voip" scope for an identity 
TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
CommunicationTokenScope[] scopes = new[] { CommunicationTokenScope.VoIP };
var tokenResponse = await client.GetTokenAsync(identity, scopes, tokenExpiresIn);

Crie uma identidade e emita um token na mesma solicitação

Você pode usar o método CreateUserAndTokenAsync para criar uma identidade de Serviços de Comunicação e emitir um token de acesso para ela ao mesmo tempo. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações com suporte em Autenticar nos Serviços de Comunicação do Azure.

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
var identityAndTokenResponse = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.VoIP });

// Retrieve the identity, token, and expiration date from the response
var identity = identityAndTokenResponse.Value.User;
var token = identityAndTokenResponse.Value.AccessToken.Token;
var expiresOn = identityAndTokenResponse.Value.AccessToken.ExpiresOn;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

(Versão prévia) Criar e identificar e emitir um token na mesma solicitação com uma ID personalizada

Importante

Esse recurso está disponível a partir da versão 1.4.0-beta1do SDK.

Observação

Esse recurso está atualmente em versão prévia.

Você pode passar sua ID personalizada para o CreateUserAndTokenAsync método para criar uma identidade e emitir um token de acesso em uma única chamada.

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
Response<CommunicationUserIdentifierAndToken> identityAndTokenResponse = await client.CreateUserAndTokenAsync(customId: "bob@contoso.com", scopes: new[] { CommunicationTokenScope.VoIP });

// Retrieve the identity, token, and expiration date from the response
var identity = identityAndTokenResponse.User;
var token = identityAndTokenResponse.AccessToken.Token;
var expiresOn = identityAndTokenResponse.AccessToken.ExpiresOn;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
Console.WriteLine(token);

Atualizar um token de acesso

Para atualizar um token de acesso, passe uma instância do objeto CommunicationUserIdentifier para GetTokenAsync. Se você armazenou isso Id e precisa criar um novo CommunicationUserIdentifier, você pode fazer isso passando o arquivo armazenado Id para o construtor CommunicationUserIdentifier da seguinte maneira:

var identityToRefresh = new CommunicationUserIdentifier(identity.Id);
var tokenResponse = await client.GetTokenAsync(identityToRefresh, scopes: new [] { CommunicationTokenScope.VoIP });

Revogar tokens de acesso

Pode ser necessário revogar explicitamente um token de acesso. Por exemplo, quando os usuários do aplicativo alteram a senha que usam para autenticar no seu serviço. O método RevokeTokensAsync invalida todos os tokens de acesso ativos que foram emitidos para a identidade.

await client.RevokeTokensAsync(identity);
Console.WriteLine($"\nSuccessfully revoked all access tokens for identity with ID: {identity.Id}");

Excluir uma identidade

Ao excluir uma identidade, você revoga todos os tokens de acesso ativos e evita a emissão futura de tokens de acesso para a identidade. Fazer isso também remove todo o conteúdo persistente associado à identidade.

await client.DeleteUserAsync(identity);
Console.WriteLine($"\nDeleted the identity with ID: {identity.Id}");

Executar o código

Quando terminar de criar o token de acesso, você poderá executar o aplicativo a partir do diretório do aplicativo usando o comando dotnet run.

dotnet run

A saída do aplicativo descreve cada ação concluída:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 10/11/2022 7:34:29 AM +00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 10/11/2022 7:34:29 AM +00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Pré-requisitos

Código Final

Localize o código finalizado no GitHub.

Configure seu ambiente

Criar um novo aplicativo do Node.js

  1. Em um terminal ou janela de prompt de comando, crie um novo diretório para seu aplicativo e abra-o.

    mkdir access-tokens-quickstart && cd access-tokens-quickstart

  2. Execute npm init -y para criar um package.json arquivo com configurações padrão.

    npm init -y

Instalar o pacote

Use o comando npm install para instalar o SDK de Identidade dos Serviços de Comunicação do Azure para JavaScript.

npm install @azure/communication-identity@latest --save

A opção --save lista a biblioteca como uma dependência no arquivo package.json.

Configurar a estrutura do aplicativo

  1. Crie um arquivo chamado issue-access-token.js no diretório do projeto e adicione o seguinte código:

    const { CommunicationIdentityClient } = require('@azure/communication-identity');

const main = async () => {
  console.log("Azure Communication Services - Access Tokens Quickstart")

  // Quickstart code goes here
};

main().catch((error) => {
  console.log("Encountered an error");
  console.log(error);
})

Autenticar o cliente

Crie a instância de um CommunicationIdentityClient com a sua cadeia de conexão. O código a seguir, que você adiciona ao método Main, recupera a cadeia de conexão para o recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING.

Para obter mais informações, veja Criar e gerenciar recursos de Serviços de Comunicação do Azure > Armazenar sua sequência de conexão.

// This code demonstrates how to fetch your connection string
// from an environment variable.
const connectionString = process.env['COMMUNICATION_SERVICES_CONNECTION_STRING'];

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(connectionString);

Como alternativa, você pode separar o ponto de extremidade e a chave de acesso executando o seguinte código:

// This code demonstrates how to fetch your endpoint and access key
// from an environment variable.
const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const accessKey = process.env["COMMUNICATION_SERVICES_ACCESSKEY"];

// Create the credential
const tokenCredential = new AzureKeyCredential(accessKey);

// Instantiate the identity client
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential)

Se você já configurou um aplicativo Microsoft Entra, você pode autenticar usando o ID do Microsoft Entra.

const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const tokenCredential = new DefaultAzureCredential();
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential);

Criar uma identidade

Para criar tokens de acesso, você precisará de uma identidade. O Serviços de Comunicação do Azure mantém um diretório de identidade leve para essa finalidade. Use o método createUser para criar uma nova entrada no diretório com um único Id. Você precisará da identidade mais tarde para emitir tokens de acesso.

let identityResponse = await identityClient.createUser();
console.log(`\nCreated an identity with ID: ${identityResponse.communicationUserId}`);

Armazene a identidade recebida com mapeamento para os usuários do seu aplicativo (por exemplo, armazenando-a no banco de dados do servidor do aplicativo).

(Versão prévia) Criar uma identidade com uma ID personalizada associada

Importante

Esse recurso está disponível a partir da versão 1.4.0-beta1do SDK.

Observação

Esse recurso está atualmente em versão prévia.

Você pode criar uma identidade com uma identidade associada customId para mapear as identidades de usuário do aplicativo às identidades dos Serviços de Comunicação do Azure. Quando você chama createUser com o mesmo customId, o serviço retorna o mesmo communicationUserId. Isso elimina a necessidade de armazenar o mapeamento por conta própria.

const customId = "alice@contoso.com";
let user = await identityClient.createUser({ customId });
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);

(Versão prévia) Obter detalhes de identidade

Importante

Esse recurso está disponível a partir da versão 1.4.0-beta1do SDK.

Observação

Esse recurso está atualmente em versão prévia.

Você pode usar o getUserDetail método para recuperar informações sobre um usuário, incluindo o customIdlastTokenIssuedAt.

const customId = "alice@contoso.com";
let user = await identityClient.createUser({ customId });
let userDetails = client.getUserDetail(user);
console.log(`\nUser ID: ${user.communicationUserId}`);
console.log(`\nCustom ID: ${userDetails.customId}`);
console.log(`\nLast token issued at: ${userDetails.lastTokenIssuedAt}`);

Emitir um token de acesso

Use o método getToken para emitir um token de acesso para sua identidade de Serviços de Comunicação. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações com suporte no modelo de identidade. Você também pode construir uma nova instância de communicationUser com base em uma representação de cadeia de caracteres da identidade do Serviço de Comunicação do Azure.

// Issue an access token with a validity of 24 hours and the "voip" scope for an identity
let tokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

// Get the token and its expiration date from the response
const { token, expiresOn } = tokenResponse;
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Os tokens de acesso são credenciais de curta duração que precisam ser reemitidas. Não fazer isso pode causar uma interrupção na experiência do usuário do seu aplicativo. A propriedade expiresOn indica o tempo de vida do token de acesso.

Definir um tempo de expiração de token personalizado

O tempo de expiração do token padrão é de 24 horas (1440 minutos), mas você pode configurá-lo fornecendo um valor entre 60 minutos e 1440 minutos para o parâmetro opcional tokenExpiresInMinutes. Ao solicitar um novo token, especifique a duração típica esperada de uma sessão de comunicação para o tempo de expiração do token.

// Issue an access token with a validity of an hour and the "voip" scope for an identity
const tokenOptions: GetTokenOptions = { tokenExpiresInMinutes: 60 };
let tokenResponse = await identityClient.getToken
(identityResponse, ["voip"], tokenOptions);

Crie uma identidade e emita um token em uma chamada de método

Você pode usar o método createUserAndToken para criar uma identidade de Serviços de Comunicação e emitir um token de acesso para ela ao mesmo tempo. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Crie isso com o escopo voip.

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
let identityTokenResponse = await identityClient.createUserAndToken(["voip"]);

// Get the token, its expiration date, and the user from the response
const { token, expiresOn, user } = identityTokenResponse;
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

(Visualização) Criar uma identidade e emitir um token em uma chamada de método, incluindo uma customId

Importante

Esse recurso está disponível a partir da versão 1.4.0-beta1do SDK.

Observação

Esse recurso está atualmente em versão prévia.

Você pode passar sua ID personalizada para o createUserAndToken método para criar uma identidade e emitir um token de acesso em uma única chamada.

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
const customId = "bob@contoso.com";
let identityTokenResponse = await identityClient.createUserAndToken(["voip"], { customId });

// Get the token, its expiration date, and the user from the response
const { token, expiresOn, user } = identityTokenResponse;
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Atualizar um token de acesso

Conforme os tokens expiram, você precisa renová-los. Para atualizar os tokens, chame getToken novamente com a mesma identidade usada para emitir os tokens. Você também precisa fornecer o scopes dos tokens atualizados.

// Value of identityResponse represents the Azure Communication Services identity stored during identity creation and then used to issue the tokens being refreshed
let refreshedTokenResponse = await identityClient.getToken(identityResponse, ["voip"]);

Revogar tokens de acesso

Pode ser necessário revogar um token de acesso. Por exemplo, você faz isso quando os usuários do aplicativo alteram a senha que usam para autenticar no seu serviço. O método revokeTokens invalida todos os tokens de acesso ativos que foram emitidos para a identidade.

await identityClient.revokeTokens(identityResponse);

console.log(`\nSuccessfully revoked all access tokens for identity with ID: ${identityResponse.communicationUserId}`);

Excluir uma identidade

Ao excluir uma identidade, você revoga todos os tokens de acesso ativos e evita a emissão futura de tokens de acesso para a identidade. Fazer isso também remove todo o conteúdo persistente associado à identidade.

await identityClient.deleteUser(identityResponse);

console.log(`\nDeleted the identity with ID: ${identityResponse.communicationUserId}`);

Executar o código

No prompt do console, vá para o diretório que contém o arquivo issue-access-token.js e execute o seguinte node comando para executar o aplicativo:

node ./issue-access-token.js

A saída do aplicativo descreve cada ação concluída:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Pré-requisitos

Código Final

Localize o código finalizado no GitHub.

Configure seu ambiente

Criar um novo aplicativo Python

  1. Em um terminal ou janela de prompt de comando, crie um novo diretório para seu aplicativo e abra-o.

    mkdir access-tokens-quickstart && cd access-tokens-quickstart

  2. Use um editor de texto para criar um arquivo chamado issue-access-tokens.py no diretório raiz do projeto. Depois, adicione a estrutura do programa, incluindo um tratamento de exceções básico. Você adicionará todo o código-fonte a esse arquivo.

    import os
from datetime import timedelta
from azure.communication.identity import CommunicationIdentityClient, CommunicationUserIdentifier

try:
   print("Azure Communication Services - Access Tokens Quickstart")
   # Quickstart code goes here
except Exception as ex:
   print("Exception:")
   print(ex)

Instalar o pacote

No diretório do aplicativo, instale o pacote do Serviços de Comunicação do Azure Identity SDK para Python usando o comando pip install.

pip install azure-communication-identity

Autenticar o cliente

Crie a instância de um CommunicationIdentityClient com a sua cadeia de conexão. O código a seguir, que você adiciona ao bloco try, recupera a cadeia de conexão para o recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING.

Para obter mais informações, veja Criar e gerenciar recursos de Serviços de Comunicação do Azure > Armazenar sua sequência de conexão.

# This code demonstrates how to retrieve your connection string
# from an environment variable.
connection_string = os.environ["COMMUNICATION_SERVICES_CONNECTION_STRING"]

# Instantiate the identity client
client = CommunicationIdentityClient.from_connection_string(connection_string)

Alternativamente, se você já configurou um aplicativo Microsoft Entra, você pode autenticar usando o ID do Microsoft Entra.

endpoint = os.environ["COMMUNICATION_SERVICES_ENDPOINT"]
client = CommunicationIdentityClient(endpoint, DefaultAzureCredential())

Criar uma identidade

Para criar tokens de acesso, você precisará de uma identidade. O Serviços de Comunicação do Azure mantém um diretório de identidade leve para essa finalidade. Use o método create_user para criar uma nova entrada no diretório com um único Id. A identidade será necessária posteriormente para emitir tokens de acesso.

identity = client.create_user()
print("\nCreated an identity with ID: " + identity.properties['id'])

Armazene a identidade recebida com mapeamento para os usuários do seu aplicativo (por exemplo, armazenando-a no banco de dados do servidor do aplicativo).

Emitir um token de acesso

Use o método get_token para emitir um token de acesso para sua identidade de Serviços de Comunicação. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações com suporte no modelo de identidade. Você também pode construir uma nova instância do parâmetro CommunicationUserIdentifier com base em uma representação de cadeia de caracteres da identidade do Serviço de Comunicação do Azure.

# Issue an access token with a validity of 24 hours and the "voip" scope for an identity
token_result = client.get_token(identity, ["voip"])
print("\nIssued an access token with 'voip' scope that expires at " + token_result.expires_on + ":")
print(token_result.token)

Os tokens de acesso são credenciais de curta duração que precisam ser reemitidas. Não fazer isso pode causar uma interrupção na experiência do usuário do seu aplicativo. A propriedade expires_on response indica o tempo de vida do token de acesso.

Definir um tempo de expiração de token personalizado

O tempo de expiração do token padrão é de 24 horas, mas você pode configurá-lo fornecendo um valor entre uma hora e 24 horas para o parâmetro opcional token_expires_in. Ao solicitar um novo token, especifique a duração típica esperada de uma sessão de comunicação para o tempo de expiração do token.

# Issue an access token with a validity of an hour and the "voip" scope for an identity
token_expires_in = timedelta(hours=1)
token_result = client.get_token(identity, ["voip"], token_expires_in=token_expires_in)

Crie uma identidade e emita um token de acesso na mesma solicitação

Você pode usar o método create_user_and_token para criar uma identidade de Serviços de Comunicação e emitir um token de acesso para ela ao mesmo tempo. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações com suporte em Autenticar nos Serviços de Comunicação do Azure.

# Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
identity_token_result = client.create_user_and_token(["voip"])

# Get the token details from the response
identity = identity_token_result[0]
token = identity_token_result[1].token
expires_on = identity_token_result[1].expires_on
print("\nCreated an identity with ID: " + identity.properties['id'])
print("\nIssued an access token with 'voip' scope that expires at " + expires_on + ":")
print(token)

Atualizar um token de acesso

Para atualizar um token de acesso, use o objeto CommunicationUserIdentifier para reemitir um token passando a identidade existente:

# The existingIdentity value represents the Communication Services identity that's stored during identity creation
identity = CommunicationUserIdentifier(existingIdentity)
token_result = client.get_token(identity, ["voip"])

Revogar tokens de acesso

Pode ser necessário revogar explicitamente um token de acesso. Por exemplo, quando os usuários do aplicativo alteram a senha que usam para autenticar no seu serviço. O método revoke_tokens invalida todos os tokens de acesso ativos que foram emitidos para a identidade.

client.revoke_tokens(identity)
print("\nSuccessfully revoked all access tokens for identity with ID: " + identity.properties['id'])

Excluir uma identidade

Ao excluir uma identidade, você revoga todos os tokens de acesso ativos e impede a emissão futura de tokens de acesso para a identidade. Fazer isso também remove todo o conteúdo persistente associado à identidade.

client.delete_user(identity)
print("\nDeleted the identity with ID: " + identity.properties['id'])

Executar o código

No prompt do console, vá para o diretório que contém o arquivo issue-access-tokens.py e execute o seguinte comando python para executar o aplicativo.

python ./issue-access-tokens.py

A saída gerada descreve cada ação concluída:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.9028648+00:00:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Pré-requisitos

Código Final

Localize o código finalizado no GitHub.

Configure seu ambiente

Criar um aplicativo Java

Em um terminal ou janela de prompt de comando, vá para o diretório onde você deseja criar seu aplicativo Java. Para gerar um projeto Java a partir do modelo maven-archetype-quickstart, execute o seguinte código:

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Observe que a tarefa generate cria um diretório com o mesmo nome que artifactId. Nesse diretório, o diretório src/main/java contém o código-fonte do projeto, o diretório src/test/java contém o código-fonte do teste e o arquivo pom.xml é o Modelo de Objeto do Projeto, ou POM, do projeto. Esse arquivo é usado para parâmetros de configuração do projeto.

Instalar os pacotes de Serviços de Comunicação do Azure

Abra o arquivo pom.xml no editor de texto. Adicione o seguinte elemento de dependência ao grupo de dependências:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
    <version>[1.4.0,)</version>
</dependency>

Esse código instrui o Maven a instalar o Serviços de Comunicação do Azure Identity SDK, que você precisará usar mais tarde.

Configurar a estrutura do aplicativo

No diretório do projeto, conclua as seguintes etapas:

  1. Acesse o diretório /src/main/java/com/communication/quickstart.
  2. Abra o arquivo App.java no editor.
  3. Substitua a instrução System.out.println("Hello world!");.
  4. Adicione as diretivas import.

Use o seguinte código para começar:

package com.communication.quickstart;

import com.azure.communication.common.*;
import com.azure.communication.identity.*;
import com.azure.communication.identity.models.*;
import com.azure.core.credential.*;

import java.io.IOException;
import java.time.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Access Tokens Quickstart");
        // Quickstart code goes here
    }
}

Autenticar o cliente

Instancie um CommunicationIdentityClient com a chave de acesso e o ponto de extremidade do seu recurso. Para obter mais informações, veja Criar e gerenciar recursos de Serviços de Comunicação do Azure > Armazenar sua sequência de conexão.

Você também pode inicializar o cliente com qualquer cliente HTTP personalizado que implemente a interface com.azure.core.http.HttpClient.

No arquivo App.java, adicione o seguinte código ao método main:

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
String accessKey = "SECRET";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(new AzureKeyCredential(accessKey))
        .buildClient();

Em vez de fornecer o ponto de extremidade e a chave de acesso, você pode fornecer a cadeia de conexão inteira usando o método connectionString().

// You can find your connection string from your Communication Services resource in the Azure portal
String connectionString = "<connection_string>";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Se você já configurou um aplicativo Microsoft Entra, você pode autenticar usando o ID do Microsoft Entra.

String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
TokenCredential credential = new DefaultAzureCredentialBuilder().build();

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(credential)
        .buildClient();

Criar uma identidade

Para criar tokens de acesso, você precisará de uma identidade. O Serviços de Comunicação do Azure mantém um diretório de identidade leve para essa finalidade. Use o método createUser para criar uma nova entrada no diretório com um único Id.

CommunicationUserIdentifier user = communicationIdentityClient.createUser();
System.out.println("\nCreated an identity with ID: " + user.getId());

A identidade criada será necessária posteriormente para emitir tokens de acesso. Armazene a identidade recebida com mapeamento para os usuários do seu aplicativo (por exemplo, armazenando-a no banco de dados do servidor do aplicativo).

Emitir um token de acesso

Use o método getToken para emitir um token de acesso para sua identidade de Serviços de Comunicação. O parâmetro scopes define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações com suporte no modelo de identidade.

No código a seguir, use a variável de usuário que você criou na etapa anterior para obter um token.

// Issue an access token with a validity of 24 hours and the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes);
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'voip' scope that expires at: " + expiresAt + ": " + token);

Os tokens de acesso são credenciais de curta duração que precisam ser reemitidas. Não fazer isso pode causar uma interrupção na experiência do usuário do seu aplicativo. A propriedade expiresAt indica o tempo de vida do token de acesso.

Definir um tempo de expiração de token personalizado

O tempo de expiração do token padrão é de 24 horas, mas você pode configurá-lo fornecendo um valor entre uma hora e 24 horas para o parâmetro opcional tokenExpiresIn. Ao solicitar um novo token, especifique a duração típica esperada de uma sessão de comunicação para o tempo de expiração do token.

// Issue an access token with a validity of an hour and the "voip" scope for a user identity
List<CommunicationTokenScope> scopes = new ArrayList<>(Arrays.asList(CommunicationTokenScope.VOIP));
Duration tokenExpiresIn = Duration.ofHours(1);
AccessToken accessToken = communicationIdentityClient.getToken(user, scopes, tokenExpiresIn);

Crie uma identidade e emita um token em uma única solicitação

Como alternativa, você pode usar o método “createUserAndToken” para criar uma nova entrada no diretório com um Id exclusivo e emitir um token de acesso ao mesmo tempo.

//Create an identity and issue token with a validity of 24 hours in one call
List<CommunicationTokenScope> scopes = Arrays.asList(CommunicationTokenScope.CHAT);
CommunicationUserIdentifierAndToken result = communicationIdentityClient.createUserAndToken(scopes);
CommunicationUserIdentifier user = result.getUser();
System.out.println("\nCreated a user identity with ID: " + user.getId());
AccessToken accessToken = result.getUserToken();
OffsetDateTime expiresAt = accessToken.getExpiresAt();
String token = accessToken.getToken();
System.out.println("\nIssued an access token with 'chat' scope that expires at: " + expiresAt + ": " + token);

Atualizar um token de acesso

Para atualizar um token de acesso, use o objeto CommunicationUserIdentifier para reemiti-lo:

// existingIdentity represents the Communication Services identity that's stored during identity creation
CommunicationUserIdentifier identity = new CommunicationUserIdentifier(existingIdentity.getId());
AccessToken response = communicationIdentityClient.getToken(identity, scopes);

Revogar um token de acesso

Pode ser necessário revogar explicitamente um token de acesso. Por exemplo, você faria isso quando os usuários do aplicativo alterassem a senha que usam para autenticar seu serviço. O método revokeTokens invalida todos os tokens de acesso ativos para um usuário específico. No código a seguir, você pode usar o usuário criado anteriormente.

communicationIdentityClient.revokeTokens(user);
System.out.println("\nSuccessfully revoked all access tokens for user identity with ID: " + user.getId());

Excluir uma identidade

Ao excluir uma identidade, você revoga todos os tokens de acesso ativos e impede a emissão futura de tokens de acesso para a identidade. Fazer isso também remove todo o conteúdo persistente associado à identidade.

communicationIdentityClient.deleteUser(user);
System.out.println("\nDeleted the user identity with ID: " + user.getId());

Executar o código

  1. Acesse o diretório que contém o arquivo pom.xml.

  2. Compile o projeto usando o seguinte comando mvn:

    mvn compile

  3. Compile o pacote:

    mvn package

  4. Execute o seguinte comando mvn para executar o aplicativo:

    mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

A saída descreve cada ação concluída:

Azure Communication Services - Access Tokens Quickstart

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Issued an access token with 'voip' scope that expires at 2022-10-11T07:34:29.902864800Z:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Created an identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-1ce9-31b4-54b7-a43a0d006a52

Issued an access token with 'chat' scope that expires at 2022-10-11T07:34:29.902864800Z:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEwNiIsIng1dCI6Im9QMWFxQnlfR3hZU3pSaXhuQ25zdE5PU2p2cyIsInR5cCI6IkpXVCJ9.eyJza3lwZWlkIjoiYWNzOjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMF8wMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY3AiOjE3OTIsImNzaSI6IjE2NjUzODcyNjkiLCJleHAiOjE2NjUzOTA4NjksImFjc1Njb3BlIjoidm9pcCIsInJlc291cmNlSWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJyZXNvdXJjZUxvY2F0aW9uIjoidW5pdGVkc3RhdGVzIiwiaWF0IjoxNjY1Mzg3MjY5fQ.kTXpQQtY7w6O82kByljZXrKtBvNNOleDE5m06LapzLeoWfRZCCpJQcDzBoLRA146mOhNzLZ0b5WMNTa5tD-0hWCiicDwgKLMASEGY9g0EvNQOidPff47g2hh6yqi9PKiDPp-t5siBMYqA6Nh6CQ-Oeh-35vcRW09VfcqFN38IgSSzJ7QkqBiY_QtfXz-iaj81Td0287KO4U1y2LJIGiyJLWC567F7A_p1sl6NmPKUmvmwM47tyCcQ1r_lfkRdeyDmcrGgY6yyI3XJZQbpxyt2DZqOTSVPB4PuRl7iyXxvppEa4Uo_y_BdMOOWFe6YTRB5O5lhI8m7Tf0LifisxX2sw

Successfully revoked all access tokens for identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Deleted the identity with ID: 8:acs:4ccc92c8-9815-4422-bddc-ceea181dc774_00000006-19e0-2727-80f5-8b3a0d003502

Pré-requisitos

Criar os tokens de acesso

  1. No portal do Azure, navegue até a lâmina Identidades e Tokens de Acesso do Usuário no seu recurso de Serviços de Comunicação.

  2. Escolha o escopo dos tokens de acesso. Você pode escolher nenhum, um ou vários serviços.

  3. Selecione Gerar.

    Captura de tela que mostra os escopos dos tokens de identidade e acesso onde você seleciona Gerar.

    O sistema vai gerar uma identidade e um token de acesso do usuário correspondente.

  4. Copie essas cadeias de caracteres e use-as nos exemplos de aplicativos e em outros cenários de teste.

    Captura de tela que mostra os tokens de identidade e acesso com data de expiração

Pré-requisitos

Criar usuário

Adicione uma nova etapa ao seu fluxo de trabalho usando o conector de Identidade dos Serviços de Comunicação do Azure. Conclua essas etapas no Power Automate com seu fluxo do Power Automate aberto no modo de edição.

  1. Abra o designer. Na etapa em que você deseja adicionar a nova ação, selecione Nova etapa. Como alternativa, para adicionar a nova ação entre as etapas, passe o mouse sobre a seta entre essas etapas, selecione o sinal de mais (+) e selecione Adicionar uma ação.

  2. Na caixa de pesquisa Escolha uma operação, insira Identidade dos Serviços de Comunicação. Na lista de ações, selecione Criar um usuário.

    Captura de tela que mostra a ação Criar usuário do conector de identidade dos Serviços de Comunicação do Azure.

  3. Forneça a Cadeia de Conexão. Você pode encontrá-lo no portal do Microsoft Azure, dentro do seu Recurso de Serviço de Comunicação do Azure. Selecione a opção Chaves no menu do painel esquerdo para visualizar a cadeia de Conexão.

    Captura de tela que mostra a página Chaves em um Recurso de Serviços de Comunicação do Azure.

  4. Forneça um nome de conexão.

  5. Clique em Criar

    Essa ação gera um ID de usuário, que é uma identidade de usuário dos Serviços de Comunicação. Além disso, se você clicar em Mostrar opções avançadas e selecionar Escopo do token a ação também gerará um token de acesso e seu tempo de expiração com o escopo especificado.

    Captura de tela que mostra a ação Criar usuário do conector dos Serviços de Comunicação do Azure.

    Captura de tela que mostra as opções avançadas de criação de ação do usuário do conector dos Serviços de Comunicação do Azure.

Emita um token de acesso do usuário

Depois de obter uma identidade de Serviços de Comunicação, você pode emitir um token de acesso. Conclua as seguintes etapas:

  1. Adicione uma nova ação e insira Identidade dos Serviços de Comunicação na caixa de pesquisa. Na lista de ações, selecione Emitir um token de acesso do usuário.

    Captura de tela que mostra a ação Emitir token de acesso do conector de identidade dos Serviços de Comunicação do Azure.

  2. Agora você pode usar a saída do ID do usuário da etapa anterior Criar um usuário.

  3. Especifique o escopo do token: VoIP ou chat. Saiba mais sobre tokens e autenticação.

    Captura de tela que mostra a ação Emitir token de acesso do conector de identidade dos Serviços de Comunicação do Azure, especificando o escopo do token.

O sistema gera um token de acesso e seu tempo de expiração com o escopo especificado.

Revogar tokens de acesso do usuário

Depois de obter uma identidade dos Serviços de Comunicação, você pode usar a ação Emitir um token de acesso de usuário para revogar um token de acesso. Conclua as seguintes etapas:

  1. Adicione uma nova ação e insira Identidade dos Serviços de Comunicação na caixa de pesquisa. Na lista de ações, selecione Revogar tokens de acesso do usuário.

    Captura de tela que mostra a ação Revogar token de acesso do conector de identidade dos Serviços de Comunicação do Azure.

  2. Especifique a ID do Usuário

    Captura de tela que mostra a entrada de ação Revogar token de acesso do conector de identidade dos Serviços de Comunicação do Azure.

O sistema revoga todos os tokens de acesso do usuário especificado; não há saídas para essa ação.

Excluir um usuário

Depois de obter uma identidade dos Serviços de Comunicação, você pode usar a ação Emitir um token de acesso de usuário para excluir um token de acesso. Conclua as seguintes etapas:

  1. Adicione uma nova ação e insira Identidade dos Serviços de Comunicação na caixa de pesquisa. Na lista de ações, selecione Excluir um usuário.

    Captura de tela que mostra a ação Excluir usuário do conector de identidade dos Serviços de Comunicação do Azure.

  2. Especifique a ID do Usuário

    Captura de tela que mostra a entrada de ação Excluir usuário do conector de identidade dos Serviços de Comunicação do Azure.

O sistema remove o usuário e revoga todos os tokens de acesso do usuário especificado. Não há saídas para essa ação.

Como testar o seu aplicativo lógico

Para iniciar manualmente o seu fluxo de trabalho, na barra de ferramentas do designer, selecione Executar. O fluxo de trabalho cria um usuário, emite um token de acesso para esse usuário e, em seguida, remove e exclui o usuário.

Para obter mais informações, confira Como executar seu fluxo de trabalho. Você pode verificar as saídas dessas ações depois que o fluxo de trabalho for executado com sucesso.

Use identidade para monitoramento e métricas

O ID do usuário atua como uma chave primária para logs e métricas coletados pelo Azure Monitor. Para visualizar todas as chamadas de um usuário, por exemplo, você pode configurar sua autenticação para mapear uma identidade específica (ou identidades) dos Serviços de Comunicação do Azure para um único usuário.

Para obter mais informações, veja:

Limpar os recursos

Para limpar e remover uma assinatura de Serviços de Comunicação, exclua o recurso ou grupo de recursos. A exclusão de um grupo de recursos também exclui quaisquer outros recursos associados a ele. Para obter mais informações, confira Criar e gerenciar recursos dos Serviços de Comunicação > Limpar recursos.

Para limpar o fluxo de trabalho do aplicativo lógico e os recursos relacionados, veja Criar um exemplo de fluxo de trabalho do aplicativo lógico de Consumo usando o portal do Azure > Limpar recursos.

Próximas etapas

Esse artigo descreve como criar um usuário e excluí-lo. Ele também descreveu como emitir e remover um token de acesso para um usuário usando o conector de Identidade dos Serviços de Comunicação do Azure. Para obter mais informações, veja Conector de identidade dos Serviços de Comunicação do Azure.

Para ver como os tokens são usados ​​por outros conectores, confira como enviar uma mensagem de chat do Power Automate usando os Serviços de Comunicação do Azure.

Para saber mais sobre como enviar um email usando o conector de email dos Serviços de Comunicação do Azure, marque Enviar mensagem de email no Power Automate com os Serviços de Comunicação do Azure..