Démarrage rapide : Créer et gérer des jetons d’accès

Les jetons d’accès permettent aux Kits de développement logiciel (SDK) d’Azure Communication Services de s’authentifier directement auprès d’Azure Communication Services en tant qu’identité particulière. Vous devrez créer des jetons d’accès si vous voulez que vos utilisateurs rejoignent un appel ou une conversation dans votre application.

Dans ce guide de démarrage rapide, vous allez apprendre à utiliser les kits de développement logiciel (SDK) Azure Communication Services pour créer des identités et gérer vos jetons d’accès. Pour les cas d’usage en production, nous vous recommandons de générer des jetons d’accès sur un service côté serveur.

Prérequis

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Une ressource Communication Services active et la chaîne de connexion. Créer une ressource Communication Services
• Installez Azure CLI.

Configuration

Ajouter l’extension

Ajoutez l’extension Azure Communication Services pour Azure CLI à l’aide de la commande az extension.

az extension add --name communication

Connectez-vous à Azure CLI

Vous devez vous connecter à Azure CLI. Vous pouvez vous connecter en exécutant la commande az login à partir du terminal et fournir vos informations d’identification.

(Facultatif) Utilisez les opérations d’identité Azure CLI sans passer dans une chaîne de connexion

Vous pouvez configurer la variable d’environnement AZURE_COMMUNICATION_CONNECTION_STRING pour utiliser les opérations d’identité Azure CLI sans avoir à utiliser --connection_string pour passer dans la chaîne de connexion. Pour configurer une variable d’environnement, ouvrez une fenêtre de console, puis sélectionnez votre système d’exploitation dans les onglets ci-dessous. Remplacez <yourConnectionString> par votre chaîne de connexion.

Windows

Ouvrez une fenêtre de console et entrez la commande suivante :

setx AZURE_COMMUNICATION_CONNECTION_STRING "<yourConnectionString>"

Après avoir ajouté la variable d’environnement, vous devrez peut-être redémarrer tous les programmes en cours d’exécution qui devront la lire, y compris la fenêtre de console. Par exemple, si vous utilisez Visual Studio comme éditeur, redémarrez Visual Studio avant d’exécuter l’exemple.

macOS

Modifiez votre profil .zshrc et ajoutez la variable d’environnement :

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

Après avoir ajouté la variable d’environnement, exécutez source ~/.zshrc depuis la fenêtre de console pour appliquer les changements. Si vous avez créé la variable d’environnement avec votre IDE ouvert, vous devrez peut-être fermer et rouvrir l’éditeur, l’IDE ou l’interpréteur de commandes pour accéder à la variable.

Linux

Modifiez votre profil .bash_profile et ajoutez la variable d’environnement :

export AZURE_COMMUNICATION_CONNECTION_STRING="<yourConnectionString>"

Après avoir ajouté la variable d’environnement, exécutez source ~/.bash_profile depuis la fenêtre de console pour appliquer les changements. Si vous avez créé la variable d’environnement avec votre IDE ouvert, vous devrez peut-être fermer et rouvrir l’éditeur, l’IDE ou l’interpréteur de commandes pour accéder à la variable.

Stocker votre jeton d’accès dans une variable d’environnement

Pour configurer une variable d’environnement, ouvrez une fenêtre de console, puis sélectionnez votre système d’exploitation dans les onglets ci-dessous. Remplacez <yourAccessToken> par votre jeton d’accès réel.

Windows

Ouvrez une fenêtre de console et entrez la commande suivante :

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Après avoir ajouté la variable d’environnement, vous devrez peut-être redémarrer tous les programmes en cours d’exécution qui devront la lire, y compris la fenêtre de console. Par exemple, si vous utilisez Visual Studio comme éditeur, redémarrez Visual Studio avant d’exécuter l’exemple.

macOS

Modifiez votre profil .zshrc et ajoutez la variable d’environnement :

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Après avoir ajouté la variable d’environnement, exécutez source ~/.zshrc depuis la fenêtre de console pour appliquer les changements. Si vous avez créé la variable d’environnement avec votre IDE ouvert, vous devrez peut-être fermer et rouvrir l’éditeur, l’IDE ou l’interpréteur de commandes pour accéder à la variable.

Linux

