The identity library is used for managing users and tokens for Azure Communication Services.
- An Azure subscription.
- An existing Communication Services resource. If you need to create the resource, you can use the Azure Portal, the Azure PowerShell, or the Azure CLI.
npm install @azure/communication-identity
To use this client library in the browser, first you need to use a bundler. For details on how to do this, please refer to our bundling documentation.
The CommunicationIdentityClient
provides methods to manage users and their tokens.
You can get a key and/or connection string from your Communication Services resource in Azure Portal. Once you have a key, you can authenticate the CommunicationIdentityClient
with any of the following methods:
import { AzureKeyCredential } from "@azure/core-auth";
import { CommunicationIdentityClient } from "@azure/communication-identity";
const credential = new AzureKeyCredential(KEY);
const client = new CommunicationIdentityClient(ENDPOINT, credential);
import { CommunicationIdentityClient } from "@azure/communication-identity";
const connectionString = `endpoint=ENDPOINT;accessKey=KEY`;
const client = new CommunicationIdentityClient(connectionString);
import { DefaultAzureCredential } from "@azure/identity";
import { CommunicationIdentityClient } from "@azure/communication-identity";
const credential = new DefaultAzureCredential();
const client = new CommunicationIdentityClient(ENDPOINT, credential);
If you use a key to initialize the client you will also need to provide the appropriate endpoint. You can get this endpoint from your Communication Services resource in Azure Portal.
import { CommunicationIdentityClient } from "@azure/communication-identity";
const client = new CommunicationIdentityClient(CONNECTION_STRING);
Use the createUser
method to create a new user.
const user = await client.createUser();
Use the getToken
method to issue or refresh a token for an existing user. The method also takes in a list of communication token scopes. Scope options include:
chat
(Use this for full access to Chat APIs)voip
(Use this for full access to Calling APIs)chat.join
(Access to Chat APIs but without the authorization to create, delete or update chat threads)chat.join.limited
(A more limited version of chat.join that doesn't allow to add or remove participants)voip.join
(Access to Calling APIs but without the authorization to start new calls)
const { token } = await client.getToken(user, ["chat"]);
To refresh the user token, issue another token with the same user.
const { token } = await client.getToken(user, ["chat"]);
It's also possible to create a Communication Identity access token by customizing the expiration time. Validity period of the token must be within [60,1440] minutes range. If not provided, the default value of 1440 minutes (24 hours) will be used.
const tokenOptions: GetTokenOptions = { tokenExpiresInMinutes: 60 };
const { token } = await client.getToken(user, ["chat"], tokenOptions);
For convenience, use createUserAndToken
to create a new user and issue a token with one function call. This translates into a single web request as opposed to creating a user first and then issuing a token.
const { user, token } = await client.createUserAndToken(["chat"]);
It's also possible to create a Communication Identity access token by customizing the expiration time. Validity period of the token must be within [60,1440] minutes range. If not provided, the default value of 1440 minutes (24 hours) will be used.
const userAndTokenOptions: CreateUserAndTokenOptions = { tokenExpiresInMinutes: 60 };
const { user, token } = await client.createUserAndToken(["chat"], userAndTokenOptions);
Use the revokeTokens
method to revoke all issued tokens for a user.
await client.revokeTokens(user);
Use the deleteUser
method to delete a user.
await client.deleteUser(user);
Use getTokenForTeamsUser
method to exchange an Azure AD access token of a Teams user for a new CommunicationAccessToken
with a matching expiration time.
await client.getTokenForTeamsUser({
teamsUserAadToken: "<aad-access-token-of-a-teams-user>",
clientId: "<cliend-id-of-an-aad-application>",
userObjectId: "<aad-object-id-of-a-teams-user>",
});
Please take a look at the samples directory for detailed examples on how to use this library.
If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.