Guia de 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 específica. Você precisará criar tokens de acesso se quiser que seus usuários participem de uma chamada ou thread de bate-papo em seu aplicativo.

Neste início rápido, você aprenderá a 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.

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Crie um recurso de Serviços de Comunicação.
• Instalar a CLI do Azure.

Configuração

Adicionar a extensão

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

az extension add --name communication

Iniciar sessão na CLI do Azure

Você precisará entrar na CLI do Azure. Você pode entrar executando o az login comando do terminal e fornecendo 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 para usar operações AZURE_COMMUNICATION_CONNECTION_STRING de identidade da CLI do Azure sem precisar usar --connection_string para passar na cadeia de conexão. Para configurar uma variável de ambiente, abra uma janela do console e selecione seu sistema operacional nas guias abaixo. Substitua <yourConnectionString> pela cadeia de conexão real.

Windows

Abra uma janela do console e digite o seguinte comando:

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Depois de adicionar a variável de ambiente, poderá ter de reiniciar todos os programas em execução que irão precisar de ler a variável de ambiente, incluindo a janela da consola. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

macOS

Edite o seu .zshrce adicione a variável de ambiente:

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

Depois de adicionar a variável de ambiente, execute source ~/.zshrc a partir da janela da consola para que as alterações entrem em vigor. Se você criou a variável de ambiente com o IDE aberto, talvez seja necessário fechar e reabrir o editor, IDE ou shell para acessar a variável.

Linux

Edite o seu .bash_profilee adicione a variável de ambiente:

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

Depois de adicionar a variável de ambiente, execute source ~/.bash_profile a partir da janela da consola para que as alterações entrem em vigor. Se você criou a variável de ambiente com o IDE aberto, talvez seja necessário fechar e reabrir o editor, IDE ou shell para acessar a variável.

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

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

Windows

Abra uma janela do console e digite o seguinte comando:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Depois de adicionar a variável de ambiente, poderá ter de reiniciar todos os programas em execução que irão precisar de ler a variável de ambiente, incluindo a janela da consola. Por exemplo, se você estiver usando o Visual Studio como editor, reinicie o Visual Studio antes de executar o exemplo.

macOS

Edite o seu .zshrce adicione a variável de ambiente:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Depois de adicionar a variável de ambiente, execute source ~/.zshrc a partir da janela da consola para que as alterações entrem em vigor. Se você criou a variável de ambiente com o IDE aberto, talvez seja necessário fechar e reabrir o editor, IDE ou shell para acessar a variável.

Linux

Edite o seu .bash_profilee adicione a variável de ambiente:

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Depois de adicionar a variável de ambiente, execute source ~/.bash_profile a partir da janela da consola para que as alterações entrem em vigor. Se você criou a variável de ambiente com o IDE aberto, talvez seja necessário fechar e reabrir o editor, IDE ou shell para acessar a variável.

Operações

Criar uma identidade

Para criar tokens de acesso, você precisa de uma identidade. Os Serviços de Comunicação do Azure mantêm um diretório de identidade leve para essa finalidade. Use o user create comando para criar uma nova entrada no diretório com um arquivo Id. A identidade é necessária posteriormente para a emissão de 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 comando a seguir para criar uma identidade dos Serviços de Comunicação e emitir um token de acesso para ela ao mesmo tempo. O scopes parâmetro 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 esta 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 scopes parâmetro 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 esta substituição no código:

• Substitua <yourConnectionString> pela cadeia de conexão.
• Substitua <userId> pelo seu userId.

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 dos usuários do aplicativo. A expires_on propriedade response indica o tempo de vida do token de acesso.

Emitir token de acesso com vários escopos

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

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

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

• Substitua <yourConnectionString> pela cadeia de conexão.
• Substitua <userId> pelo seu userId.

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 dos usuários do aplicativo. A expires_on propriedade response indica o tempo de vida do token de acesso.

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

Use o token get-for-teams-user comando 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 esta substituição no código:

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

Revogar tokens de acesso

Ocasionalmente, 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 se autenticar no seu serviço. O token revoke comando 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 esta substituição no código:

