Início Rápido: Criar e gerenciar tokens de acesso

Os tokens de acesso permitem que os SDKs dos Serviços de Comunicação do Azure se autentiquem diretamente nos Serviços de Comunicação do Azure como uma identidade particular. Você precisará criar token de acesso se quiser que eles ingressem em um thread de chamada ou de chat em seu aplicativo.

Neste início rápido, você aprenderá a usar os SDKs de Serviços de Comunicação do Azure para criar identidades e gerenciar seus tokens de acesso. Para casos de uso de produção, é recomendável gerar tokens de acesso em um serviço do lado do servidor.

Pré-requisitos

Configurando

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

Você precisará entrar na CLI do Azure. Para se conectar, execute o comando az login no terminal e forneça suas credenciais.

(Opcional) Usar 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 do console e selecione o sistema operacional nas guias abaixo. Substitua <yourConnectionString> pela cadeia de conexão real.

Abra uma janela do console e insira o seguinte comando:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

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

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

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

Abra uma janela do console e insira o seguinte comando:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

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

Operations

Criar uma identidade

Para criar tokens de acesso, você precisará de uma identidade. Os 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> pela cadeia de conexão.

Criar uma identidade e emitir 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, confira a lista de ações com suporte em Autenticar para 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> pela 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, confira a lista de ações com suporte em Autenticar para 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> pela 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 de resposta expires_on 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> pela 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 de resposta expires_on indica o tempo de vida do token de acesso.

Trocar um token de acesso do 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> pela 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

Ocasionalmente, talvez seja necessário revogar explicitamente um token de acesso. Por exemplo, você faria isso quando os usuários do aplicativo alterasse a senha que eles usam para autenticação em 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> pela 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 de tokens de acesso adicionais 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> pela cadeia de conexão.
  • Substitua <userId> por seu userId.

Pré-requisitos

Código final

Encontre o código finalizado para este guia de início rápido no GitHub.

Configurar seu ambiente

Criar um aplicativo em C#

Em uma janela de Prompt de Comando, como cmd, PowerShell ou Bash, execute o comando dotnet new para criar um aplicativo de console com o nome AccessTokensQuickstart. Esse comando cria um projeto simples em C# do tipo "Olá, Mundo" com um arquivo de origem único: Program.cs.

dotnet new console -o AccessTokensQuickstart

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

cd AccessTokensQuickstart
dotnet build

Uma saída "Olá, Mundo" simples deve ser exibida. Se for, sua configuração estará funcionando corretamente e você poderá começar a escrever seu código Serviços de Comunicação do Azure específico.

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 o framework de aplicativos

No diretório do projeto, faça o seguinte:

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

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, consulte a seção "armazenar sua cadeia de conexão" em Criar e gerenciar recursos dos serviços de comunicaçã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á tiver configurado um aplicativo do Microsoft Entra, poderá autenticar-se usando o Microsoft Entra ID.

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. Os 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 entrada no diretório com um Id exclusivo. A identidade será necessária 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 o mapeamento para os usuários do aplicativo (por exemplo, armazenando-a no banco de dados do servidor de aplicativos).

Emitir um token de acesso

Quando você tiver uma identidade dos 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 instância de um communicationUser com base na representação da cadeia de caracteres da identidade de um 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. Deixar de fazer isso pode causar a interrupção da experiência dos usuários do 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 é possível configurá-lo fornecendo um valor entre uma hora e 24 horas para o parâmetro opcional tokenExpiresIn. Ao solicitar um novo token, é recomendável especificar 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);

Criar uma identidade e emitir um token na mesma solicitação

Você pode usar o método CreateUserAndTokenAsync 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, confira a lista de ações com suporte em Autenticar para 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);

Atualizar um token de acesso

Para atualizar um token de acesso, passe uma instância do objeto CommunicationUserIdentifier para GetTokenAsync. Se você tiver armazenado essa Id e precisar criar um CommunicationUserIdentifier, poderá fazer isso passando o Id armazenado 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

Ocasionalmente, talvez seja necessário revogar explicitamente um token de acesso. Por exemplo, você faria isso quando os usuários do aplicativo alterasse a senha que eles usam para autenticação em 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 impede a emissão de tokens de acesso adicionais 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 no 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

Encontre o código finalizado para este guia de início rápido no GitHub.

Configurar seu ambiente

Criar um novo aplicativo do Node.js

Em um terminal ou janela do Prompt de Comando, crie um diretório para seu aplicativo e abra-o.

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

Execute npm init -y para criar um arquivo package.json com as 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 o framework de aplicativos

  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, consulte a seção "armazenar sua cadeia de conexão" em Criar e gerenciar recursos dos serviços de comunicaçã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á tiver configurado um aplicativo do Microsoft Entra, poderá autenticar-se usando o Microsoft Entra ID.

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. Os 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 entrada no diretório com um Id exclusivo. A identidade será necessária posteriormente para emitir tokens de acesso.

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

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

Emitir um token de acesso

