Démarrage rapide : configurer et gérer des jetons d’accès pour les utilisateurs Teams

Configurer les prérequis

• Dernière version du SDK .NET pour votre système d’exploitation.

Code final

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Configurer

Créer une application C#

Dans une fenêtre de console (par exemple cmd, PowerShell ou Bash), utilisez la commande dotnet new pour créer une application console avec le nom CommunicationAccessTokensQuickstart. Cette commande crée un projet C# « Hello World » simple avec un seul fichier source : Program.cs.

dotnet new console -o CommunicationAccessTokensQuickstart

Remplacez votre répertoire par le dossier d’application que vous venez de créer, puis utilisez la commande dotnet build pour compiler votre application.

cd CommunicationAccessTokensQuickstart
dotnet build

Installer le package

Alors que vous êtes toujours dans le répertoire de l’application, installez le package de la bibliothèque Azure Communication Services Identity pour .NET à l’aide de la commande dotnet add package.

dotnet add package Azure.Communication.Identity
dotnet add package Microsoft.Identity.Client

Configurer le framework d’application

À partir du répertoire de projet :

1. Ouvrez le fichier Program.cs dans un éditeur de texte
2. Ajoutez une directive using pour inclure l’espace de noms Azure.Communication.Identity
3. Mettez à jour la déclaration de méthode Main pour prendre en charge le code asynchrone

Utilisez le code suivant pour commencer :

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

Étape 1 : obtenir le jeton utilisateur Microsoft Entra et l’ID d’objet via la bibliothèque MSAL

La première étape du flux d’échange de jetons consiste à obtenir un jeton pour votre utilisateur Teams à l’aide de Microsoft.Identity.Client. Le code ci-dessous récupère l’ID client Microsoft Entra et l’ID de locataire à partir de variables d’environnement nommées AAD_CLIENT_ID et AAD_TENANT_ID. Il est essentiel de configurer le client MSAL avec l’autorité appropriée, à partir de la variable d’environnement AAD_TENANT_ID, pour pouvoir récupérer la revendication de l’ID d’objet (oid) correspondant à un utilisateur dans le locataire de Fabrikam, et initialiser la variable 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;

Étape 2 : Initialiser CommunicationIdentityClient

Initialisez un CommunicationIdentityClient avec votre chaîne de connexion. Le code ci-dessous récupère la chaîne de connexion de la ressource à partir d’une variable d’environnement nommée COMMUNICATION_SERVICES_CONNECTION_STRING. Découvrez comment gérer la chaîne de connexion de la ressource.

Ajoutez le code suivant à la méthode 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);

Étape 3 : échanger le jeton d’accès Microsoft Entra de l’utilisateur Teams contre un jeton d’accès d’identité Communication

Utilisez la méthode GetTokenForTeamsUser afin d’émettre, pour l’utilisateur Teams, un jeton d’accès qui peut être utilisé avec les SDK Azure Communication Services.

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

Exécuter le code

Exécutez l’application à partir de votre répertoire d’application avec la commande dotnet run.

dotnet run

Configurer les prérequis

• Node.js versions Active LTS et Maintenance LTS (8.11.1 et 10.14.1 recommandées).

Code final

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Configurer

Créer une application Node.js

Ouvrez votre fenêtre de terminal ou de commande, créez un répertoire pour votre application, puis accédez-y.

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

Exécutez npm init -y pour créer un fichier package.json avec les paramètres par défaut.

npm init -y

Installer le package

Utilisez la commande npm install pour installer le kit de développement logiciel (SDK) Azure Communication Services Identity pour JavaScript.

npm install @azure/communication-identity@latest --save
npm install @azure/msal-node --save
npm install express --save
npm install dotenv --save

L’option --save liste la bibliothèque comme dépendance dans votre fichier package.json.

Configurer le framework d’application

À partir du répertoire de projet :

1. Ouvrez un nouveau fichier texte dans votre éditeur de code

2. Ajoutez un appel require pour charger CommunicationIdentityClient

3. Créer la structure du programme, y compris la gestion des exceptions de base

   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. Enregistrez le nouveau fichier sous issue-communication-access-token.js dans le répertoire access-tokens-quickstart.

Étape 1 : obtenir le jeton utilisateur Microsoft Entra et l’ID d’objet via la bibliothèque MSAL

La première étape du flux d’échange de jetons consiste à obtenir un jeton pour votre utilisateur Teams à l’aide de Microsoft.Identity.Client. Le code ci-dessous récupère l’ID client Microsoft Entra et l’ID de locataire à partir de variables d’environnement nommées AAD_CLIENT_ID et AAD_TENANT_ID. Il est essentiel de configurer le client MSAL avec l’autorité appropriée, à partir de la variable d’environnement AAD_TENANT_ID, pour pouvoir récupérer la revendication de l’ID d’objet (oid) correspondant à un utilisateur dans le locataire de Fabrikam, et initialiser la variable 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);
    });
});

Étape 2 : Initialiser CommunicationIdentityClient

Instanciez un CommunicationIdentityClient avec votre chaîne de connexion. Le code ci-dessous récupère la chaîne de connexion de la ressource à partir d’une variable d’environnement nommée COMMUNICATION_SERVICES_CONNECTION_STRING. Découvrez comment gérer la chaîne de connexion de la ressource.

Ajoutez le code suivant à la méthode 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);

Étape 3 : échanger le jeton d’accès Microsoft Entra de l’utilisateur Teams contre un jeton d’accès d’identité Communication

Utilisez la méthode getTokenForTeamsUser afin d’émettre, pour l’utilisateur Teams, un jeton d’accès qui peut être utilisé avec les SDK Azure Communication Services.

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