• Substitua <yourConnectionString> pela cadeia de conexão.
• Substitua <userId> pelo seu userId.

Excluir uma identidade

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

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

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

• Substitua <yourConnectionString> pela cadeia de conexão.
• Substitua <userId> pelo seu userId.

Pré-requisitos

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• A versão mais recente do SDK do .NET Core para seu sistema operacional.
• Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Crie um recurso de Serviços de Comunicação.

Código final

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

Configurar o ambiente

Criar um novo aplicativo C#

Em uma janela do Prompt de Comando, como cmd, PowerShell ou Bash, execute o dotnet new comando para criar um novo aplicativo de console com o nome AccessTokensQuickstart. Este comando cria um projeto C# "Hello World" simples com um único arquivo de origem, Program.cs.

dotnet new console -o AccessTokensQuickstart

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

cd AccessTokensQuickstart
dotnet build

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

Instalar o pacote

Enquanto você ainda estiver no diretório do aplicativo, instale a biblioteca de Identidade dos Serviços de Comunicação do Azure para o pacote .NET usando o dotnet add package comando.

dotnet add package Azure.Communication.Identity

Configurar a estrutura do aplicativo

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

1. Abra o arquivo Program.cs em um editor de texto.
2. Adicione uma using diretiva para incluir o Azure.Communication.Identity namespace.
3. Atualize a declaração de método para oferecer suporte a código assíncrono 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 CommunicationIdentityClient com sua cadeia de conexão. O código a seguir, que você adiciona ao Main método, 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" de 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á configurou um aplicativo Microsoft Entra, você pode autenticar 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ê precisa de uma identidade. Os Serviços de Comunicação do Azure mantêm um diretório de identidade leve para essa finalidade. Use o createUser método para criar uma nova entrada no diretório com um arquivo Id. A identidade é necessária posteriormente para a emissão de 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 de aplicativos).

Emitir um token de acesso

Depois de ter uma identidade dos Serviços de Comunicação, use o GetToken método para emitir um token de acesso para ela. O scopes parâmetro define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações suportadas no Modelo de identidade. Você também pode construir uma nova instância de com base em uma representação de cadeia de caracteres de uma identidade do Serviço de communicationUser 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 dos usuários do aplicativo. A expiresOn propriedade 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 tokenExpiresInopcional. 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 CreateUserAndTokenAsync método para criar uma identidade dos Serviços de Comunicação e emitir um token de acesso para ela ao mesmo tempo. O scopes parâmetro 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);

Atualizar um token de acesso

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

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

Revogar tokens de acesso

Ocasionalmente, 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 se autenticar no seu serviço. O RevokeTokensAsync método 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 adicional de tokens de acesso para a identidade. 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 dotnet run comando.

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

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• Node.js versões Ative LTS e Maintenance LTS (8.11.1 e 10.14.1 recomendadas).
• Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Crie um recurso de Serviços de Comunicação.

Código final

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

Configurar o ambiente

Criar uma nova aplicação Node.js

Em uma janela de terminal ou prompt de comando, crie um novo 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 npm install comando para instalar o SDK de Identidade dos Serviços de Comunicação do Azure para JavaScript.

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

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

Configurar a estrutura do aplicativo

1. Crie um arquivo nomeado 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

Instancie com sua cadeia de CommunicationIdentityClient conexão. O código a seguir, que você adiciona ao Main método, 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" de 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á configurou um aplicativo Microsoft Entra, você pode autenticar 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ê precisa de uma identidade. Os Serviços de Comunicação do Azure mantêm um diretório de identidade leve para essa finalidade. Use o createUser método para criar uma nova entrada no diretório com um arquivo Id. A identidade é necessária posteriormente para a emissão de 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 de aplicativos).

Emitir um token de acesso

Use o getToken método para emitir um token de acesso para sua identidade dos Serviços de Comunicação. O scopes parâmetro define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações suportadas no Modelo de identidade. Você também pode construir uma nova instância de um 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 dos usuários do aplicativo. A expiresOn propriedade 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 tokenExpiresInMinutesopcional. 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 createUserAndToken método para criar uma identidade dos Serviços de Comunicação e emitir um token de acesso para ela ao mesmo tempo. O scopes parâmetro define um conjunto de permissões e funções de token de acesso. Novamente, você o cria com o voip escopo.

