Azure Communication Common (Java)

Utilitaires d'authentification partagés et structures de données pour Azure Communication Services.

Installation

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version>1.4.0</version>
</dependency>

Concepts clés

CommunicationTokenCredential

Token statique (clients de courte durée)

import com.azure.communication.common.CommunicationTokenCredential;

// Token statique simple - pas d'actualisation
String userToken = "<user-access-token>";
CommunicationTokenCredential credential = new CommunicationTokenCredential(userToken);

// Utiliser avec Chat, Calling, etc.
ChatClient chatClient = new ChatClientBuilder()
    .endpoint("https://<resource>.communication.azure.com")
    .credential(credential)
    .buildClient();

Actualisation proactive du token (clients de longue durée)

import com.azure.communication.common.CommunicationTokenRefreshOptions;
import java.util.concurrent.Callable;

// Callback d'actualisation du token - appelé quand le token est sur le point d'expirer
Callable<String> tokenRefresher = () -> {
    // Appeler votre serveur pour obtenir un token actualisé
    return fetchNewTokenFromServer();
};

// Avec actualisation proactive
CommunicationTokenRefreshOptions refreshOptions = new CommunicationTokenRefreshOptions(tokenRefresher)
    .setRefreshProactively(true)      // Actualiser avant expiration
    .setInitialToken(currentToken);    // Token initial optionnel

CommunicationTokenCredential credential = new CommunicationTokenCredential(refreshOptions);

Actualisation asynchrone du token

import java.util.concurrent.CompletableFuture;

// Fetcher de token asynchrone
Callable<String> asyncRefresher = () -> {
    CompletableFuture<String> future = fetchTokenAsync();
    return future.get();  // Bloquer jusqu'à ce que le token soit disponible
};

CommunicationTokenRefreshOptions options = new CommunicationTokenRefreshOptions(asyncRefresher)
    .setRefreshProactively(true);

CommunicationTokenCredential credential = new CommunicationTokenCredential(options);

Authentification Entra ID (Azure AD)

import com.azure.identity.InteractiveBrowserCredentialBuilder;
import com.azure.communication.common.EntraCommunicationTokenCredentialOptions;
import java.util.Arrays;
import java.util.List;

// Pour Teams Phone Extensibility
InteractiveBrowserCredential entraCredential = new InteractiveBrowserCredentialBuilder()
    .clientId("<your-client-id>")
    .tenantId("<your-tenant-id>")
    .redirectUrl("<your-redirect-uri>")
    .build();

String resourceEndpoint = "https://<resource>.communication.azure.com";
List<String> scopes = Arrays.asList(
    "https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls"
);

EntraCommunicationTokenCredentialOptions entraOptions = 
    new EntraCommunicationTokenCredentialOptions(entraCredential, resourceEndpoint)
        .setScopes(scopes);

CommunicationTokenCredential credential = new CommunicationTokenCredential(entraOptions);

Identifiants de communication

CommunicationUserIdentifier

import com.azure.communication.common.CommunicationUserIdentifier;

// Créer un identifiant pour un utilisateur ACS
CommunicationUserIdentifier user = new CommunicationUserIdentifier("8:acs:resource-id_user-id");

// Obtenir l'ID brut
String rawId = user.getId();

PhoneNumberIdentifier

import com.azure.communication.common.PhoneNumberIdentifier;

// Numéro de téléphone au format E.164
PhoneNumberIdentifier phone = new PhoneNumberIdentifier("+14255551234");

String phoneNumber = phone.getPhoneNumber();  // "+14255551234"
String rawId = phone.getRawId();              // "4:+14255551234"

MicrosoftTeamsUserIdentifier

import com.azure.communication.common.MicrosoftTeamsUserIdentifier;

// Identifiant utilisateur Teams
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier("<teams-user-id>")
    .setCloudEnvironment(CommunicationCloudEnvironment.PUBLIC);

// Pour les utilisateurs Teams anonymes
MicrosoftTeamsUserIdentifier anonymousTeamsUser = new MicrosoftTeamsUserIdentifier("<teams-user-id>")
    .setAnonymous(true);

UnknownIdentifier

import com.azure.communication.common.UnknownIdentifier;

// Pour les identifiants de type inconnu
UnknownIdentifier unknown = new UnknownIdentifier("some-raw-id");

Analyse syntaxique des identifiants

import com.azure.communication.common.CommunicationIdentifier;
import com.azure.communication.common.CommunicationIdentifierModel;

