Azure Communication Common for Java: Setup, Usage & Best Practices

What This Skill Does

The Azure Communication Common SDK for Java provides shared authentication utilities, identity types, and credential management used across all Azure Communication Services SDKs. This skill isn't used directly to build features but provides the foundation for Chat, Calling, SMS, and other Communication Services by handling user access tokens, token refresh, and identity abstraction.

Think of this as the "plumbing" SDK. When building chat applications, voice bots, or SMS services, you use this SDK to authenticate users, refresh expiring tokens, and represent different participant types (Azure Communication users, phone numbers, Microsoft Teams users).

The SDK's CommunicationTokenCredential class is particularly important - it handles automatic token refresh, preventing disruptions in long-running chat or call sessions. Without proper token management, users would be abruptly disconnected when tokens expire (typically after 24 hours).

Getting Started

Add the Maven dependency:

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

This SDK is typically used as a dependency of other Communication Services SDKs, but you'll interact with its classes directly for authentication and identity management.

Key Features

CommunicationTokenCredential: Manages user access tokens with automatic refresh. Prevents authentication failures in long-running sessions by fetching new tokens before expiration.

Identity Types: Type-safe representations of different participant types. CommunicationUserIdentifier for Azure Communication users, PhoneNumberIdentifier for phone numbers, MicrosoftTeamsUserIdentifier for Teams users, UnknownIdentifier for future types.

Token Refresh Options: Configure proactive or reactive token refresh with custom refresher callbacks. Control token lifecycle without manual intervention.

Entra ID Authentication: Support for Microsoft Entra ID (Azure AD) authentication for Teams Phone Extensibility scenarios. Enables Teams identity integration.

Raw ID Parsing: Utilities for converting between raw ID strings and typed identifiers. Essential when deserializing identifiers from JSON or database storage.

Usage Examples

Static token (short-lived clients):

import com.azure.communication.common.CommunicationTokenCredential;

String userToken = "<user-access-token>";
CommunicationTokenCredential credential = 
    new CommunicationTokenCredential(userToken);

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

Proactive token refresh (long-lived clients):

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

// Token refresher - called before token expires
Callable<String> tokenRefresher = () -> {
    // Call your backend API to get fresh token
    return httpClient.get("/api/token").body();
};

CommunicationTokenRefreshOptions refreshOptions = 
    new CommunicationTokenRefreshOptions(tokenRefresher)
        .setRefreshProactively(true)    // Refresh before expiry
        .setInitialToken(currentToken);  // Optional initial token

CommunicationTokenCredential credential = 
    new CommunicationTokenCredential(refreshOptions);

Working with identity types:

import com.azure.communication.common.*;

// Azure Communication user
CommunicationUserIdentifier user = 
    new CommunicationUserIdentifier("8:acs:resource-id_user-id");

// Phone number
PhoneNumberIdentifier phone = 
    new PhoneNumberIdentifier("+14255551234");

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

// Type checking
if (identifier instanceof CommunicationUserIdentifier) {
    CommunicationUserIdentifier acsUser = 
        (CommunicationUserIdentifier) identifier;
    System.out.println("ACS User: " + acsUser.getId());
}

Parsing raw IDs:

public CommunicationIdentifier parseRawId(String rawId) {
    if (rawId.startsWith("8:acs:")) {
        return new CommunicationUserIdentifier(rawId);
    } else if (rawId.startsWith("4:")) {
        return new PhoneNumberIdentifier(rawId.substring(2));
    } else if (rawId.startsWith("8:orgid:")) {
        return new MicrosoftTeamsUserIdentifier(rawId.substring(8));
    } else {
        return new UnknownIdentifier(rawId);
    }
}

Best Practices

Always use proactive token refresh for long-lived clients. Set setRefreshProactively(true) to refresh tokens before they expire rather than after receiving auth failures:

refreshOptions.setRefreshProactively(true);

Implement robust token refresher callbacks. Handle network failures, retry logic, and fallback tokens:

Callable<String> reliableRefresher = () -> {
    for (int i = 0; i < 3; i++) {
        try {
            return tokenService.getNewToken();
        } catch (IOException e) {
            if (i == 2) throw e;
            Thread.sleep(1000 * (i + 1));
        }
    }
    throw new RuntimeException("Token refresh failed after retries");
};

Dispose credentials when finished. Credentials hold resources:

try (CommunicationTokenCredential cred = new CommunicationTokenCredential(options)) {
    // Use credential
    chatClient.doWork();
}

Never log or expose tokens. Tokens grant full access to Communication Services - treat them like passwords:

// DON'T DO THIS
System.out.println("Token: " + credential.getToken());

// Instead
System.out.println("Token acquired successfully");

Use specific identifier types, not raw strings. Type-safe identifiers prevent errors and enable better IDE support:

// Good
CommunicationUserIdentifier user = new CommunicationUserIdentifier(userId);

// Bad
String user = userId;  // Loses type information

Handle cloud environments for Teams users. Specify the correct cloud:

MicrosoftTeamsUserIdentifier teamsUser = 
    new MicrosoftTeamsUserIdentifier("<user-id>")
        .setCloudEnvironment(CommunicationCloudEnvironment.GCCH);  // Gov cloud

Implement error handling for token operations:

try {
    AccessToken token = credential.getToken();
} catch (RuntimeException e) {
    logger.error("Token acquisition failed", e);
    // Handle gracefully - maybe use cached token or re-authenticate
}

When to Use This Skill

Use Azure Communication Common when implementing any Azure Communication Services feature. This SDK is fundamental to Chat, Calling, SMS, and other communication scenarios.

This skill is essential when building authentication flows for communication applications. Implement user authentication, token issuance, and refresh logic using these utilities.

Choose this skill when integrating multiple Communication Services. The shared identity types work across Chat, Calling, and SMS - use the same identity abstractions everywhere.

It's perfect for building multi-tenant communication platforms. Handle different user types (your users, Teams users, phone numbers) with a unified interface.

Use it when implementing token refresh in server-side components. Background services, bots, or long-running processes need proper token management.

When NOT to Use This Skill

Don't use this directly for end-user features. It's a utility SDK - use it as part of Chat, Calling, or other feature SDKs.

Avoid trying to issue tokens with this SDK. Token issuance happens server-side using the Azure Communication Identity SDK. This SDK only consumes tokens.

Skip implementing custom authentication schemes. Use the provided token credential system rather than building custom auth.

Don't use for anonymous scenarios requiring tokens. Anonymous users still need tokens issued by your backend using the Identity SDK.

This skill doesn't validate token content. It manages lifecycle only - token content validation happens server-side.

Related Skills

• azure-communication-chat-java - Uses credentials from this SDK
• azure-communication-callautomation-java - Uses identity types from this SDK
• azure-identity - Azure-wide authentication (different from Communication token auth)

Source

Official SDK: azure-sdk-for-java/sdk/communication/azure-communication-common

API Documentation: Azure Communication Common