Início Rápido: configurar e gerenciar tokens de acesso para usuários do Teams

Neste início rápido, você criará um aplicativo de console do .NET para autenticar um usuário do Microsoft 365 usando a MSAL (Biblioteca de Autenticação da Microsoft) e recuperando um token de usuário do Microsoft Entra. Em seguida, esse token será trocado por um token de acesso de um usuário do Teams com o SDK de Identidade dos Serviços de Comunicação do Azure. O token de acesso do usuário do Teams pode ser usado pelo SDK de Chamada dos Serviços de Comunicação para integrar o recurso de chamada como o usuário do Teams.

Observação

Quando estiver em um ambiente de produção, recomendamos implementar esse mecanismo de troca em serviços de back-end, pois as solicitações para uma troca são assinadas com um segredo.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.
• Um recurso e uma cadeia de conexão ativos dos Serviços de Comunicação do Azure. Para obter mais informações, confira Criar um recurso dos Serviços de Comunicação do Azure.
• Uma instância do Microsoft Entra com usuários que tenham uma licença do Teams. Para saber mais, confira Requisitos de licença do Teams.

Introdução

As identidades do Teams são associadas a locatários no Microsoft Entra ID. Seu aplicativo pode ser usado por usuários do mesmo ou de outro locatário. Neste guia de início rápido, você trabalhará com um caso de uso de um multilocatário com vários atores: usuários, desenvolvedores e administradores das empresas fictícias Contoso e Fabrikam. Nesse caso de uso, a Contoso é uma empresa que está criando um SaaS (software como serviço) para a Fabrikam.

As seções a seguir orientarão você pelas etapas para administradores, desenvolvedores e usuários. Os diagramas demonstram o caso de uso de multilocatário. Se estiver trabalhando com um único locatário, execute todas as etapas da Contoso e da Fabrikam em um único locatário.

Ações de administrador

A função Administrador tem permissões estendidas no Microsoft Entra ID. Os membros dessa função podem configurar recursos e ler informações do portal do Azure. No diagrama a seguir, é possível ver todas as ações que devem ser executadas por administradores.

1. O administrador da Contoso cria ou seleciona um aplicativo existente no Microsoft Entra ID. A propriedade Tipos de conta com suporte define se os usuários de vários locatários podem se autenticar no aplicativo. A propriedade URI de redirecionamento redireciona uma solicitação de autenticação bem-sucedida para o servidorda Contoso.
2. O Administrador da Contoso adiciona permissões de API a Teams.ManageCalls e Teams.ManageChats dos Serviços de Comunicação.
3. O Administrador da Contoso permite o fluxo do cliente público para o aplicativo.
4. O Administrador da Contoso cria ou seleciona os serviços de comunicação existentes, que serão usados para autenticar as solicitações de troca. Os tokens de usuário do Microsoft Entra serão trocados por um token de acesso de um usuário do Teams. Para obter mais informações, confira Criar e gerenciar recursos dos Serviços de Comunicação.
5. O Administrador da Fabrikam concede permissões de Teams.ManageCalls e Teams.ManageChats dos Serviços de Comunicação ao aplicativo da Contoso. Essa etapa será necessária somente se o Administrador da Fabrikam puder conceder acesso ao aplicativo com as permissões Teams.ManageCalls e Teams.ManageChats.

Etapa 1: criar um registro de aplicativo do Microsoft Entra ou selecionar um aplicativo do Microsoft Entra

Os usuários devem ser autenticados em aplicativos do Microsoft Entra com as permissões Teams.ManageCalls e Teams.ManageChats do Serviço de Comunicação do Azure. Se não houver um aplicativo existente que deseja usar para este início rápido, poderá criar um novo registro de aplicativo.

As configurações de aplicativo a seguir influenciam a experiência:

• A propriedade Tipos de conta com suporte define se o aplicativo é de locatário único ("Contas somente neste diretório organizacional") ou multilocatário ("Contas em qualquer diretório organizacional"). Para este cenário, é possível usar o multilocatário.
• O URI de redirecionamento define o URI em que a solicitação de autenticação é redirecionada após a autenticação. Para este cenário, é possível usar cliente público/nativo (móvel e desktop) e inserir http://localhost como o URI.

Para obter informações mais detalhadas, confira Registrar um aplicativo na plataforma de identidade da Microsoft.