Use o método getToken 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 no modelo de identidade. Você também pode construir uma instância do communicationUser com base na representação da 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. Deixar de fazer isso pode causar a interrupção da experiência dos usuários do 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 é possível configurá-lo fornecendo um valor entre 60 minutos e 1440 minutos para o parâmetro opcional tokenExpiresInMinutes. Ao solicitar um novo token, é recomendável especificar 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);

Criar uma identidade e emitir um token em uma chamada de método

Você pode usar o método createUserAndToken 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. Novamente, você o cria 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);

Atualizar um token de acesso

À medida que os tokens expirarem, você precisará atualizá-los periodicamente. A atualização é fácil, simplesmente chame getToken novamente com a mesma identidade que foi usada para emitir os tokens. Também é preciso fornecer a 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

Ocasionalmente, talvez seja necessário revogar um token de acesso. Por exemplo, você faria isso quando os usuários do aplicativo alterasse a senha que eles usam para autenticação em 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 impede a emissão de tokens de acesso adicionais 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

Do prompt de um console, vá até o diretório que contém o arquivo issue-access-token.js e execute o seguinte comando node 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

Encontre o código finalizado para este guia de início rápido no GitHub.

Configurar seu ambiente

Criar um novo aplicativo Python

  1. Em um terminal ou janela do Prompt de Comando, crie um 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 e adicione a estrutura do programa, incluindo a manipulação de exceção básica. Você adicionará todo o código-fonte deste guia de início rápido a esse arquivo nas seções a seguir.

    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

Ainda no diretório do aplicativo, instale o pacote do SDK de Identidade dos Serviços de Comunicação do Azure 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, consulte a seção "armazenar sua cadeia de conexão" em Criar e gerenciar recursos dos serviços de comunicaçã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)

Como alternativa, se você já tiver configurado um aplicativo do Microsoft Entra, poderá autenticar-se usando o Microsoft Entra ID.

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

Criar uma identidade

Para criar tokens de acesso, você precisará de uma identidade. Os 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 entrada no diretório com um Id exclusivo. 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 o mapeamento para os usuários do aplicativo (por exemplo, armazenando-a no banco de dados do servidor de aplicativos).

Emitir um token de acesso

Use o método get_token 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 no modelo de identidade. Você também pode construir uma instância do parâmetro CommunicationUserIdentifier com base na representação da 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. Deixar de fazer isso pode causar a interrupção da experiência dos usuários do aplicativo. A propriedade de resposta expires_on 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 é possível configurá-lo fornecendo um valor entre uma hora e 24 horas para o parâmetro opcional token_expires_in. Ao solicitar um novo token, é recomendável especificar 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)

Criar uma identidade e emitir um token de acesso na mesma solicitação

Você pode usar o método create_user_and_token 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, confira a lista de ações com suporte em Autenticar para 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

Ocasionalmente, talvez seja necessário revogar explicitamente um token de acesso. Por exemplo, você faria isso quando os usuários do aplicativo alterasse a senha que eles usam para autenticação em 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 de tokens de acesso adicionais 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

Do prompt de um console, vá até o diretório que contém o arquivo issue-access-tokens.py e execute o comando python a seguir para executar o aplicativo.

python ./issue-access-tokens.py

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

Encontre o código finalizado para este guia de início rápido no GitHub.

Configurar seu ambiente

Criar um aplicativo Java

Em uma janela de terminal ou de prompt de comando, vá para o diretório em que você deseja criar seu aplicativo Java. Para gerar um projeto Java no 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

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

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

Abra o arquivo pom.xml no seu 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 SDK de identidade dos serviços de comunicação, que você usará mais tarde.

Configurar o framework de aplicativos

No diretório do projeto, faça o seguinte:

  1. Vá para o diretório /src/main/java/com/communication/quickstart.
  2. Abra o arquivo App.java em seu 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

Crie uma instância de um CommunicationIdentityClient com a chave de acesso e o ponto de extremidade do recurso. Para obter mais informações, consulte a seção "armazenar sua cadeia de conexão" em Criar e gerenciar recursos dos serviços de comunicação.

Além disso, você 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 toda a cadeia de conexão 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á tiver configurado um aplicativo do Microsoft Entra, poderá autenticar-se usando o Microsoft Entra ID.

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. Os 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 entrada no diretório com um Id exclusivo.

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 o mapeamento para os usuários do aplicativo (por exemplo, armazenando-a no banco de dados do servidor de aplicativos).

Emitir um token de acesso

Use o método getToken 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 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. Deixar de fazer isso pode causar a interrupção da experiência dos usuários do 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 é possível configurá-lo fornecendo um valor entre uma hora e 24 horas para o parâmetro opcional tokenExpiresIn. Ao solicitar um novo token, é recomendável especificar 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);

Criar uma identidade e emitir token em uma solicitação

Como alternativa, podemos usar o método 'createUserAndToken' para criar uma 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

Ocasionalmente, talvez seja necessário revogar explicitamente um token de acesso. Por exemplo, você faria isso quando os usuários do aplicativo alterasse a senha que eles usam para autenticação em 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 de tokens de acesso adicionais 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

Navegue até o diretório que contém o arquivo pom.xml e compile o projeto usando o seguinte comando mvn:

