Edit

Identity model

  • Article

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

  • Reuse existing identities from your identity management system and simply map them with Azure Communication Services identities.
  • Provides integration flexibility as identity-agnostic model works well with your existing identity system.
  • You can 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

Uniquely identifies a user through a user-identifier, which is generated by Azure Communication Services when a user is created. External identifiers such as phone numbers, users, devices, applications, and GUIDs can't be used for identity in Azure Communication Services. You can create Azure Communication Service user identities for free. Charges are only incurred when the user consumes communications modalities such as a chat or a call. Your users identity can be mapped to Azure Communication Services user Identity in 1:1, 1:N, N:1, N:N configurations. A user can participate in multiple communication sessions, using multiple devices, simultaneously. Mapping between Azure Communication Services user identity and customer's private user identity is kept and maintained by the customer. For example, customers can add a CommunicationServicesId column in their user table to store the associated Azure Communication Services identity.

Access tokens

After a user identity is created, a user is granted with the capability to participate in communications using chat or calls, using access tokens. For example, only a user with chat token can participate in chat and user with VoIP token can participate in a VoIP call. A user can have multiple tokens simultaneously. Azure Communication Services supports multiple types of tokens to account for users who require full access vs limited access. Access tokens have the following properties.

Property Description
Identity Uniquely identifies a token
Expiration An access token is valid for a period of time between 1 and 24 hours. After it expires, the access token is invalidated and can't be used to access any primitive. To generate a token with a custom validity, specify the desired validity period when generating the token. If no custom validity is specified, the token will be valid for 24 hours. We recommend using short lifetime tokens for one-off meetings and longer lifetime tokens for agents using the application for longer periods of time
Scope The scope parameter defines a nonempty set of primitives (Chat/VoIP) that can be used.

An access token is a JSON Web Token (JWT) and has integrity protection. That is, its claims can't be changed after it's issued. So a manual change of properties such as identity, expiration, or scopes will invalidate the access token. If primitives are used with invalidated tokens, then access will be denied to the primitives. Azure Communication Services supports the following scopes for access tokens.

Chat token scopes

Three types of chat token scopes are supported. Permissions for each token are described below.

  • chat
  • chat.join
  • chat.join.limited
Capability / Token scope chat chat.join chat.join.limited
Create chat thread Y N N
Update chat thread with ID Y N N
Delete chat thread with ID Y N N
Add participant to a chat thread Y Y N
Remove participant from a chat thread Y Y N
Get chat threads Y Y Y
Get chat thread with ID Y Y Y
Get ReadReceipt Y Y Y
Create ReadReceipt Y Y Y
Create message for chat thread with ID Y Y Y
Get message with message ID Y Y Y
Update your own message with message ID Y Y Y
Delete your own message with message ID Y Y Y
Send typing indicator Y Y Y
Get participant for thread ID Y Y Y

VoIP token scopes

Two types of VoIP token scopes are supported. Permissions for each token are described below.

  • voip
  • voip.join
Capability / Token scope voip voip.join
Start a VoIP call Y N
Start a VoIP call in Virtual Rooms, when the user is already invited to the Room Y Y
Join an InProgress VoIP call Y Y
Join an InProgress VoIP call in Virtual Rooms, when the user is already invited to the Room Y Y
All other in-call operations such as mute/unmute, screen share etc. Y Y
All other in-call operations such as mute/unmute, screen share etc. in Virtual Rooms Determined by user role Determined by user role

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.
  • The removal of 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. 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. In this case all identities lose access to Azure Communication Services, and they must issue new access tokens.

Considerations

  • We recommend issuing access tokens in your server-side service and not in the client's application. The reasoning is that issuing requires an access key or Microsoft Entra authentication. Sharing secrets with the client's application isn't recommended for security reasons.
  • Client application should use a trusted service endpoint that can authenticate clients. The endpoint should issue access tokens on their behalf. For more information, see Client and server architecture.
  • If you cache access tokens to a backing store, we recommend using encryption. An access token is sensitive data. It can be used for malicious activity if it's not protected. Someone who has an access token can start the SDK and access the API. The accessible API is restricted only based on the scopes that the access token has.
  • We recommend issuing access tokens that have only the required scopes.

Next steps