Quando o aplicativo for registrado, você verá um identificador na visão geral. Esse identificador, a ID de aplicativo (cliente), será usado nas próximas etapas.

Etapa 2: Permitir fluxos de cliente público

No painel Autenticação do aplicativo, você pode ver uma plataforma configurada para Cliente público/nativo (móvel e desktop) com uma URI de redirecionamento apontando para http://localhost. Na parte inferior do painel, você verá um controle de alternância Permitir fluxos de cliente público, o que para este início rápido deve ser definido como Sim.

Etapa 3: adicionar as permissões dos Serviços de Comunicação no aplicativo

O aplicativo precisa declarar as permissões Teams.ManageCalls e Teams.ManageChats para ter acesso aos recursos de chamada do Teams no locatário. O usuário do Teams solicitaria um token de usuário do Microsoft Entra com essa permissão para a troca de tokens.

1. Navegue até o aplicativo do Microsoft Entra no portal do Azure e selecione Permissões de API
2. Selecione Adicionar permissões
3. No menu Adicionar Permissões, selecione Serviços de Comunicação do Azure
4. Selecione as permissões Teams.ManageCalls e Teams.ManageChats e clique em Adicionar permissões.

Etapa 4: Criar ou selecionar um recurso dos Serviços de Comunicação

O recurso dos Serviços de Comunicação será usado para autenticar todas as solicitações de troca de tokens de usuário do Microsoft Entra por um token de acesso de um usuário do Teams. Você pode disparar essa troca usando o SDK de Identidade dos Serviços de Comunicação, que pode ser autenticado com uma chave de acesso ou usando o RBAC (controle de acesso baseado em função) do Azure. Você pode obter a chave de acesso no portal do Azure ou ao configurar o RBAC do Azure no painel Controle de acesso (IAM) por recurso dos Serviços de Comunicação.

Se quiser criar um novo recurso dos Serviços de Comunicação, consulte Criar e gerenciar recursos dos Serviços de Comunicação.

Etapa 5: Fornecer consentimento do administrador

O locatário do Microsoft Entra pode ser configurado para exigir o consentimento do administrador do Microsoft Entra para as permissões Teams.ManageCalls e Teams.ManageChats do aplicativo. Nesse caso, o Administrador do Microsoft Entra deve conceder permissão ao aplicativo Contoso para as permissões Teams.ManageCalls e Teams.ManageChats dos Serviços de Comunicação. O Administrador do Microsoft Entra da Fabrikam fornece consentimento por meio de uma URL exclusiva.

As seguintes funções podem dar consentimento em nome de uma empresa:

• Administrador global
• Administrador de aplicativo
• Administrador do aplicativo de nuvem

Se quiser verificar as funções no portal do Azure, consulte Listar atribuições de função do Azure.

Para construir uma URL de consentimento do administrador, o administrador do Microsoft Entra da Fabrikam segue as seguintes etapas:

1. Na URL https://login.microsoftonline.com/{Tenant_ID}/adminconsent?client_id={Application_ID}, o Administrador substitui {Tenant_ID} pela ID de Locatário da Fabrikam e substitui {Application_ID} pela ID de Aplicativo da Contoso.
2. O Administrador faz logon e concede permissões em nome da organização.

A entidade de serviço do aplicativo da Contoso no locatário da Fabrikam será criada se o consentimento for concedido. O Administrador da Fabrikam pode revisar o consentimento no Microsoft Entra ID seguindo as seguintes etapas:

1. Entre no Portal do Azure como administrador.
2. Acesse o Microsoft Entra ID.
3. No painel Aplicativos empresariais, defina o filtro Tipo de aplicativo como Todos os aplicativos.
4. No campo para filtrar os aplicativos, insira o nome do aplicativo da Contoso.
5. Selecione Aplicar.
6. Selecione a entidade de serviço usando o nome necessário.
7. Acesse o painel Permissões.

Veja que o status das permissões Teams.ManageCalls e Teams.ManageChats dos Serviços de Comunicação foram Concedidas para {Directory_name}.