mvn compile

Então, crie o pacote:

mvn package

Execute o seguinte comando mvn para executar o aplicativo:

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

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.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

No portal do Azure, navegue até a folha Identidades e tokens de acesso do usuário em seu recurso dos Serviços de Comunicação.

Escolha o escopo dos tokens de acesso. Você pode selecionar nenhum, um ou vários. Clique em Gerar.

Select the scopes of the identity and access tokens.

Você verá uma identidade e um token de acesso de usuário correspondente gerados. Você pode copiar essas cadeias de caracteres e usá-las nos aplicativos de exemplo e em outros cenários de teste.

The identity and access tokens are generated and show the expiration date.

Pré-requisitos

Criar usuário

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

  1. No 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, mova o ponteiro sobre a seta entre essas etapas, selecione o sinal de adição (+) e selecione Adicionar uma ação.

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

    Screenshot that shows the Azure Communication Services Identity connector Create user action.

  3. Forneça a Cadeia de Conexão. Ela pode ser encontrada no Microsoft Azure, no recurso do Serviço de Comunicação do Azure, na opção Chaves do menu esquerdo > Cadeia de Conexão

    Screenshot that shows the Keys page within an Azure Communication Services Resource.

  4. Forneça uma Nome de Conexão

  5. Clique em Criar

    Essa ação gerará uma ID do 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 o Escopo do Token, a ação também gerará um token de acesso e o tempo de expiração com o escopo especificado.

    Screenshot that shows the Azure Communication Services connector Create user action.

    Screenshot that shows the Azure Communication Services connector Create user action advanced options.

Emita um token de acesso do usuário

Depois de ter uma identidade dos Serviços de Comunicação, você pode usar a ação Emitir um token de acesso do usuário, para emitir um token de acesso. As etapas a seguir mostrarão como fazer isso:

  1. Adicione uma nova ação e insira a 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.

    Screenshot that shows the Azure Communication Services Identity connector Issue access token action.

  2. Em seguida, você pode usar a saída da 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.

    Screenshot that shows the Azure Communication Services Identity connector Issue access token action, specifying the token scope.

Isso gerará um token de acesso e o tempo de expiração com o escopo especificado.

Revogar tokens de acesso do usuário

Depois de ter uma identidade dos Serviços de Comunicação, você pode usar a ação Emitir um token de acesso do usuário, para revogar um token de acesso. As etapas a seguir mostrarão como fazer isso:

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

    Screenshot that shows the Azure Communication Services Identity connector Revoke access token action.

  2. Especifique a ID do Usuário

    Screenshot that shows the Azure Communication Services Identity connector Revoke access token action input.

Isso revogará todos os tokens de acesso do usuário especificado, não há saídas para essa ação.

Excluir um usuário

Depois de ter uma identidade dos Serviços de Comunicação, você pode usar a ação Emitir um token de acesso do usuário, para excluir um token de acesso. As etapas a seguir mostrarão como fazer isso:

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

    Screenshot that shows the Azure Communication Services Identity connector Delete user action.

  2. Especifique a ID do Usuário

    Screenshot that shows the Azure Communication Services Identity connector Delete user action input.

    Isso removerá o usuário e revogará 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 executar manualmente o fluxo de trabalho, selecione Executar na barra de ferramentas do designer. O fluxo de trabalho deve criar um usuário, emitir um token de acesso para esse usuário, bem como remover e excluir o usuário. Para obter mais informações, examine como executar seu fluxo de trabalho. Você pode verificar as saídas dessas ações, depois que o fluxo de trabalho for executado com êxito.

Usar identidade para monitoramento e métricas

A ID de usuário destina-se a atuar como uma chave primária para logs e métricas coletados por meio do Azure Monitor. Para visualizar todas as chamadas de um usuário específico, por exemplo, você pode configurar sua autenticação de maneira que mapeie uma identidade de Serviços de Comunicação do Azure específica (ou identidades) para um só usuário.

Saiba mais sobre conceitos de autenticação, como chamar o diagnóstico por meio do Log Analyticse as métricas disponíveis para você.

Limpar os recursos

Para limpar e remover uma assinatura dos Serviços de Comunicação, exclua o recurso ou o grupo de recursos. Excluir um grupo de recursos também exclui todos os recursos associados a ele. Para obter mais informações, consulte a seção "Limpar recursos" em Criar e gerenciar recursos dos Serviços de Comunicação.

Para limpar o fluxo de trabalho do aplicativo lógico e os recursos relacionados, leia como limpar os recursos dos Aplicativos Lógicos do Azure.

Próximas etapas

Neste guia de início rápido, você aprendeu a:

  • Emitir tokens de acesso
  • Gerenciar identidades

Talvez seja necessário também:

Próximas etapas

Neste guia de início rápido, você aprendeu a criar um usuário, excluir um usuário, emitir um token de acesso para um usuário e remover o token de acesso do usuário usando o conector de Identidade dos Serviços de Comunicação do Azure. Para saber mais, verifique a documentação do 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 no Power Automate usando os Serviços de Comunicação do Azure.

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