Modifiez votre profil .bash_profile et ajoutez la variable d’environnement :

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Après avoir ajouté la variable d’environnement, exécutez source ~/.bash_profile depuis la fenêtre de console pour appliquer les changements. Si vous avez créé la variable d’environnement avec votre IDE ouvert, vous devrez peut-être fermer et rouvrir l’éditeur, l’IDE ou l’interpréteur de commandes pour accéder à la variable.

Opérations

Créer une identité

Pour créer des jetons d’accès, vous avez besoin d’une identité. Azure Communication Services gère un répertoire LID (Lightweight Identity Directory) à cet effet. Utilisez la commande user create pour créer une entrée dans l’annuaire avec une valeur Id unique. L’identité sera demandée ultérieurement pour émettre des jetons d’accès.

az communication identity user create --connection-string "<yourConnectionString>"

• Remplacez <yourConnectionString> par votre chaîne de connexion.

Créer une identité et émettre un jeton d’accès dans la même requête

Exécutez la commande suivante pour créer une identité Communication Services et émettre un jeton d’accès pour celle-ci en même temps. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Pour plus d’informations, consultez la liste des actions prises en charge dans S’authentifier auprès d’Azure Communication Services.

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

Effectuez ce remplacement dans le code :

• Remplacez <yourConnectionString> par votre chaîne de connexion.

Émettre des jetons d’accès

Exécutez la commande pour émettre un jeton d’accès pour votre identité Communication Services. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Pour plus d’informations, consultez la liste des actions prises en charge dans S’authentifier auprès d’Azure Communication Services.

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

Effectuez ce remplacement dans le code :

• Remplacez <yourConnectionString> par votre chaîne de connexion.
• Remplacez <userId> par votre userId.

Les jetons d’accès sont des informations d’identification à durée de vie courte, qui doivent être réémises. Ne pas le faire peut entraîner une interruption expérimentée par les utilisateurs de votre application. La propriété de réponse expires_on indique la durée de vie du jeton d’accès.

Émettre un jeton d’accès avec plusieurs étendues

Exécutez la commande suivante pour émettre un jeton d’accès avec plusieurs étendues pour votre identité Communication Services. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Pour plus d’informations, consultez la liste des actions prises en charge dans le modèle d’identité.

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

Effectuez ce remplacement dans le code :

• Remplacez <yourConnectionString> par votre chaîne de connexion.
• Remplacez <userId> par votre userId.

Les jetons d’accès sont des informations d’identification à durée de vie courte, qui doivent être réémises. Ne pas le faire peut entraîner une interruption expérimentée par les utilisateurs de votre application. La propriété de réponse expires_on indique la durée de vie du jeton d’accès.

Échanger un jeton d’accès Microsoft Entra de l’utilisateur Teams contre un jeton d’accès de l’identité de communication

Utilisez la commande token get-for-teams-user afin d’émettre un jeton d’accès pour l’utilisateur Teams qui peut être utilisé avec les SDK Azure Communication Services.

az communication identity token get-for-teams-user --aad-token "<yourAadToken>" --client "<yourAadApplication>" --aad-user "<yourAadUser>" --connection-string "<yourConnectionString>"

Effectuez ce remplacement dans le code :

• Remplacez <yourConnectionString> par votre chaîne de connexion.
• Remplacez <yourAadUser> par votre userId Microsoft Entra.
• Remplacez <yourAadApplication> par l’ID de votre application Microsoft Entra.
• Remplacez <yourAadToken> par votre jeton d’accès Microsoft Entra.

Révoquer des jetons d’accès

Vous devrez peut-être parfois révoquer explicitement un jeton d’accès. Par exemple, vous pouvez le faire lorsque les utilisateurs de l’application modifient le mot de passe qu’ils utilisent pour s’authentifier auprès de votre service. La commande token revoke invalide tous les jetons d’accès actifs qui ont été émis pour l’identité.

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

Effectuez ce remplacement dans le code :

• Remplacez <yourConnectionString> par votre chaîne de connexion.
• Remplacez <userId> par votre userId.

Supprimer une identité

Lorsque vous supprimez une identité, vous révoquez tous les jetons d’accès actifs et vous empêchez les nouvelles émissions de jetons d’accès pour l’identité. Cela supprime également tout le contenu persistant associé à l’identité.

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

Effectuez ce remplacement dans le code :

• Remplacez <yourConnectionString> par votre chaîne de connexion.
• Remplacez <userId> par votre userId.

Prérequis

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Dernière version du kit SDK .NET Core pour votre système d’exploitation.
• Une ressource Communication Services active et la chaîne de connexion. Créez une ressource Communication Services.