Se você encontrar o problema "O aplicativo está tentando acessar um serviço '1fd5118e-2576-4263-8130-9503064c837a'(Serviços de Comunicação do Azure) para o qual sua organização '{GUID}' não tem uma entidade de serviço. Entre em contato com sua Administração de TI para examinar a configuração de suas assinaturas de serviço ou consentir que o aplicativo crie a entidade de serviço necessária." seu locatário do Microsoft Entra não tem uma entidade de serviço para o aplicativo Serviços de Comunicação do Azure. Para corrigir esse problema, use o PowerShell como um administrador do Microsoft Entra para se conectar ao seu locatário. Substitua Tenant_ID por uma ID do seu locatário do Microsoft Entra.

Você exigirá Application.ReadWrite.All conforme mostrado abaixo.

Connect-MgGraph -TenantId "Tenant_ID" -Scopes Application.ReadWrite.All

Se o comando não for encontrado, inicie o PowerShell como administrador e instale o pacote do Microsoft Graph.

Install-Module Microsoft.Graph

Em seguida, execute o comando a seguir para adicionar uma entidade de serviço ao seu locatário. Não modifique o GUID da ID do Aplicativo.

New-MgServicePrincipal -AppId "1fd5118e-2576-4263-8130-9503064c837a"

Ações do desenvolvedor

O desenvolvedor da Contoso precisa configurar o aplicativo cliente para autenticar os usuários. Em seguida, o desenvolvedor precisa criar um ponto de extremidade no servidor de back-end para processar o token de usuário do Microsoft Entra após o redirecionamento. Quando o token de usuário do Microsoft Entra é recebido, ele é trocado pelo token de acesso do usuário do Teams e devolvido para o aplicativo cliente.

As ações necessárias do desenvolvedor são mostradas no diagrama a seguir:

1. O desenvolvedor da Contoso configura a MSAL (Biblioteca de Autenticação da Microsoft) para autenticar o usuário para o aplicativo que foi criado pelo Administrador para as permissões Teams.ManageCalls e Teams.ManageChats dos Serviços de Comunicação.
2. O desenvolvedor da Contoso inicializa o SDK da Identidade dos Serviços de Comunicação e troca o token de usuário de entrada do Microsoft Entra pelo token de acesso do usuário do Teams por meio do SDK de identidade. Em seguida, o token de acesso do usuário do Teams é devolvido ao aplicativo cliente.

Ao usar a MSAL, os desenvolvedores podem adquirir tokens de usuário do Microsoft Entra do ponto de extremidade da plataforma de identidade da Microsoft para autenticar usuários e acessar APIs Web seguras. Eles podem ser usados para fornecer acesso seguro aos Serviços de Comunicação. A MSAL dá suporte a várias arquiteturas e plataformas de aplicativos diferentes, incluindo .NET, JavaScript, Java, Python, Android e iOS.

Para obter mais informações sobre como configurar ambientes na documentação pública, consulte Visão geral da biblioteca de autenticação da Microsoft.

Observação

As seções a seguir descrevem como trocar o token de acesso do Microsoft Entra pelo token de acesso do usuário do Teams para o aplicativo de console.

Configurar pré-requisitos

• A versão mais recente do SDK do .NET para o seu sistema operacional.

Código final

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

Configuração

Criar um aplicativo em C#

Em uma janela de console (como cmd, PowerShell ou Bash), use o comando dotnet new para criar um novo aplicativo do console com o nome CommunicationAccessTokensQuickstart. Esse comando cria um projeto simples C# "Olá, Mundo" com um arquivo de origem único: Program.cs.

dotnet new console -o CommunicationAccessTokensQuickstart

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

cd CommunicationAccessTokensQuickstart
dotnet build

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
dotnet add package Microsoft.Identity.Client

Configurar o framework de aplicativos

No diretório do projeto:

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 do método Main para dar suporte ao código assíncrono

Use o seguinte código para começar:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Azure.Communication.Identity;
using Microsoft.Identity.Client;

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

            // Quickstart code goes here
        }
    }
}

Etapa 1: receber o token de usuário do Microsoft Entra e a ID do objeto por meio da biblioteca MSAL

A primeira etapa no fluxo de troca de token é obter um token para seu Teams usando Microsoft.Identity.Client. O código a seguir recupera a ID do cliente e a ID do locatário do Microsoft Entra de variáveis de ambiente chamadas AAD_CLIENT_ID e AAD_TENANT_ID. É essencial configurar o cliente MSAL com a autoridade correta, com base na variável de ambiente AAD_TENANT_ID, para poder recuperar a declaração de ID do Objeto (oid) correspondente a um usuário no locatário da Fabrikam e inicializar a variável userObjectId.