Exécuter le code

À partir d’une invite de console, accédez au répertoire contenant le fichier issue-communication-access-token.js, puis exécutez la commande node suivante pour exécuter l’application.

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

Configurer les prérequis

• Python 3.8+.

Code final

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Configurer

Créer une application Python

1. Ouvrez votre fenêtre de terminal ou de commande, créez un répertoire pour votre application, puis accédez-y.

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

2. Utilisez un éditeur de texte pour créer un fichier appelé exchange-communication-access-tokens.py dans le répertoire racine du projet, puis ajoutez la structure du programme, notamment la gestion des exceptions de base. Dans les sections suivantes, vous ajouterez l’ensemble du code source de ce guide de démarrage rapide dans ce fichier.

   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}")
   

Installer le package

Toujours dans le répertoire de l’application, installez le package du kit de développement logiciel (SDK) Azure Communication Services Identity pour Python à l’aide de la commande pip install.

pip install azure-communication-identity
pip install msal

Étape 1 : obtenir le jeton utilisateur Microsoft Entra et l’ID d’objet via la bibliothèque MSAL

La première étape du flux d’échange de jetons consiste à obtenir un jeton pour votre utilisateur Teams à l’aide de Microsoft.Identity.Client. Dans le portail Azure, configurez l’URI de redirection de votre « Application mobile et de bureau » en tant que http://localhost. Le code ci-dessous récupère l’ID client Microsoft Entra et l’ID de locataire à partir de variables d’environnement nommées AAD_CLIENT_ID et AAD_TENANT_ID. Il est essentiel de configurer le client MSAL avec l’autorité appropriée, à partir de la variable d’environnement AAD_TENANT_ID, pour pouvoir récupérer la revendication de l’ID d’objet (oid) correspondant à un utilisateur dans le locataire de Fabrikam, et initialiser la variable 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"] 

Étape 2 : Initialiser CommunicationIdentityClient

Instanciez un CommunicationIdentityClient avec votre chaîne de connexion. Le code ci-dessous récupère la chaîne de connexion de la ressource à partir d’une variable d’environnement nommée COMMUNICATION_SERVICES_CONNECTION_STRING. Découvrez comment gérer la chaîne de connexion de la ressource.

Ajoutez ce code dans le bloc 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)

Étape 3 : échanger le jeton d’accès Microsoft Entra de l’utilisateur Teams contre un jeton d’accès d’identité Communication

Utilisez la méthode get_token_for_teams_user afin d’émettre, pour l’utilisateur Teams, un jeton d’accès qui peut être utilisé avec les SDK Azure Communication Services.

# 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)

Exécuter le code

À partir d’une invite de console, accédez au répertoire contenant le fichier exchange-teams-access-tokens.py, puis exécutez la commande python suivante pour exécuter l’application.

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

Configurer les prérequis

• Java Development Kit (JDK) version 8 ou ultérieure.
• Apache Maven.

Code final

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Configurer

Créer une application Java

Ouvrez votre fenêtre de terminal ou de commande. Accédez au répertoire dans lequel vous souhaitez créer votre application Java. Exécutez la commande ci-dessous pour générer le projet Java à partir du modèle maven-archetype-quickstart.

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

Vous remarquerez que la tâche « generate » a créé un répertoire portant le même nom que l’artifactId. Sous ce répertoire, le répertoire src/main/java contient le code source du projet, le src/test/java directory contient la source de test et le fichier pom.xml est le modèle objet du projet (POM).

Installer le package

Ouvrez le fichier pom.xml dans votre éditeur de texte. Ajoutez les éléments de dépendance suivants au groupe de dépendances.

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

Configurer le framework d’application

À partir du répertoire de projet :

1. Accédez au répertoire /src/main/java/com/communication/quickstart.
2. Ouvrez le fichier App.java dans votre éditeur.
3. Remplacez l’instruction System.out.println("Hello world!");
4. Ajoutez des directives import.

Utilisez le code suivant pour commencer :

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

Étape 1 : obtenir le jeton utilisateur Microsoft Entra et l’ID d’objet via la bibliothèque MSAL

La première étape du flux d’échange de jetons consiste à obtenir un jeton pour votre utilisateur Teams à l’aide de Microsoft.Identity.Client. Il est essentiel de configurer le client MSAL avec l’autorité appropriée, à partir de la variable tenantId, pour pouvoir récupérer la revendication de l’ID d’objet (oid) correspondant à un utilisateur dans le locataire de Fabrikam, et initialiser la variable 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);

Étape 2 : Initialiser CommunicationIdentityClient

Instanciez un CommunicationIdentityClient avec la clé d’accès et le point de terminaison de votre ressource. Découvrez comment gérer la chaîne de connexion de la ressource. En outre, vous pouvez initialiser le client avec n’importe quel client HTTP personnalisé qui implémente l’interface com.azure.core.http.HttpClient.

Ajoutez le code suivant à la méthode 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();

Étape 3 : échanger le jeton d’accès Microsoft Entra de l’utilisateur Teams contre un jeton d’accès d’identité Communication

Utilisez la méthode getTokenForTeamsUser afin d’émettre, pour l’utilisateur Teams, un jeton d’accès qui peut être utilisé avec les SDK Azure Communication Services.

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

Exécuter le code

Accédez au répertoire contenant le fichier pom.xml, puis compilez le projet à l’aide de la commande mvn compile.

Ensuite, générez le package.

mvn package

Exécutez la commande mvn suivante pour exécuter l’application.

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