// Analyser l'ID brut pour obtenir le type approprié
public CommunicationIdentifier parseIdentifier(String rawId) {
    if (rawId.startsWith("8:acs:")) {
        return new CommunicationUserIdentifier(rawId);
    } else if (rawId.startsWith("4:")) {
        String phone = rawId.substring(2);
        return new PhoneNumberIdentifier(phone);
    } else if (rawId.startsWith("8:orgid:")) {
        String teamsId = rawId.substring(8);
        return new MicrosoftTeamsUserIdentifier(teamsId);
    } else {
        return new UnknownIdentifier(rawId);
    }
}

Vérification de type des identifiants

import com.azure.communication.common.CommunicationIdentifier;

public void processIdentifier(CommunicationIdentifier identifier) {
    if (identifier instanceof CommunicationUserIdentifier) {
        CommunicationUserIdentifier user = (CommunicationUserIdentifier) identifier;
        System.out.println("Utilisateur ACS : " + user.getId());

    } else if (identifier instanceof PhoneNumberIdentifier) {
        PhoneNumberIdentifier phone = (PhoneNumberIdentifier) identifier;
        System.out.println("Téléphone : " + phone.getPhoneNumber());

    } else if (identifier instanceof MicrosoftTeamsUserIdentifier) {
        MicrosoftTeamsUserIdentifier teams = (MicrosoftTeamsUserIdentifier) identifier;
        System.out.println("Utilisateur Teams : " + teams.getUserId());
        System.out.println("Anonyme : " + teams.isAnonymous());

    } else if (identifier instanceof UnknownIdentifier) {
        UnknownIdentifier unknown = (UnknownIdentifier) identifier;
        System.out.println("Inconnu : " + unknown.getId());
    }
}

Accès au token

import com.azure.core.credential.AccessToken;

// Obtenir le token actuel (pour debug/logs - ne pas exposer !)
CommunicationTokenCredential credential = new CommunicationTokenCredential(token);

// Accès synchrone
AccessToken accessToken = credential.getToken();
System.out.println("Le token expire : " + accessToken.getExpiresAt());

// Accès asynchrone
credential.getTokenAsync()
    .subscribe(token -> {
        System.out.println("Token : " + token.getToken().substring(0, 20) + "...");
        System.out.println("Expire : " + token.getExpiresAt());
    });

Libérer les identifiants

// Nettoyer quand vous avez terminé
credential.close();

// Ou utiliser try-with-resources
try (CommunicationTokenCredential cred = new CommunicationTokenCredential(options)) {
    // Utiliser l'identifiant
    chatClient.doSomething();
}

Environnements cloud

import com.azure.communication.common.CommunicationCloudEnvironment;

// Environnements disponibles
CommunicationCloudEnvironment publicCloud = CommunicationCloudEnvironment.PUBLIC;
CommunicationCloudEnvironment govCloud = CommunicationCloudEnvironment.GCCH;
CommunicationCloudEnvironment dodCloud = CommunicationCloudEnvironment.DOD;

// Définir sur l'identifiant Teams
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier("<user-id>")
    .setCloudEnvironment(CommunicationCloudEnvironment.GCCH);

Variables d'environnement

AZURE_COMMUNICATION_ENDPOINT=https://<resource>.communication.azure.com
AZURE_COMMUNICATION_USER_TOKEN=<user-access-token>

Bonnes pratiques

1. Actualisation proactive - Toujours utiliser setRefreshProactively(true) pour les clients de longue durée
2. Sécurité des tokens - Ne jamais enregistrer ni exposer les tokens complets
3. Fermer les identifiants - Libérer les identifiants quand ils ne sont plus utilisés
4. Gestion des erreurs - Gérer les défaillances d'actualisation des tokens gracieusement
5. Types d'identifiants - Utiliser les types d'identifiants spécifiques, pas les chaînes brutes

Modèles d'utilisation courants

// Modèle : Créer un identifiant pour client Chat/Calling
public ChatClient createChatClient(String token, String endpoint) {
    CommunicationTokenRefreshOptions refreshOptions = 
        new CommunicationTokenRefreshOptions(this::refreshToken)
            .setRefreshProactively(true)
            .setInitialToken(token);

    CommunicationTokenCredential credential = 
        new CommunicationTokenCredential(refreshOptions);

    return new ChatClientBuilder()
        .endpoint(endpoint)
        .credential(credential)
        .buildClient();
}

private String refreshToken() {
    // Appeler votre endpoint de tokens
    return tokenService.getNewToken();
}

Phrases déclencheurs

• "Authentification ACS", "communication token credential"
• "user access token", "token refresh"
• "CommunicationUserIdentifier", "PhoneNumberIdentifier"
• "Authentification Azure Communication Services"