// This code demonstrates how to fetch an AAD client ID and tenant ID 
// from an environment variable.
string appId = Environment.GetEnvironmentVariable("AAD_CLIENT_ID");
string tenantId = Environment.GetEnvironmentVariable("AAD_TENANT_ID");
string authority = $"https://login.microsoftonline.com/{tenantId}";
string redirectUri = "http://localhost";

// Create an instance of PublicClientApplication
var aadClient = PublicClientApplicationBuilder
                .Create(appId)
                .WithAuthority(authority)
                .WithRedirectUri(redirectUri)
                .Build();

List<string> scopes = new() {
    "https://auth.msft.communication.azure.com/Teams.ManageCalls",
    "https://auth.msft.communication.azure.com/Teams.ManageChats"
};

// Retrieve the AAD token and object ID of a Teams user
var result = await aadClient
                        .AcquireTokenInteractive(scopes)
                        .ExecuteAsync();
string teamsUserAadToken =  result.AccessToken;
string userObjectId =  result.UniqueId;

Etapa 2: Inicializar o CommunicationIdentityClient

Inicialize um CommunicationIdentityClient com a sua cadeia de conexão. O código abaixo recupera a cadeia de conexão do recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerenciar a cadeia de conexão do seu recurso.

Adicione o seguinte código ao método Main:

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

Etapa 3: trocar o token de acesso do Microsoft Entra do usuário do Teams para um token de acesso da Identidade de Comunicação

Use o método GetTokenForTeamsUser para emitir um token de acesso para o Teams que pode ser usado com os SDKs Serviços de Comunicação do Azure.

var options = new GetTokenForTeamsUserOptions(teamsUserAadToken, appId, userObjectId);
var accessToken = await client.GetTokenForTeamsUserAsync(options);
Console.WriteLine($"Token: {accessToken.Value.Token}");

Executar o código

Execute o aplicativo do seu diretório de aplicativo com o comando dotnet run.

dotnet run

Configurar pré-requisitos

• Node.js, versões Active LTS e Maintenance LTS (8.11.1 e 10.14.1 recomendadas).

Código final

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

Configuração

Criar um aplicativo Node.js

Abra o terminal ou a janela de comando para criar um diretório para seu aplicativo e navegue até ele.

mkdir communication-access-tokens-quickstart && cd communication-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
npm install @azure/msal-node --save
npm install express --save
npm install dotenv --save

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

Configurar o framework de aplicativos

No diretório do projeto:

1. Abra um arquivo de texto novo no editor de código

2. Adicione uma chamada require para carregar o CommunicationIdentityClient

3. Crie a estrutura do programa, incluindo um tratamento de exceções básico

   const { CommunicationIdentityClient } = require('@azure/communication-identity');    
   const { PublicClientApplication, CryptoProvider } = require('@azure/msal-node');
   const express = require("express");
   
   // You will need to set environment variables in .env
   const SERVER_PORT = process.env.PORT || 80;
   const REDIRECT_URI = `http://localhost:${SERVER_PORT}/redirect`;
   const clientId = process.env['AAD_CLIENT_ID'];
   const tenantId = process.env['AAD_TENANT_ID'];
   
   // Quickstart code goes here
   
   app.listen(SERVER_PORT, () => console.log(`Communication access token application started on ${SERVER_PORT}!`))
   
   

4. Salve o novo arquivo como issue-communication-access-token.js no diretório access-tokens-quickstart.

Etapa 1: receber o token de usuário do Microsoft Entra e a ID do objeto por meio da biblioteca MSAL

A primeira etapa no fluxo de troca de token é obter um token para seu Teams usando Microsoft.Identity.Client. O código a seguir recupera a ID do cliente e a ID do locatário do Microsoft Entra de variáveis de ambiente chamadas AAD_CLIENT_ID e AAD_TENANT_ID. É essencial configurar o cliente MSAL com a autoridade correta, com base na variável de ambiente AAD_TENANT_ID, para poder recuperar a declaração de ID do Objeto (oid) correspondente a um usuário no locatário da Fabrikam e inicializar a variável userObjectId.