// 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 expiram, você precisará atualizá-los periodicamente. Atualizar é fácil basta ligar getToken novamente com a mesma identidade que foi usada para emitir os tokens. Você também precisará fornecer os scopes 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, pode ser necessário revogar um token de acesso. Por exemplo, você faria isso quando os usuários do aplicativo alterassem a senha que usam para se autenticar no seu serviço. O revokeTokens método 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 adicional de tokens de acesso para a identidade. 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

Em um 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

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• Python 3.8+.
• Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Crie um recurso de Serviços de Comunicação.

Código final

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

Configurar o ambiente

Criar uma aplicação Python nova

1. Em uma janela de terminal ou 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 e adicionar a estrutura para o programa, incluindo o tratamento básico de exceções. Você adicionará todo o código-fonte deste início rápido a este 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

Enquanto você ainda estiver no diretório do aplicativo, instale o pacote SDK de Identidade dos Serviços de Comunicação do Azure para Python usando o pip install comando.

pip install azure-communication-identity

Autenticar o cliente

Instancie a CommunicationIdentityClient com sua cadeia de conexão. O código a seguir, que você adiciona ao try bloco , 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" de 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á configurou um aplicativo Microsoft Entra, você pode autenticar usando o Microsoft Entra ID.

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

Criar uma identidade

Para criar tokens de acesso, você precisa de uma identidade. Os Serviços de Comunicação do Azure mantêm um diretório de identidade leve para essa finalidade. Use o create_user método para criar uma nova entrada no diretório com um arquivo Id. A identidade é necessária posteriormente para a emissão de 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 de aplicativos).

Emitir um token de acesso

Use o get_token método para emitir um token de acesso para sua identidade dos Serviços de Comunicação. O scopes parâmetro define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações suportadas no Modelo de identidade. Você também pode construir uma nova instância de 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 dos usuários do aplicativo. A expires_on propriedade 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 token_expires_inopcional. 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 create_user_and_token método para criar uma identidade dos Serviços de Comunicação e emitir um token de acesso para ela ao mesmo tempo. O scopes parâmetro 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 CommunicationUserIdentifier objeto 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, 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 se autenticar no seu serviço. O revoke_tokens método 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 adicional de tokens de acesso para a identidade. 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

Em um prompt de console, vá para o diretório que contém o arquivo issue-access-tokens.py e execute o seguinte python comando 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

• Uma conta do Azure com uma subscrição ativa. Crie uma conta gratuitamente.
• Java Development Kit (JDK) versão 8 ou posterior.
• Apache Maven.
• Um recurso ativo dos Serviços de Comunicação e uma cadeia de conexão. Crie um recurso de Serviços de Comunicação.

Código final

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

Configurar o ambiente

Criar uma nova aplicação Java

Em um terminal ou janela de prompt de comando, vá para o diretório onde você deseja criar sua aplicação 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

Você notará que a generate tarefa cria um diretório com o mesmo nome artifactIdde . Neste diretório, o diretório src/main/java contém o código-fonte do projeto, o diretório src/test/java contém a fonte de teste e o arquivo pom.xml é o Project Object Model ou POM do projeto. Este arquivo é usado para parâmetros de configuração do projeto.

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

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 SDK de Identidade dos Serviços de Comunicação, que você usará mais tarde.

Configurar a estrutura do aplicativo

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 no editor.
3. Substitua a System.out.println("Hello world!"); instrução.
4. Adicionar import diretivas.

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, consulte a seção "Armazenar sua cadeia de conexão" de 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 com.azure.core.http.HttpClient interface.

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

// 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 connectionString() método.

// 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 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ê precisa de uma identidade. Os Serviços de Comunicação do Azure mantêm um diretório de identidade leve para essa finalidade. Use o createUser método para criar uma nova entrada no diretório com um arquivo Id.

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

A identidade criada é necessária posteriormente para a emissão de 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 de aplicativos).

Emitir um token de acesso

