Partilhar via


Guia de 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 .NET para autenticar um usuário do Microsoft 365 usando a Biblioteca de Autenticação da Microsoft (MSAL) e recuperando um token de usuário do Microsoft Entra. Em seguida, você trocará esse token por um token de acesso do usuário do Teams com o SDK de Identidade dos Serviços de Comunicação do Azure. O token de acesso para o usuário do Teams pode ser usado pelo SDK de Chamada dos Serviços de Comunicação para integrar o recurso de chamada como usuário do Teams.

Nota

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

Pré-requisitos

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

Introdução

As identidades das equipes são vinculadas aos locatários no Microsoft Entra ID. Seu aplicativo pode ser usado por usuários do mesmo ou de outro locatário. Neste início rápido, você trabalhará em um caso de uso 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 software como serviço (SaaS) para a Fabrikam.

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

Ações do 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, você pode ver todas as ações que precisam ser executadas pelos administradores.

Ações do administrador para habilitar o suporte dos Serviços de Comunicação do Azure para identidades do Teams.

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

Etapa 1: Criar um registro de aplicativo Microsoft Entra ou selecionar um aplicativo Microsoft Entra

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

As seguintes configurações do aplicativo influenciam a experiência:

  • A propriedade Tipos de conta suportados define se o aplicativo é locatário único ("Contas somente neste diretório organizacional") ou multilocatário ("Contas em qualquer diretório organizacional"). Para esse cenário, você pode usar multilocatário.
  • O URI de redirecionamento define o URI para o qual a solicitação de autenticação é redirecionada após a autenticação. Para esse cenário, você pode usar o cliente/nativo público (mobile & desktop) e inserir http://localhost como o URI.

Para obter informações mais detalhadas, consulte Registrar um aplicativo com a plataforma de identidade da Microsoft.

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

Etapa 2: Permitir fluxos de clientes públicos

No painel Autenticação do seu aplicativo, você pode ver uma plataforma configurada para Cliente público/nativo (móvel ou desktop) com um URI de redirecionamento apontando para http://localhost. Na parte inferior do painel, você verá um controle de alternância Permitir fluxos de clientes públicos, 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 deve 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 estaria solicitando um token de usuário do Microsoft Entra com essa permissão para troca de tokens.

  1. Navegue até seu aplicativo 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, em seguida, selecione Adicionar permissões

Adicione a permissão Teams.ManageCalls e Teams.ManageChats ao aplicativo Microsoft Entra criado na etapa anterior.

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

Seu recurso de Serviços de Comunicação é usado para autenticar todas as solicitações de troca de token de usuário do Microsoft Entra por um token de acesso de 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 controle de acesso baseado em função do Azure (Azure RBAC). Você pode obter a chave de acesso no portal do Azure ou configurando 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.

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ões ao aplicativo Contoso para Serviços de Comunicação Teams.ManageCalls e Teams.ManageChats. O Administrador do Microsoft Entra da Fabrikam fornece consentimento através de um URL exclusivo.

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

  • Administrador Global do
  • Administrador da aplicação
  • Administração de aplicativos na nuvem

Se você quiser verificar 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 executa as seguintes etapas:

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

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

  1. Inicie sessão no portal do Azure como administrador.
  2. Aceda ao Microsoft Entra ID.
  3. No painel Aplicativos corporativos, defina o filtro Tipo de aplicativo como Todos os aplicativos.
  4. No campo para filtrar os aplicativos, insira o nome do aplicativo Contoso.
  5. Selecione Aplicar.
  6. Selecione a entidade de serviço usando o nome necessário.
  7. Vá para o painel Permissões .

Você pode ver que o status das permissões Teams.ManageCalls e Teams.ManageChats dos Serviços de Comunicação são Concedidas para {Directory_name}.

Se você se deparar com 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 o administrador de TI para revisar 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 administrador do Microsoft Entra para se conectar ao seu locatário. Substitua Tenant_ID por uma ID do seu arrendamento do Microsoft Entra.

Você precisará de Application.ReadWrite.All como mostrado abaixo.

Captura de tela mostrando o aplicativo Read Write All.

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 seguinte comando para adicionar uma entidade de serviço ao seu locatário. Não modifique o GUID do 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 usuários. Em seguida, o desenvolvedor precisa criar um ponto de extremidade no servidor 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 retornado ao aplicativo cliente.

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

Diagrama de ações do desenvolvedor para habilitar o suporte dos Serviços de Comunicação do Azure para identidades do Teams.

  1. O desenvolvedor da Contoso configura a Biblioteca de Autenticação da Microsoft (MSAL) para autenticar o usuário para o aplicativo que foi criado anteriormente pelas permissões Administrator for Communication Services Teams.ManageCalls e Teams.ManageChats.
  2. O desenvolvedor da Contoso inicializa o SDK de 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. O token de acesso do usuário do Teams é então retornado ao aplicativo cliente.

