Azure Communication Identity SDK for JavaScript

Manage user identities and issue access tokens for Azure Communication Services.

Introduction

The Azure Communication Identity SDK for JavaScript allows you to create and manage user identities within Azure Communication Services. This is a crucial step for enabling features like chat, voice, and video calling.

With this SDK, you can:

  • Create new communication users.
  • Obtain and manage access tokens for users to authenticate with Communication Services.
  • Revoke tokens when necessary to enforce security policies.

Installation

Install the Azure Communication Identity SDK for JavaScript using npm or yarn:

npm install @azure/communication-identity

Or using yarn:

yarn add @azure/communication-identity

Getting Started

To use the SDK, you'll need an Azure Communication Services resource. You can create one in the Azure portal. You will also need to obtain your resource's connection string or use Azure AD authentication.

Prerequisites

  • An Azure account with an active subscription.
  • An Azure Communication Services resource.
  • Your Communication Services resource's connection string or Azure AD credentials.

Creating a User

You can create a new communication user using the createCommsUser method.


import { CommunicationIdentityClient } from "@azure/communication-identity";

// Replace with your actual connection string
const connectionString = "YOUR_CONNECTION_STRING";
const identityClient = new CommunicationIdentityClient(connectionString);

async function createUser() {
  try {
    const userResult = await identityClient.createCommsUser();
    console.log(`User created with ID: ${userResult.communicationUserId}`);
    return userResult.communicationUserId;
  } catch (error) {
    console.error("Error creating user:", error);
    throw error;
  }
}

// Example usage:
// createUser().then(userId => console.log("User created:", userId));

Getting an Access Token

To allow a user to interact with Communication Services, you need to issue an access token for them. You can specify the scopes required for the token.


import { CommunicationIdentityClient } from "@azure/communication-identity";

const connectionString = "YOUR_CONNECTION_STRING";
const identityClient = new CommunicationIdentityClient(connectionString);

async function getToken(userId) {
  try {
    // Scopes define the permissions the token grants
    const tokenResult = await identityClient.getToken(userId, ["chat", "voip"]);
    console.log(`Access token: ${tokenResult.token}`);
    console.log(`Token expires on: ${tokenResult.expiresOn}`);
    return tokenResult;
  } catch (error) {
    console.error("Error getting token:", error);
    throw error;
  }
}

// Example usage (assuming you have a userId from createUser):
// const userId = "acs-user-id-here";
// getToken(userId).then(result => console.log("Token obtained:", result));

Available Scopes:

  • "voip": For making and receiving calls.
  • "chat": For sending and receiving chat messages.
  • "pstn": For making and receiving PSTN calls.
  • " இடங்களில்": For managing appointments.

Revoking Tokens

You can revoke an issued access token for a specific user. This is useful for security when a user leaves or their permissions change.


import { CommunicationIdentityClient } from "@azure/communication-identity";

const connectionString = "YOUR_CONNECTION_STRING";
const identityClient = new CommunicationIdentityClient(connectionString);

async function revokeToken(userId) {
  try {
    await identityClient.revokeTokens(userId);
    console.log(`All tokens for user ${userId} have been revoked.`);
  } catch (error) {
    console.error("Error revoking tokens:", error);
    throw error;
  }
}

// Example usage (assuming you have a userId):
// const userId = "acs-user-id-here";
// revokeToken(userId).then(() => console.log("Tokens revoked."));

API Reference

CommunicationIdentityClient

The main class for interacting with the identity service.

Constructor

new CommunicationIdentityClient(connectionString: string)

Initializes the client with your Azure Communication Services resource connection string.

Methods

  • createCommsUser(): Promise<{ communicationUserId: string }>

    Creates a new communication user. Returns the unique ID of the created user.

  • getToken(userId: string, scopes: string[]): Promise<{ token: string, expiresOn: Date }>

    Issues an access token for the specified user with the given scopes.

    userId: The ID of the communication user.

    scopes: An array of strings representing the desired permissions (e.g., ["chat", "voip"]).

    Returns the access token and its expiration date.

  • revokeTokens(userId: string): Promise<void>

    Revokes all existing access tokens for the specified user.

    userId: The ID of the communication user.

Authentication

The SDK supports authentication using:

  • Connection String: The simplest method for server-side applications. Obtain this from your Azure Communication Services resource in the Azure portal.
  • Azure Active Directory (Azure AD): For more robust security and enterprise scenarios, you can use Azure AD credentials (e.g., service principals, managed identities) with the Azure Identity library.

For Azure AD authentication, you would typically use classes like DefaultAzureCredential from @azure/identity and pass a token credential to the CommunicationIdentityClient constructor.


// Example using Azure AD
/*
import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";

const endpoint = "YOUR_ACS_ENDPOINT"; // e.g., "https://your-resource-name.communication.azure.com";
const credential = new DefaultAzureCredential();
const identityClient = new CommunicationIdentityClient(endpoint, { credential });

// Now use identityClient as shown in the examples above
*/