Code final

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

Configurer votre environnement

Créer une application C#

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

dotnet new console -o AccessTokensQuickstart

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 AccessTokensQuickstart
dotnet build

Une sortie « Hello World » simple doit être affichée. Si c’est le cas, votre installation fonctionne correctement et vous pouvez commencer à écrire votre code spécifique à Azure Communication Services.

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 en utilisant la commande dotnet add package.

dotnet add package Azure.Communication.Identity

Configurer le framework d’application

Dans le répertoire du projet, procédez comme suit :

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 la méthode Main pour prendre en charge le code asynchrone.

Pour commencer, exécutez le code suivant :

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

Authentifier le client

Initialisez CommunicationIdentityClient avec votre chaîne de connexion. Le code suivant, que vous ajoutez à la méthode Main, récupère la chaîne de connexion pour la ressource à partir d’une variable d’environnement nommée COMMUNICATION_SERVICES_CONNECTION_STRING.

Pour plus d’informations, consultez la section « Stocker votre chaîne de connexion » de la rubrique Créer et gérer des ressources Communication Services.

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

Vous pouvez également séparer le point de terminaison et la clé d’accès en exécutant le code suivant :

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

Si vous avez déjà configuré une application Microsoft Entra, vous pouvez vous authentifier à l’aide de Microsoft Entra ID.

TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(new Uri(endpoint), tokenCredential);

Créer une identité

Pour créer des jetons d’accès, vous avez besoin d’une identité. Azure Communication Services gère un répertoire LID (Lightweight Identity Directory) à cet effet. Utilisez la méthode createUser pour créer une entrée, avec une valeur Id unique, dans le répertoire. L’identité sera demandée ultérieurement pour émettre des jetons d’accès.

var identityResponse = await client.CreateUserAsync();
var identity = identityResponse.Value;
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");

Stockez l’identité reçue avec un mappage aux utilisateurs de votre application (par exemple, en la stockant dans la base de données de votre serveur d’applications).

Émettre un jeton d’accès

Une fois que vous avez une identité Communication Services, utilisez la méthode GetToken pour émettre un jeton d’accès pour celle-ci. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Pour plus d’informations, consultez la liste des actions prises en charge dans le modèle d’identité. Une nouvelle instance de communicationUser peut également être construite sur la base de la représentation sous forme de chaîne de l’identité Azure Communication Services.

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

Les jetons d’accès sont des informations d’identification à durée de vie courte, qui doivent être réémises. Ne pas le faire peut entraîner une interruption expérimentée par les utilisateurs de votre application. La propriété expiresOn indique la durée de vie du jeton d’accès.

Définir une heure d’expiration de jeton personnalisé

L’heure d’expiration du jeton par défaut est de 24 heures, mais vous pouvez la configurer en fournissant une valeur comprise entre une heure et 24 heures au paramètre facultatif tokenExpiresIn. Lors de la demande d’un nouveau jeton, il est recommandé de spécifier la durée normale attendue d’une session de communication pour l’heure d’expiration du jeton.

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

Créer une identité et émettre un jeton dans la même requête

Vous pouvez utiliser la méthode CreateUserAndTokenAsync pour créer une identité Communication Services et émettre un jeton d’accès pour celle-ci en même temps. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Pour plus d’informations, consultez la liste des actions prises en charge dans S’authentifier auprès d’Azure Communication Services.

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

Actualiser un jeton d’accès

Pour actualiser un jeton d’accès, transmettez une instance de l’objet CommunicationUserIdentifier dans GetTokenAsync. Si vous avez stocké cet élément Id et que vous devez créer un CommunicationUserIdentifier, vous pouvez le faire en passant votre Id stocké dans le constructeur CommunicationUserIdentifier, comme suit :

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

Révoquer des jetons d’accès

Vous devrez peut-être parfois révoquer explicitement un jeton d’accès. Par exemple, vous pouvez le faire lorsque les utilisateurs de l’application modifient le mot de passe qu’ils utilisent pour s’authentifier auprès de votre service. La méthode RevokeTokensAsync invalide tous les jetons d’accès actifs qui ont été émis pour l’identité.

await client.RevokeTokensAsync(identity);
Console.WriteLine($"\nSuccessfully revoked all access tokens for identity with ID: {identity.Id}");

Supprimer une identité