Usando o 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 da Web seguras. Ele pode ser usado para fornecer acesso seguro aos Serviços de Comunicação. O MSAL suporta muitas 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.

Nota

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

Código final

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

Configurar

Criar um novo aplicativo C#

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

dotnet new console -o CommunicationAccessTokensQuickstart

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

cd CommunicationAccessTokensQuickstart
dotnet build

Instalar o pacote

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

Configurar a estrutura do aplicativo

No diretório do projeto:

  1. Abrir Program.cs arquivo em um editor de texto
  2. Adicionar uma using diretiva para incluir o Azure.Communication.Identity namespace
  3. Atualizar a declaração de método para suportar código assíncrono Main

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 e a ID do objeto do Microsoft Entra por meio da biblioteca MSAL

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

// 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 sua cadeia de conexão. O código abaixo recupera a cadeia de conexão para o recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerir a cadeia de ligaçã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 por um token de acesso de identidade de comunicação

Use o GetTokenForTeamsUser método 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.

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 a partir do diretório do aplicativo com o dotnet run comando.

dotnet run

Configurar pré-requisitos

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

Código final

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

Configurar

Criar um novo aplicativo Node.js

Abra o terminal ou a janela de comando, crie um novo 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 package.json arquivo 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
npm install @azure/msal-node --save
npm install express --save
npm install dotenv --save

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

Configurar a estrutura do aplicativo

No diretório do projeto:

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

  2. Adicionar uma require chamada para carregar o CommunicationIdentityClient

  3. Criar a estrutura para o programa, incluindo o tratamento básico de exceções

    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 access-tokens-quickstart diretório.

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

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

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

Instancie a CommunicationIdentityClient com sua cadeia de conexão. O código abaixo recupera a cadeia de conexão para o recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerir a cadeia de ligaçã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 por um token de acesso de identidade de comunicação

Use o getTokenForTeamsUser método 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.

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

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

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

Configurar pré-requisitos

Código final

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

Configurar

Criar uma aplicação Python nova

  1. Abra o terminal ou a janela de comando, crie um novo 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 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 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

Enquanto 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
pip install msal

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

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

# 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

Instancie a CommunicationIdentityClient com sua cadeia de conexão. O código abaixo recupera a cadeia de conexão para o recurso de uma variável de ambiente chamada COMMUNICATION_SERVICES_CONNECTION_STRING. Saiba como gerir a cadeia de ligação do seu recurso.

Adicione este código dentro do try bloco:

# 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 por um token de acesso de identidade de comunicação

Use o get_token_for_teams_user método 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.

# 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

Em um prompt do console, navegue até o diretório que contém o arquivo exchange-teams-access-tokens.py e execute o seguinte python comando para executar o aplicativo.

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

Configurar pré-requisitos

Código final

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

Configurar

Criar uma nova aplicação Java

Abra o terminal ou a janela de comando. Navegue até o diretório onde você gostaria de criar seu aplicativo Java. Execute o comando abaixo para gerar o projeto Java a partir do maven-archetype-quickstart modelo.

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

Você notará que a tarefa 'gerar' criou um diretório com o mesmo nome do artifactId. Neste diretório, o src/main/java diretório contém o código-fonte do projeto, o src/test/java directory contém a fonte de teste e o pom.xml arquivo é o Project Object Model ou POM do projeto.

Instalar o pacote

Abra o arquivo no editor de pom.xml 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 a estrutura do aplicativo

No diretório do projeto:

  1. Navegue para o diretório /src/main/java/com/communication/quickstart
  2. Abra o App.java arquivo 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.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 e a ID do objeto do Microsoft Entra por meio da biblioteca MSAL

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

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

Instancie um CommunicationIdentityClient com a chave de acesso e o ponto de extremidade do seu recurso. Saiba como gerir a cadeia de ligação do seu recurso. Além disso, você pode inicializar o cliente com qualquer cliente HTTP personalizado que implementa a com.azure.core.http.HttpClient interface.

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 por um token de acesso de identidade de comunicação

Use o getTokenForTeamsUser método 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.

// 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 pom.xml arquivo e compile o projeto usando o mvn compile comando.

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ções do utilizador

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

Diagrama de ações do usuário para habilitar o suporte dos Serviços de Comunicação do Azure para identidades do Teams.

  1. O usuário da Fabrikam usa o aplicativo cliente da Contoso e é solicitado a autenticar.
  2. O aplicativo cliente da Contoso usa o MSAL para autenticar o usuário no locatário do Microsoft Entra da Fabrikam para o aplicativo 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 Redirecionar URI no MSAL e no aplicativo Contoso.
  4. O servidor 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 válido para o usuário do Teams no aplicativo cliente, os desenvolvedores podem integrar o SDK de Chamada dos Serviços de Comunicação e gerenciar chamadas como usuário do Teams.

Próximos passos

Neste início rápido, aprendeu a:

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

Conheça os seguintes conceitos: