Azure Communication Common Java

1---
2name: azure-communication-common-java
3description: Azure Communication Services common utilities for Java. Use when working with CommunicationTokenCredential, user identifiers, token refresh, or shared authentication across ACS services.
4package: com.azure:azure-communication-common
5---
6 
7# Azure Communication Common (Java)
8 
9Shared authentication utilities and data structures for Azure Communication Services.
10 
11## Installation
12 
13```xml
14<dependency>
15    <groupId>com.azure</groupId>
16    <artifactId>azure-communication-common</artifactId>
17    <version>1.4.0</version>
18</dependency>
19```
20 
21## Key Concepts
22 
23| Class | Purpose |
24|-------|---------|
25| `CommunicationTokenCredential` | Authenticate users with ACS services |
26| `CommunicationTokenRefreshOptions` | Configure automatic token refresh |
27| `CommunicationUserIdentifier` | Identify ACS users |
28| `PhoneNumberIdentifier` | Identify PSTN phone numbers |
29| `MicrosoftTeamsUserIdentifier` | Identify Teams users |
30| `UnknownIdentifier` | Generic identifier for unknown types |
31 
32## CommunicationTokenCredential
33 
34### Static Token (Short-lived Clients)
35 
36```java
37import com.azure.communication.common.CommunicationTokenCredential;
38 
39// Simple static token - no refresh
40String userToken = "<user-access-token>";
41CommunicationTokenCredential credential = new CommunicationTokenCredential(userToken);
42 
43// Use with Chat, Calling, etc.
44ChatClient chatClient = new ChatClientBuilder()
45    .endpoint("https://<resource>.communication.azure.com")
46    .credential(credential)
47    .buildClient();
48```
49 
50### Proactive Token Refresh (Long-lived Clients)
51 
52```java
53import com.azure.communication.common.CommunicationTokenRefreshOptions;
54import java.util.concurrent.Callable;
55 
56// Token refresher callback - called when token is about to expire
57Callable<String> tokenRefresher = () -> {
58    // Call your server to get a fresh token
59    return fetchNewTokenFromServer();
60};
61 
62// With proactive refresh
63CommunicationTokenRefreshOptions refreshOptions = new CommunicationTokenRefreshOptions(tokenRefresher)
64    .setRefreshProactively(true)      // Refresh before expiry
65    .setInitialToken(currentToken);    // Optional initial token
66 
67CommunicationTokenCredential credential = new CommunicationTokenCredential(refreshOptions);
68```
69 
70### Async Token Refresh
71 
72```java
73import java.util.concurrent.CompletableFuture;
74 
75// Async token fetcher
76Callable<String> asyncRefresher = () -> {
77    CompletableFuture<String> future = fetchTokenAsync();
78    return future.get();  // Block until token is available
79};
80 
81CommunicationTokenRefreshOptions options = new CommunicationTokenRefreshOptions(asyncRefresher)
82    .setRefreshProactively(true);
83 
84CommunicationTokenCredential credential = new CommunicationTokenCredential(options);
85```
86 
87## Entra ID (Azure AD) Authentication
88 
89```java
90import com.azure.identity.InteractiveBrowserCredentialBuilder;
91import com.azure.communication.common.EntraCommunicationTokenCredentialOptions;
92import java.util.Arrays;
93import java.util.List;
94 
95// For Teams Phone Extensibility
96InteractiveBrowserCredential entraCredential = new InteractiveBrowserCredentialBuilder()
97    .clientId("<your-client-id>")
98    .tenantId("<your-tenant-id>")
99    .redirectUrl("<your-redirect-uri>")
100    .build();
101 
102String resourceEndpoint = "https://<resource>.communication.azure.com";
103List<String> scopes = Arrays.asList(
104    "https://auth.msft.communication.azure.com/TeamsExtension.ManageCalls"
105);
106 
107EntraCommunicationTokenCredentialOptions entraOptions = 
108    new EntraCommunicationTokenCredentialOptions(entraCredential, resourceEndpoint)
109        .setScopes(scopes);
110 
111CommunicationTokenCredential credential = new CommunicationTokenCredential(entraOptions);
112```
113 
114## Communication Identifiers
115 
116### CommunicationUserIdentifier
117 
118```java
119import com.azure.communication.common.CommunicationUserIdentifier;
120 
121// Create identifier for ACS user
122CommunicationUserIdentifier user = new CommunicationUserIdentifier("8:acs:resource-id_user-id");
123 
124// Get raw ID
125String rawId = user.getId();
126```
127 
128### PhoneNumberIdentifier
129 
130```java
131import com.azure.communication.common.PhoneNumberIdentifier;
132 
133// E.164 format phone number
134PhoneNumberIdentifier phone = new PhoneNumberIdentifier("+14255551234");
135 
136String phoneNumber = phone.getPhoneNumber();  // "+14255551234"
137String rawId = phone.getRawId();              // "4:+14255551234"
138```
139 
140### MicrosoftTeamsUserIdentifier
141 
142```java
143import com.azure.communication.common.MicrosoftTeamsUserIdentifier;
144 
145// Teams user identifier
146MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier("<teams-user-id>")
147    .setCloudEnvironment(CommunicationCloudEnvironment.PUBLIC);
148 
149// For anonymous Teams users
150MicrosoftTeamsUserIdentifier anonymousTeamsUser = new MicrosoftTeamsUserIdentifier("<teams-user-id>")
151    .setAnonymous(true);
152```
153 
154### UnknownIdentifier
155 
156```java
157import com.azure.communication.common.UnknownIdentifier;
158 
159// For identifiers of unknown type
160UnknownIdentifier unknown = new UnknownIdentifier("some-raw-id");
161```
162 
163## Identifier Parsing
164 
165```java
166import com.azure.communication.common.CommunicationIdentifier;
167import com.azure.communication.common.CommunicationIdentifierModel;
168 
169// Parse raw ID to appropriate type
170public CommunicationIdentifier parseIdentifier(String rawId) {
171    if (rawId.startsWith("8:acs:")) {
172        return new CommunicationUserIdentifier(rawId);
173    } else if (rawId.startsWith("4:")) {
174        String phone = rawId.substring(2);
175        return new PhoneNumberIdentifier(phone);
176    } else if (rawId.startsWith("8:orgid:")) {
177        String teamsId = rawId.substring(8);
178        return new MicrosoftTeamsUserIdentifier(teamsId);
179    } else {
180        return new UnknownIdentifier(rawId);
181    }
182}
183```
184 
185## Type Checking Identifiers
186 
187```java
188import com.azure.communication.common.CommunicationIdentifier;
189 
190public void processIdentifier(CommunicationIdentifier identifier) {
191    if (identifier instanceof CommunicationUserIdentifier) {
192        CommunicationUserIdentifier user = (CommunicationUserIdentifier) identifier;
193        System.out.println("ACS User: " + user.getId());
194        
195    } else if (identifier instanceof PhoneNumberIdentifier) {
196        PhoneNumberIdentifier phone = (PhoneNumberIdentifier) identifier;
197        System.out.println("Phone: " + phone.getPhoneNumber());
198        
199    } else if (identifier instanceof MicrosoftTeamsUserIdentifier) {
200        MicrosoftTeamsUserIdentifier teams = (MicrosoftTeamsUserIdentifier) identifier;
201        System.out.println("Teams User: " + teams.getUserId());
202        System.out.println("Anonymous: " + teams.isAnonymous());
203        
204    } else if (identifier instanceof UnknownIdentifier) {
205        UnknownIdentifier unknown = (UnknownIdentifier) identifier;
206        System.out.println("Unknown: " + unknown.getId());
207    }
208}
209```
210 
211## Token Access
212 
213```java
214import com.azure.core.credential.AccessToken;
215 
216// Get current token (for debugging/logging - don't expose!)
217CommunicationTokenCredential credential = new CommunicationTokenCredential(token);
218 
219// Sync access
220AccessToken accessToken = credential.getToken();
221System.out.println("Token expires: " + accessToken.getExpiresAt());
222 
223// Async access
224credential.getTokenAsync()
225    .subscribe(token -> {
226        System.out.println("Token: " + token.getToken().substring(0, 20) + "...");
227        System.out.println("Expires: " + token.getExpiresAt());
228    });
229```
230 
231## Dispose Credential
232 
233```java
234// Clean up when done
235credential.close();
236 
237// Or use try-with-resources
238try (CommunicationTokenCredential cred = new CommunicationTokenCredential(options)) {
239    // Use credential
240    chatClient.doSomething();
241}
242```
243 
244## Cloud Environments
245 
246```java
247import com.azure.communication.common.CommunicationCloudEnvironment;
248 
249// Available environments
250CommunicationCloudEnvironment publicCloud = CommunicationCloudEnvironment.PUBLIC;
251CommunicationCloudEnvironment govCloud = CommunicationCloudEnvironment.GCCH;
252CommunicationCloudEnvironment dodCloud = CommunicationCloudEnvironment.DOD;
253 
254// Set on Teams identifier
255MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier("<user-id>")
256    .setCloudEnvironment(CommunicationCloudEnvironment.GCCH);
257```
258 
259## Environment Variables
260 
261```bash
262AZURE_COMMUNICATION_ENDPOINT=https://<resource>.communication.azure.com
263AZURE_COMMUNICATION_USER_TOKEN=<user-access-token>
264```
265 
266## Best Practices
267 
2681. **Proactive Refresh** - Always use `setRefreshProactively(true)` for long-lived clients
2692. **Token Security** - Never log or expose full tokens
2703. **Close Credentials** - Dispose of credentials when no longer needed
2714. **Error Handling** - Handle token refresh failures gracefully
2725. **Identifier Types** - Use specific identifier types, not raw strings
273 
274## Common Usage Patterns
275 
276```java
277// Pattern: Create credential for Chat/Calling client
278public ChatClient createChatClient(String token, String endpoint) {
279    CommunicationTokenRefreshOptions refreshOptions = 
280        new CommunicationTokenRefreshOptions(this::refreshToken)
281            .setRefreshProactively(true)
282            .setInitialToken(token);
283    
284    CommunicationTokenCredential credential = 
285        new CommunicationTokenCredential(refreshOptions);
286    
287    return new ChatClientBuilder()
288        .endpoint(endpoint)
289        .credential(credential)
290        .buildClient();
291}
292 
293private String refreshToken() {
294    // Call your token endpoint
295    return tokenService.getNewToken();
296}
297```
298 
299## Trigger Phrases
300 
301- "ACS authentication", "communication token credential"
302- "user access token", "token refresh"
303- "CommunicationUserIdentifier", "PhoneNumberIdentifier"
304- "Azure Communication Services authentication"
305