Lorsque vous supprimez une identité, vous révoquez tous les jetons d’accès actifs et vous empêchez les nouvelles émissions de jetons d’accès pour l’identité. Cela supprime également tout le contenu persistant associé à l’identité.

await client.DeleteUserAsync(identity);
Console.WriteLine($"\nDeleted the identity with ID: {identity.Id}");

Exécuter le code

Une fois que vous avez fini de créer le jeton d’accès, vous pouvez exécuter l’application à partir de votre répertoire d’application à l’aide de la commande dotnet run.

dotnet run

La sortie de l’application décrit chaque action terminée :

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

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Node.js versions Active LTS et Maintenance LTS (8.11.1 et 10.14.1 recommandées).
• Une ressource Communication Services active et la chaîne de connexion. Créez une ressource Communication Services.

Code final

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

Configurer votre environnement

Création d’une application Node.js

Dans un terminal ou une fenêtre d’invite de commandes, créez un nouveau répertoire pour votre application, puis ouvrez-le.

mkdir access-tokens-quickstart && cd 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

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

Configurer le framework d’application

1. Créez un fichier nommé issue-access-token.js dans le répertoire du projet et ajoutez le code suivant :

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

Authentifier le client

Instanciez un CommunicationIdentityClient avec votre chaîne de connexion. Le code suivant, que vous ajoutez à la méthode Main, récupère la chaîne de connexion pour la ressource à partir d’une variable d’environnement nommée COMMUNICATION_SERVICES_CONNECTION_STRING.

Pour plus d’informations, consultez la section « Stocker votre chaîne de connexion » de la rubrique Créer et gérer des ressources Communication Services.

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

Vous pouvez également séparer le point de terminaison et la clé d’accès en exécutant le code suivant :

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

Si vous avez déjà configuré une application Microsoft Entra, vous pouvez vous authentifier à l’aide de Microsoft Entra ID.

const endpoint = process.env["COMMUNICATION_SERVICES_ENDPOINT"];
const tokenCredential = new DefaultAzureCredential();
const identityClient = new CommunicationIdentityClient(endpoint, tokenCredential);

Créer une identité

Pour créer des jetons d’accès, vous avez besoin d’une identité. Azure Communication Services gère un répertoire LID (Lightweight Identity Directory) à cet effet. Utilisez la méthode createUser pour créer une entrée, avec une valeur Id unique, dans le répertoire. L’identité sera demandée ultérieurement pour émettre des jetons d’accès.

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

Stockez l’identité reçue avec un mappage aux utilisateurs de votre application (par exemple, en la stockant dans la base de données de votre serveur d’applications).

Émettre un jeton d’accès

Avec la méthode getToken, émettez un jeton d’accès pour votre identité Communication Services. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Pour plus d’informations, consultez la liste des actions prises en charge dans le modèle d’identité. Une nouvelle instance de communicationUser peut également être construite sur la base de la représentation sous forme de chaîne de l’identité Azure Communication Services.

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

Les jetons d’accès sont des informations d’identification à durée de vie courte, qui doivent être réémises. Ne pas le faire peut entraîner une interruption expérimentée par les utilisateurs de votre application. La propriété expiresOn indique la durée de vie du jeton d’accès.

Définir une heure d’expiration de jeton personnalisé

L’heure d’expiration du jeton par défaut est de 24 heures (1 440 minutes), mais vous pouvez la configurer en fournissant une valeur comprise entre 60 minutes and 1 440 minutes au paramètre facultatif tokenExpiresInMinutes. Lors de la demande d’un nouveau jeton, il est recommandé de spécifier la durée normale attendue d’une session de communication pour l’heure d’expiration du jeton.

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

Créer une identité et émettre un jeton dans un appel de méthode

Vous pouvez utiliser la méthode createUserAndToken pour créer une identité Communication Services et émettre un jeton d’accès pour celle-ci en même temps. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Là encore, vous le créez avec l’étendue voip.

// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
let identityTokenResponse = await identityClient.createUserAndToken(["voip"]);

// Get the token, its expiration date, and the user from the response
const { token, expiresOn, user } = identityTokenResponse;
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
console.log(token);

Actualiser un jeton d’accès

Comme les jetons expirent, vous devrez périodiquement les actualiser. L’actualisation est facile, il suffit d’appeler à nouveau getToken avec la même identité qui a été utilisée pour émettre les jetons. Vous devez également fournir les scopes des jetons actualisés.

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

Révoquer des jetons d’accès