Use o getToken método para emitir um token de acesso para sua identidade dos Serviços de Comunicação. O scopes parâmetro define um conjunto de permissões e funções de token de acesso. Para obter mais informações, consulte a lista de ações suportadas 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 dos usuários do aplicativo. A expiresAt propriedade 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 tokenExpiresInopcional. 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 um token em uma solicitação

Como alternativa, você pode usar o método 'createUserAndToken' para criar uma nova entrada no diretório com um token exclusivo Id 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 CommunicationUserIdentifier objeto 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, 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 se autenticar no seu serviço. O revokeTokens método 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 adicional de tokens de acesso para a identidade. 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

Vá para o diretório que contém o arquivo pom.xml e, em seguida, compile o projeto usando o seguinte mvn comando:

mvn compile

Em seguida, compile o pacote:

mvn package

Execute o seguinte mvn comando 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

• Um recurso dos Serviços de Comunicação do Azure

Criar os tokens de acesso

No portal do Azure, navegue até a folha Identidades & Tokens de Acesso do Usuário dentro do recurso Serviços de Comunicação.

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

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.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa ou crie uma conta do Azure gratuitamente.

• Um recurso ativo dos Serviços de Comunicação do Azure ou crie um recurso dos Serviços de Comunicação.

• Um recurso ativo de Aplicativos Lógicos do Azure (aplicativo lógico) ou crie um fluxo de trabalho de aplicativo lógico de Consumo com o gatilho que você deseja usar. Atualmente, o conector de Identidade dos Serviços de Comunicação do Azure fornece apenas ações, portanto, seu aplicativo lógico requer um gatilho, no mínimo.

Criar utilizador

Adicione uma nova etapa em seu fluxo de trabalho usando o conector de Identidade dos Serviços de Comunicação do Azure, siga estas etapas no Power Automate com seu 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 Escolha uma operação, insira Identidade dos Serviços de Comunicação. Na lista de ações, selecione Criar um usuário.

   

3. Forneça a cadeia de conexão. Isso pode ser encontrado no Microsoft Azure, dentro do seu Recurso de Serviço de Comunicação do Azure, na opção Chaves do menu > esquerdo Cadeia de Conexão

   

4. Forneça um nome de conexão

5. Clique em Criar

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

   

   

Emitir um token de acesso de usuário

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

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 de usuário.

   

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

   

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

Revogar tokens de acesso de usuário

Depois de ter 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. As etapas a seguir mostrarão como:

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.

   

2. Especifique o ID de usuário

   

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

Eliminar um utilizador

Depois de ter 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. As etapas a seguir mostrarão como:

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.

   

2. Especifique o ID de usuário

   

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

Teste seu aplicativo lógico

Para iniciar manualmente o fluxo de trabalho, na barra de ferramentas do designer, selecione Executar. O fluxo de trabalho deve criar um usuário, emitir um token de acesso para esse usuário, removê-lo e excluir o usuário. Para obter mais informações, consulte 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 coletadas por meio do Azure Monitor. Para exibir todas as chamadas de um usuário, por exemplo, você pode configurar sua autenticação de uma forma que mapeie uma identidade (ou identidades) específica dos Serviços de Comunicação do Azure para um único usuário.

Saiba mais sobre conceitos de autenticação, diagnósticos de chamadas por meio de análises de log e métricas disponíveis para você.

Clean up resources (Limpar recursos)

Para limpar e remover uma assinatura dos 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, consulte a seção "Limpar recursos" de Criar e gerenciar recursos dos Serviços de Comunicação.

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

Próximos passos

Neste início rápido, aprendeu a:

• Emitir tokens de acesso
• Gerenciar identidades

Adicionar chamadas de voz ao seu aplicativo

Você também pode querer:

• Saiba mais sobre autenticação
• Adicionar bate-papo ao seu aplicativo
• Saiba mais sobre a arquitetura de cliente e servidor
• Implantar exemplo de herói de serviço de autenticação confiável

Próximos passos

Neste início rápido, você aprendeu como criar um usuário, excluir um usuário, emitir um token de acesso a 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, consulte a documentação do Azure Communication Services Identity Connector .

Para ver como os tokens são usados por outros conectores, confira como enviar uma mensagem de bate-papo 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.