Identity model

Azure Communication Services is an identity-agnostic service, which offers multiple benefits:

• Reuse existing identities from your identity management system and map them with Azure Communication Services identities.
• Works well with any existing identity system and has no dependency on a specific identity provider.
• Keep your user's data, such as their name, private as you don't need to duplicate it in Azure Communication Services.

Azure Communication Services identity model works with two key concepts.

User identity / mapping

When you create a user identity via SDK or REST API, Azure Communication Services creates a unique user identifier. You can't use external identifiers such as phone numbers, user/device/application IDs, or user names directly in Azure Communication Services. Instead, you need to use the Communication Services identities and maintain a mapping to your own user ID system as needed.

You can create Azure Communication Service user identities for free. The only charges are incurred when the user consumes communication services such as a chat or a call. How you use your generated Communication Services identity depends on your scenario. For example, you can map an identity 1:1, 1:N, N:1, or N:N, and you can use it for human users or applications. Your end-user can participate in multiple communication sessions, using multiple devices, simultaneously.

Managing a mapping between Azure Communication Services user identities and your own identity system is your responsibility as a developer, and doesn't come built-in. For example, you can add a CommunicationServicesId column in your existing user table to store the associated Azure Communication Services identity. A mapping design is described in more detail under Client-server architecture.

Access tokens

After you create a user identity, the end-user then needs an access token with specific scopes to participate in communications using chat or calls. For example, only a user with a token of chat scope can participate in chat. Only a user with a token of voip scope can participate in a VoIP call.

A user can have multiple tokens simultaneously. Azure Communication Services supports multiple token scopes to account for users who require full access vs limited access. Access tokens have the following properties.

An access token is a JSON Web Token (JWT) and has integrity protection. That is, its claims can't be changed without invalidating the access token because then the token signature no longer matches. If communication primitives are used with invalid tokens, access is denied. Even though tokens aren't encrypted or obfuscated, your application shouldn't depend on the token format or its claims. The token format can change and isn't part of the official API contract. Azure Communication Services supports the following scopes for access tokens.

Chat token scopes

The identity model supports three different chat token scopes. Permissions for each scope are described in the following table.

• chat
• chat.join
• chat.join.limited

VoIP token scopes

The identity model supports two VoIP token scopes. Permissions for each scope are described in the following table.

• voip
• voip.join

You can use the voip.join scope together with Rooms to create a scheduled call. In this scenario, only invited users get access and users are prohibited from creating any other calls.

Revoke or update access token

• Azure Communication Services Identity library can be used to revoke an access token before its expiration time. Token revocation isn't immediate. It can take up to 15 minutes to propagate.
• Deleting an identity, resource, or subscription revokes all access tokens.
• If you want to remove a user's ability to access specific functionality, revoke all access tokens for the user. Then issue a new access token that has a more limited set of scopes.
• Rotation of access keys revokes all active access tokens that were created by using a former access key. So all identities lose access to Azure Communication Services and need new access tokens.

Client-server architecture

Create and manage user access tokens through a trusted service and not create tokens in your client application. You need the connection string or Microsoft Entra credentials to create user access tokens. Remember to protect the credentials, passing them to a client would risk leaking the secret. Failure to properly manage access tokens can result in extra charges on your resource when tokens are dispensed freely and misused by someone else.

If you cache access tokens to a backing store, we recommend encrypting the tokens. An access token gives access to sensitive data and can be used for malicious activity if it isn't protected. Anyone with a user's access token can access that user's chat data or participate in calls impersonating the user.

Make sure to include only those scopes in the token that your client application needs in order to follow the security principle of least privilege.

1. A user starts the client application.
2. The client application contacts your identity management service.
3. The identity management service authenticates the application user. You can skip authentication for scenarios where the user is anonymous, but be careful to then add other protective measures such as throttling and CORS to your service to mitigate token abuse.
4. Create or find a Communication Services identity for the user.
   1. Stable identity scenario: Your identity management service maintains a mapping between application identities and Communication Services identities. (Application identities include your users and other addressable objects, like services or bots.) If the application identity is new, a new Communication identity is created and a mapping is stored.
   2. Ephemeral identity scenario: The identity management service creates a new Communication identity. In this scenario, the same user ends up with a different Communication identity for each session.
5. The identity management service issues a user access token for the applicable identity and returns it to the client application.

Azure App Service or Azure Functions are two alternatives for operating the identity management service. These services scale easily and have built-in features to authenticate users. They're integrated with OpenID and third-party identity providers like Facebook.

Next steps

• To issue tokens, see Create and manage access tokens for end users.
• For an introduction to authentication, see Authenticate to Azure Communication Services.
• To read about data residency and privacy, see Region availability and data residency.
• For a full sample of a simple identity management service, see Trusted service tutorial.
• For a more advanced identity management sample which integrates with Entra ID and Microsoft Graph, see Authentication service hero sample.