Vous devrez peut-être parfois révoquer un jeton d’accès. Par exemple, vous pouvez le faire lorsque les utilisateurs de l’application modifient le mot de passe qu’ils utilisent pour s’authentifier auprès de votre service. La méthode revokeTokens invalide tous les jetons d’accès actifs qui ont été émis pour l’identité.

await identityClient.revokeTokens(identityResponse);

console.log(`\nSuccessfully revoked all access tokens for identity with ID: ${identityResponse.communicationUserId}`);

Supprimer une identité

Lorsque vous supprimez une identité, vous révoquez tous les jetons d’accès actifs et vous empêchez les nouvelles émissions de jetons d’accès pour l’identité. Cela supprime également tout le contenu persistant associé à l’identité.

await identityClient.deleteUser(identityResponse);

console.log(`\nDeleted the identity with ID: ${identityResponse.communicationUserId}`);

Exécuter le code

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

node ./issue-access-token.js

La sortie de l’application décrit chaque action terminée :

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

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Python 3.8 et version ultérieure.
• Une ressource Communication Services active et la chaîne de connexion. Créez une ressource Communication Services.

Code final

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

Configurer votre environnement

Créer une application Python

1. Dans un terminal ou une fenêtre d’invite de commandes, créez un nouveau répertoire pour votre application, puis ouvrez-le.

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

2. Utilisez un éditeur de texte pour créer un fichier appelé issue-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 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)
   

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

Authentifier le client

Instanciez un CommunicationIdentityClient avec votre chaîne de connexion. Le code suivant, que vous ajoutez au bloc try, récupère la chaîne de connexion pour la ressource à partir d’une variable d’environnement nommée COMMUNICATION_SERVICES_CONNECTION_STRING.

Pour plus d’informations, consultez la section « Stocker votre chaîne de connexion » de la rubrique Créer et gérer des ressources Communication Services.

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

Sinon, si vous avez déjà configuré une application Microsoft Entra, vous pouvez vous authentifier à l’aide de Microsoft Entra ID.

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

Créer une identité

Pour créer des jetons d’accès, vous avez besoin d’une identité. Azure Communication Services gère un répertoire LID (Lightweight Identity Directory) à cet effet. Utilisez la méthode create_user pour créer une entrée, avec une valeur Id unique, dans le répertoire. L’identité sera demandée ultérieurement pour émettre des jetons d’accès.

identity = client.create_user()
print("\nCreated an identity with ID: " + identity.properties['id'])

Stockez l’identité reçue avec un mappage aux utilisateurs de votre application (par exemple, en la stockant dans la base de données de votre serveur d’applications).

Émettre un jeton d’accès

Avec la méthode get_token, émettez un jeton d’accès pour votre identité Communication Services. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Pour plus d’informations, consultez la liste des actions prises en charge dans le modèle d’identité. Une nouvelle instance du paramètre CommunicationUserIdentifier peut également être construite sur la base de la représentation sous forme de chaîne de l’identité Azure Communication Services.

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

Les jetons d’accès sont des informations d’identification à durée de vie courte, qui doivent être réémises. Ne pas le faire peut entraîner une interruption expérimentée par les utilisateurs de votre application. La propriété de réponse expires_on indique la durée de vie du jeton d’accès.

Définir une heure d’expiration de jeton personnalisé

L’heure d’expiration du jeton par défaut est de 24 heures, mais vous pouvez la configurer en fournissant une valeur comprise entre une heure et 24 heures au paramètre facultatif token_expires_in. Lors de la demande d’un nouveau jeton, il est recommandé de spécifier la durée normale attendue d’une session de communication pour l’heure d’expiration du jeton.

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

Créer une identité et émettre un jeton d’accès dans la même requête

Vous pouvez utiliser la méthode create_user_and_token pour créer une identité Communication Services et émettre un jeton d’accès pour celle-ci en même temps. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Pour plus d’informations, consultez la liste des actions prises en charge dans S’authentifier auprès d’Azure Communication Services.

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

Actualiser un jeton d’accès

Pour actualiser un jeton d’accès, utilisez l’objet CommunicationUserIdentifier pour réémettre un jeton en transmettant ’identité existante :

# The existingIdentity value represents the Communication Services identity that's stored during identity creation
identity = CommunicationUserIdentifier(existingIdentity)
token_result = client.get_token(identity, ["voip"])

Révoquer des jetons d’accès