// Create configuration object that will be passed to MSAL instance on creation.
const msalConfig = {
    auth: {
        clientId: clientId,
        authority: `https://login.microsoftonline.com/${tenantId}`,
    }
};

// Create an instance of PublicClientApplication
const pca = new PublicClientApplication(msalConfig);
const provider = new CryptoProvider();

const app = express();

let pkceVerifier = "";
const scopes = [
            "https://auth.msft.communication.azure.com/Teams.ManageCalls",
            "https://auth.msft.communication.azure.com/Teams.ManageChats"
        ];

app.get('/', async (req, res) => {
    // Generate PKCE Codes before starting the authorization flow
    const {verifier, challenge} = await provider.generatePkceCodes();
    pkceVerifier = verifier;
    
    const authCodeUrlParameters = {
        scopes: scopes,
        redirectUri: REDIRECT_URI,
        codeChallenge: challenge, 
        codeChallengeMethod: "S256"
    };
    // Get url to sign user in and consent to scopes needed for application
    pca.getAuthCodeUrl(authCodeUrlParameters).then((response) => {
        res.redirect(response);
    }).catch((error) => console.log(JSON.stringify(error)));
});

app.get('/redirect', async (req, res) => {
    // Create request parameters object for acquiring the AAD token and object ID of a Teams user
    const tokenRequest = {
        code: req.query.code,
        scopes: scopes,
        redirectUri: REDIRECT_URI,
        codeVerifier: pkceVerifier,
    };
    // Retrieve the AAD token and object ID of a Teams user
    pca.acquireTokenByCode(tokenRequest).then(async(response) => {
        console.log("Response:", response);
        let teamsUserAadToken = response.accessToken;
        let userObjectId = response.uniqueId;
        //TODO: the following code snippets go here
        res.sendStatus(200);
    }).catch((error) => {
        console.log(error);
        res.status(500).send(error);
    });
});

Etapa 2: Inicializar o CommunicationIdentityClient

Crie a instância de um CommunicationIdentityClient com a sua cadeia de conexão. O código abaixo recupera a cadeia de conexão do recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerenciar a cadeia de conexão do seu recurso.

Adicione o seguinte código ao método then:

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

Etapa 3: trocar o token de acesso do Microsoft Entra do usuário do Teams para um token de acesso da Identidade de Comunicação

Use o método getTokenForTeamsUser para emitir um token de acesso para o Teams que pode ser usado com os SDKs Serviços de Comunicação do Azure.

//Exchange the Azure AD access token of the Teams User for a Communication Identity access token
let accessToken = await identityClient.getTokenForTeamsUser({
    teamsUserAadToken: teamsUserAadToken,
    clientId: clientId,
    userObjectId: userObjectId,
  });
console.log("Token:", accessToken);

Executar o código

Do prompt de um console, navegue até o diretório que contém o arquivo issue-communication-access-token.js e execute o comando node a seguir para executar o aplicativo.

node ./issue-communication-access-token.js

Configurar pré-requisitos

• Python 3.8 e posterior.

Código final

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

Configuração

Criar um novo aplicativo Python

1. Abra o terminal ou a janela de comando para criar um diretório para seu aplicativo e navegue até ele.

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