Vous devrez peut-être parfois révoquer explicitement un jeton d’accès. Par exemple, vous pouvez le faire lorsque les utilisateurs de l’application modifient le mot de passe qu’ils utilisent pour s’authentifier auprès de votre service. La méthode revoke_tokens invalide tous les jetons d’accès actifs qui ont été émis pour l’identité.

client.revoke_tokens(identity)
print("\nSuccessfully revoked all access tokens for identity with ID: " + identity.properties['id'])

Supprimer une identité

Lorsque vous supprimez une identité, vous révoquez tous les jetons d’accès actifs et vous empêchez les nouvelles émissions de jetons d’accès pour l’identité. Cela supprime également tout le contenu persistant associé à l’identité.

client.delete_user(identity)
print("\nDeleted the identity with ID: " + identity.properties['id'])

Exécuter le code

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

python ./issue-access-tokens.py

La sortie de l’application décrit chaque action terminée :

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

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.
• Kit de développement Java (JDK), version 8 ou ultérieure
• Apache Maven.
• Une ressource Communication Services active et la chaîne de connexion. Créez une ressource Communication Services.

Code final

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

Configurer votre environnement

Créer une application Java

Dans un terminal ou une fenêtre d’invite de commandes, accédez au répertoire dans lequel vous souhaitez créer votre application Java. Exécutez le code 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 artifactId. Sous ce répertoire, le répertoire src/main/java contient le code source du projet, le répertoire src/test/java contient la source de test, et le fichier pom.xml est le modèle d’objet du projet, ou modèle POM. Ce fichier est utilisé pour les paramètres de configuration du projet.

Installer les packages Azure Communication Services

Ouvrez le fichier pom.xml dans votre éditeur de texte. Ajoutez l’élément dépendance suivant au groupe de dépendances :

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-identity</artifactId>
    <version>[1.4.0,)</version>
</dependency>

Ce code indique à Maven d’installer le kit de développement logiciel (SDK) Communication Services Identity, que vous utiliserez ultérieurement.

Configurer le framework d’application

Dans le répertoire du projet, procédez comme suit :

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. Ajouter des directives import.

Utilisez le code suivant pour commencer :

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

Authentifier le client

Instanciez un CommunicationIdentityClient avec la clé d’accès et le point de terminaison de votre ressource. Pour plus d’informations, consultez la section « Stocker votre chaîne de connexion » de la rubrique Créer et gérer des ressources Communication Services.

En outre, vous pouvez initialiser le client avec n’importe quel client HTTP personnalisé qui implémente l’interface com.azure.core.http.HttpClient.

Dans le fichier App.java, ajoutez le code suivant à la méthode main :

// You can find your endpoint and access key from your resource in the Azure portal
String endpoint = "https://<RESOURCE_NAME>.communication.azure.com";
String accessKey = "SECRET";

CommunicationIdentityClient communicationIdentityClient = new CommunicationIdentityClientBuilder()
        .endpoint(endpoint)
        .credential(new AzureKeyCredential(accessKey))
        .buildClient();

Vous pouvez également fournir la chaîne de connexion entière à l’aide de la méthode connectionString() au lieu de fournir le point de terminaison et la clé d’accès.

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

Si vous avez déjà configuré une application Microsoft Entra, vous pouvez vous authentifier à l’aide de 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();

Créer une identité

Pour créer des jetons d’accès, vous avez besoin d’une identité. Azure Communication Services gère un répertoire LID (Lightweight Identity Directory) à cet effet. Utilisez la méthode createUser pour créer une entrée, avec une valeur Id unique, dans le répertoire.

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

L’identité créée sera demandée ultérieurement pour émettre des jetons d’accès. Stockez l’identité reçue avec un mappage aux utilisateurs de votre application (par exemple, en la stockant dans la base de données de votre serveur d’applications).

Émettre un jeton d’accès

Avec la méthode getToken, émettez un jeton d’accès pour votre identité Communication Services. Le paramètre scopes définit un ensemble d’autorisations et de rôles de jeton d’accès. Pour plus d’informations, consultez la liste des actions prises en charge dans le modèle d’identité.

Dans le code suivant, utilisez la variable utilisateur que vous avez créée à l’étape précédente pour obtenir un jeton.

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

Les jetons d’accès sont des informations d’identification à durée de vie courte, qui doivent être réémises. Ne pas le faire peut entraîner une interruption expérimentée par les utilisateurs de votre application. La propriété expiresAt indique la durée de vie du jeton d’accès.