2. Use um editor de texto para criar um arquivo chamado exchange-communication-access-tokens.py no diretório raiz do projeto e adicione a estrutura do programa, incluindo o tratamento básico de exceções. 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 azure.communication.identity import CommunicationIdentityClient, CommunicationUserIdentifier
   from msal.application import PublicClientApplication
   
   try:
      print("Azure Communication Services - Access Tokens Quickstart")
      # Quickstart code goes here
   except Exception as ex:
      print(f"Exception: {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
pip install msal

Etapa 1: receber o token de usuário do Microsoft Entra e a ID do objeto por meio da biblioteca MSAL

A primeira etapa no fluxo de troca de token é obter um token para seu Teams usando Microsoft.Identity.Client. No portal do Azure, configure o URI de Redirecionamento de seu "aplicativo móvel e desktop" como http://localhost. O código a seguir recupera a ID do cliente e a ID do locatário do Microsoft Entra de variáveis de ambiente chamadas AAD_CLIENT_ID e AAD_TENANT_ID. É essencial configurar o cliente MSAL com a autoridade correta, com base na variável de ambiente AAD_TENANT_ID, para poder recuperar a declaração de ID do Objeto (oid) correspondente a um usuário no locatário da Fabrikam e inicializar a variável user_object_id.

# This code demonstrates how to fetch your Azure AD client ID and tenant ID
# from an environment variable.
client_id = os.environ["AAD_CLIENT_ID"]
tenant_id = os.environ["AAD_TENANT_ID"]
authority = "https://login.microsoftonline.com/%s" % tenant_id

# Create an instance of PublicClientApplication
app = PublicClientApplication(client_id, authority=authority)

scopes = [ 
"https://auth.msft.communication.azure.com/Teams.ManageCalls",
"https://auth.msft.communication.azure.com/Teams.ManageChats"
 ]

# Retrieve the AAD token and object ID of a Teams user
result = app.acquire_token_interactive(scopes)
aad_token =  result["access_token"]
user_object_id = result["id_token_claims"]["oid"] 

Etapa 2: Inicializar o CommunicationIdentityClient

Crie a instância de um CommunicationIdentityClient com a sua cadeia de conexão. O código abaixo recupera a cadeia de conexão do recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerenciar a cadeia de conexão do seu recurso.

Adicione esse código ao bloco try:

# This code demonstrates how to fetch 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)

Etapa 3: trocar o token de acesso do Microsoft Entra do usuário do Teams para um token de acesso da Identidade de Comunicação

Use o método get_token_for_teams_user para emitir um token de acesso para o Teams que pode ser usado com os SDKs Serviços de Comunicação do Azure.

# Exchange the Azure AD access token of the Teams User for a Communication Identity access token
token_result = client.get_token_for_teams_user(aad_token, client_id, user_object_id)
print("Token: " + token_result.token)

Executar o código

Do prompt de um console, navegue até o diretório que contém o arquivo exchange-teams-access-tokens.py e efetue o comando python a seguir para executar o aplicativo.

python ./exchange-communication-access-tokens.py

Configurar pré-requisitos

• JDK (Java Development Kit) versão 8 ou superior.
• Apache Maven.

Código final

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

Configuração

Criar um aplicativo Java

Abra o terminal ou a janela Comando. Navegue até o diretório em que você deseja criar o aplicativo Java. Execute o comando abaixo para gerar o projeto Java no modelo maven-archetype-quickstart.

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

Você observará que a tarefa 'gerar' criou 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 diretório src/test/java directory contém a fonte de teste e o arquivo pom.xml é o POM (Modelo de Objeto do Projeto).

Instalar o pacote

Abra o arquivo pom.xml no seu editor de texto. Adicione os seguintes elementos de dependência ao grupo de dependências.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-communication-identity</artifactId>
        <version>[1.2.0,)</version>
    </dependency>
    <dependency>
      <groupId>com.microsoft.azure</groupId>
      <artifactId>msal4j</artifactId>
      <version>1.11.0</version>
    </dependency>
</dependencies>

Configurar o framework de aplicativos

No diretório do projeto:

1. Navegue até 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 diretivas import

Use o seguinte código para começar:

package com.communication.quickstart;

import com.azure.communication.identity.CommunicationIdentityClient;
import com.azure.communication.identity.CommunicationIdentityClientBuilder;
import com.azure.communication.identity.models.GetTokenForTeamsUserOptions;
import com.azure.core.credential.AccessToken;
import com.microsoft.aad.msal4j.IAuthenticationResult;
import com.microsoft.aad.msal4j.InteractiveRequestParameters;
import com.microsoft.aad.msal4j.PublicClientApplication;

import java.net.URI;
import java.util.HashSet;
import java.util.Set;

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

Etapa 1: receber o token de usuário do Microsoft Entra e a ID do objeto por meio da biblioteca MSAL

A primeira etapa no fluxo de troca de token é obter um token para seu Teams usando Microsoft.Identity.Client. É essencial configurar o cliente MSAL com a autoridade correta, com base na variável tenantId, para poder recuperar a declaração de ID do Objeto (oid) correspondente a um usuário no locatário da Fabrikam e inicializar a variável userObjectId.

// You need to provide your Azure AD client ID and tenant ID
String appId = "<contoso_application_id>";
String tenantId = "<contoso_tenant_id>";
String authority = "https://login.microsoftonline.com/" + tenantId;

// Create an instance of PublicClientApplication
PublicClientApplication pca = PublicClientApplication.builder(appId)
        .authority(authority)
        .build();

String redirectUri = "http://localhost";
Set<String> scope = new HashSet<String>();
scope.add("https://auth.msft.communication.azure.com/Teams.ManageCalls");
scope.add("https://auth.msft.communication.azure.com/Teams.ManageChats");

// Create an instance of InteractiveRequestParameters for acquiring the AAD token and object ID of a Teams user
InteractiveRequestParameters parameters = InteractiveRequestParameters
                    .builder(new URI(redirectUri))
                    .scopes(scope)
                    .build();

// Retrieve the AAD token and object ID of a Teams user
IAuthenticationResult result = pca.acquireToken(parameters).get();
String teamsUserAadToken = result.accessToken();
String[] accountIds = result.account().homeAccountId().split("\\.");
String userObjectId = accountIds[0];
System.out.println("Teams token: " + teamsUserAadToken);

Etapa 2: Inicializar o CommunicationIdentityClient

Crie uma instância de um CommunicationIdentityClient com a chave de acesso e o ponto de extremidade do recurso. Saiba como gerenciar a cadeia de conexão do seu recurso. Além disso, você pode inicializar o cliente com qualquer cliente HTTP personalizado que implemente a interface com.azure.core.http.HttpClient.

Adicione o seguinte código ao método main:

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

// Instantiate the identity client
CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
    .connectionString(connectionString)
    .buildClient();

Etapa 3: trocar o token de acesso do Microsoft Entra do usuário do Teams para um token de acesso da Identidade de Comunicação

Use o método getTokenForTeamsUser para emitir um token de acesso para o Teams que pode ser usado com os SDKs Serviços de Comunicação do Azure.

// Exchange the Azure AD access token of the Teams User for a Communication Identity access token
GetTokenForTeamsUserOptions options = new GetTokenForTeamsUserOptions(teamsUserAadToken, appId, userObjectId);
var accessToken = communicationIdentityClient.getTokenForTeamsUser(options);
System.out.println("Token: " + accessToken.getToken());

Executar o código

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

Em seguida, compile o pacote.

mvn package

Execute o comando mvn a seguir para executar o aplicativo.

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

Ações do usuário

O usuário representa os usuários da Fabrikam do aplicativo da Contoso. A experiência do usuário é mostrada no seguinte diagrama:

1. O usuário da Fabrikam usa o aplicativo cliente da Contoso e é solicitado a autenticar.
2. O aplicativo cliente da Contoso usa a MSAL para autenticar o usuário no locatário do Microsoft Entra da Fabrikam para o aplicativo da Contoso com as permissões Teams.ManageCalls e Teams.ManageChats dos Serviços de Comunicação.
3. A autenticação é redirecionada para o servidor conforme definido na propriedade URI de redirecionamento na. MSAL e no aplicativo da Contoso.
4. O servidor da Contoso troca o token de usuário do Microsoft Entra pelo token de acesso do usuário do Teams usando o SDK de Identidade dos Serviços de Comunicação e retorna o token de acesso do usuário do Teams para o aplicativo cliente.

Com um token de acesso de usuário do Teams válido no aplicativo cliente, os desenvolvedores podem integrar o SDK de Chamada dos Serviços de Comunicação e gerenciar chamadas como o usuário do Teams.

Próximas etapas

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

• Criar e configurar um aplicativo no Microsoft Entra ID.
• Usar a MSAL (Biblioteca de Autenticação da Microsoft) para emitir um token de usuário do Microsoft Entra.
• Usar o SDK da Identidade dos Serviços de Comunicação para trocar o token de usuário do Microsoft Entra por um token de acesso de usuário do Teams.

Criar um serviço de autenticação confiável para usuários do TeamsFazer uma chamada como usuários do Teams a um usuário do Teams

Saiba mais sobre os seguintes conceitos:

• Casos de uso de comunicação como usuário do Teams
• Suporte dos Serviços de Comunicação do Azure às identidades do Teams
• Interoperabilidade do Teams
• Autenticação de locatário único e multilocatário para usuários do Teams
• Criar e gerenciar tokens de acesso de comunicação para usuários do Teams em um SPA (aplicativo de página única)