Définir une heure d’expiration de jeton personnalisé

L’heure d’expiration du jeton par défaut est de 24 heures, mais vous pouvez la configurer en fournissant une valeur comprise entre une heure et 24 heures au paramètre facultatif tokenExpiresIn. Lors de la demande d’un nouveau jeton, il est recommandé de spécifier la durée normale attendue d’une session de communication pour l’heure d’expiration du jeton.

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

Créer une identité et émettre un jeton en une requête

Vous pouvez également utiliser la méthode « createUserAndToken » pour créer une entrée dans le répertoire avec un Id unique et émettre un jeton d’accès en même temps.

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

Actualiser un jeton d’accès

Pour actualiser un jeton d’accès, utilisez l’objet CommunicationUserIdentifier permettant de l’émettre à nouveau :

// existingIdentity represents the Communication Services identity that's stored during identity creation
CommunicationUserIdentifier identity = new CommunicationUserIdentifier(existingIdentity.getId());
AccessToken response = communicationIdentityClient.getToken(identity, scopes);

Révoquer un jeton d’accès

Vous devrez peut-être parfois révoquer explicitement un jeton d’accès. Par exemple, vous pouvez le faire lorsque les utilisateurs de l’application modifient le mot de passe qu’ils utilisent pour s’authentifier auprès de votre service. La méthode revokeTokens invalide tous les jetons d’accès actifs pour un utilisateur particulier. Dans le code suivant, vous pouvez utiliser l’utilisateur créé précédemment.

communicationIdentityClient.revokeTokens(user);
System.out.println("\nSuccessfully revoked all access tokens for user identity with ID: " + user.getId());

Supprimer une identité

Lorsque vous supprimez une identité, vous révoquez tous les jetons d’accès actifs et vous empêchez les nouvelles émissions de jetons d’accès pour l’identité. Cela supprime également tout le contenu persistant associé à l’identité.

communicationIdentityClient.deleteUser(user);
System.out.println("\nDeleted the user identity with ID: " + user.getId());

Exécuter le code

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

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

La sortie de l’application décrit chaque action terminée :

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

• Une ressource Azure Communication Services

Créer les jetons d’accès

Dans le portail Azure, accédez au panneau Identités et jetons d’accès utilisateur de votre ressource Communication Services.

Choisissez l’étendue des jetons d’accès. Vous pouvez sélectionner aucun, un ou plusieurs. Cliquez sur Générer.

Vous verrez qu’une identité et un jeton d’accès utilisateur correspondant sont générés. Vous pouvez copier ces chaînes et les utiliser dans les exemples d’applications et d’autres scénarios de test.

Prérequis

• Un compte Azure avec un abonnement actif ou créez gratuitement un compte Azure.

• Une ressource Azure Communication Services active ou créez une ressource Communication Services.

• Une ressource Azure Logic Apps active (application logique), ou créez un flux de travail d’application logique de consommation avec le déclencheur que vous souhaitez utiliser. Comme le connecteur Azure Communication Services Identity ne fournit actuellement que des actions, votre application logique nécessite au minimum un déclencheur.

Créer un utilisateur

Ajoutez une nouvelle étape à votre workflow à l’aide du connecteur Azure Communication Services Identity, puis suivez les étapes ci-dessous dans Power Automate en veillant à ce que votre flux Power Automate soit ouvert en mode d’édition.

1. Dans le concepteur, sous l’étape à laquelle vous souhaitez ajouter la nouvelle action, choisissez Nouvelle étape. Vous pouvez également ajouter la nouvelle action entre des étapes, déplacer votre pointeur sur la flèche située entre ces étapes, sélectionner le signe plus (+), puis sélectionner Ajouter une action.

2. Dans la zone de recherche Choisir une opération, entrez Communication Services Identity. Dans la liste des actions, sélectionnez Créer un utilisateur.

   

3. Fournissez la chaîne de connexion. Celle-ci se trouve dans Microsoft Azure, sous votre ressource Azure Communication Service, dans l’option Clés du menu de gauche > Chaîne de connexion.

   

4. Fournissez un nom de connexion.

5. Cliquez sur Créer

   Cette action génère un identifiant utilisateur, qui est une identité d’utilisateur Communication Services. En outre, si vous cliquez sur « Afficher les options avancées » et sélectionnez l’étendue du jeton, l’action génère également un jeton d’accès et son heure d’expiration, avec spécification de l’étendue.

   

   

Émettre un jeton d’accès utilisateur

Une fois que vous disposez d’une identité Communication Services, vous pouvez utiliser l’action Émettre un jeton d’accès utilisateur pour émettre un jeton d’accès. Pour cela, procédez comme suit :

1. Ajoutez une nouvelle action et entrez Communication Services Identity dans la zone de recherche. Dans la liste des actions, sélectionnez Émettre un jeton d’accès utilisateur.

   

2. Vous pouvez ensuite utiliser l’identifiant utilisateur généré lors de l’étape Créer un utilisateur.

3. Spécifiez l’étendue du jeton : VoIP ou conversation. Apprenez-en davantage sur les jetons et l’authentification.

   

Cela génère un jeton d’accès et son heure d’expiration avec spécification de l’étendue.

Révoquer des jetons d’accès utilisateur

Une fois que vous disposez d’une identité Communication Services, vous pouvez utiliser l’action Émettre un jeton d’accès utilisateur pour révoquer un jeton d’accès. Pour cela, procédez comme suit :

1. Ajoutez une nouvelle action et entrez Communication Services Identity dans la zone de recherche. Dans la liste des actions, sélectionnez Révoquer un jeton d’accès utilisateur.

   

2. Spécifiez l’identifiant utilisateur.

   

Cela révoque tous les jetons d’accès de l’utilisateur spécifié. Il n’existe aucune sortie pour cette action.

Supprimer un utilisateur

Une fois que vous disposez d’une identité Communication Services, vous pouvez utiliser l’action Émettre un jeton d’accès utilisateur pour supprimer un jeton d’accès. Pour cela, procédez comme suit :

1. Ajoutez une nouvelle action et entrez Communication Services Identity dans la zone de recherche. Dans la liste des actions, sélectionnez Supprimer un utilisateur.

   

2. Spécifiez l’identifiant utilisateur.

   

   Cela supprime l’utilisateur et révoque tous les jetons d’accès de l’utilisateur spécifié. Il n’existe aucune sortie pour cette action.

Tester votre application logique

Pour lancer manuellement votre workflow, sélectionnez Exécuter dans la barre d’outils du concepteur. Le flux de travail doit créer un utilisateur, émettre un jeton d’accès pour cet utilisateur, puis le supprimer et supprimer l’utilisateur. Pour plus d’informations, consultez Exécuter votre workflow. Vous pouvez vérifier les sorties de ces actions une fois que le flux de travail s’exécute correctement.

Utilisation de l’identité pour le monitoring et les métriques

L’identifiant utilisateur est destiné à servir de clé primaire pour les journaux et les métriques collectés par le biais d’Azure Monitor. Pour afficher tous les appels d’un utilisateur, par exemple, vous pouvez configurer votre authentification de manière à mapper une ou des identités Azure Communication Services spécifiques à un seul utilisateur.

En savoir plus sur les concepts d’authentification, l’appel de diagnostics via Log Analytics et les métriques à votre disposition.

Nettoyer les ressources

Pour nettoyer et supprimer un abonnement Communication Services, supprimez la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées. Pour plus d’informations, consultez la section « Nettoyer les ressources » de la rubrique Créer et gérer des ressources Communication Services.

Pour nettoyer le flux de travail de votre application logique et les ressources associées, consultez les instructions permettant de nettoyer des ressources Azure Logic Apps.

Étapes suivantes

Dans ce démarrage rapide, vous avez appris comment :

• Émettre des jetons d’accès
• Gérer des identités

Ajouter l’appel vocal à votre application

Vous pouvez également :

• Découvrir l’authentification
• Ajouter un système de conversation à votre application
• Découvrir l’architecture client et serveur
• Déployer l’exemple de service d’authentification approuvé

Étapes suivantes

Ce guide de démarrage rapide vous a appris créer un utilisateur, supprimer un utilisateur, émettre un jeton d’accès pour un utilisateur et retirer un jeton d’accès à un utilisateur à l’aide du connecteur Azure Communication Services Identity. Pour en savoir plus, consultez la documentation du connecteur Azure Communication Services Identity.

Pour en savoir plus sur la façon dont d’autres connecteurs utilisent les jetons, apprenez à envoyer un message de conversation à partir de Power Automate à l’aide d’Azure Communication Services.

Pour en savoir plus sur l’envoi d’un e-mail à l’aide du connecteur Azure Communication Services Email, consultez Envoyer un e-mail dans Power Automate avec Azure Communication Services.