Merge pull request #262244 from FarrukhGhaffar/FarrukhGhaffar/SecurityTokensDocs

Farrukh ghaffar/security tokens docs

Author: AnnaMHuff

articles/communication-services/concepts/chat/concepts.md

@@ -36,7 +36,7 @@ Chat conversations happen within **chat threads**. Chat threads have the followi
 - Users are added as a participant to any chat threads that they create.
 
 ### User access
-Typically the thread creator and participants have same level of access to the thread and can execute all related operations available in the SDK, including deleting it. Participants don't have write access to messages sent by other participants, which means only the message sender can update or delete their sent messages. If another participant tries to do that, they get an error. 
+Azure Communication Services supports three levels of user access control, using the chat tokens. See [Identity and Tokens](../identity-model.md) for details. Participants don't have write-access to messages sent by other participants, which means only the message sender can update or delete their sent messages. If another participant tries to do that, they get an error. 
 
 ### Chat Data 
 Azure Communication Services stores chat messages indefinitely until they are deleted by the customer. Chat thread participants can use `ListMessages` to view  message history for a particular thread. Users that are removed from a chat thread are able to view previous message history but can't send or receive new messages. Accidentally deleted messages aren't recoverable by the system. To learn more about data being stored in Azure Communication Services chat service, refer to the [data residency and privacy page](../privacy.md).  

articles/communication-services/concepts/identity-model.md

@@ -2,83 +2,89 @@
 title: Identity model
 titleSuffix: An Azure Communication Services concept
 description: Learn about the identities and access tokens
-author: tomaschladek
-manager: nmurav
+author: FarrukhGhaffar
+manager: cassidyfein
 services: azure-communication-services
 
-ms.author: tchladek
-ms.date: 06/30/2021
+ms.author: faghaffa
+ms.date: 01/02/2024
 ms.topic: conceptual
 ms.service: azure-communication-services
 ms.subservice: identity
 ---
 
 # Identity model
-
-Azure Communication Services is an identity-agnostic service. This design offers multiple benefits:
-
-- Reuses existing identities from your identity management system
-- Provides flexibility for integration scenarios
-- Keeps your identities private in Azure Communication Services
-
-Instead of duplicating information in your system, you'll maintain the mapping relationship that your business case requires. For example, you can map identities 1:1, 1:N, N:1, N:M. External identifiers such as phone numbers, users, devices, applications, and GUIDs can't be used for identity in Azure Communication Services. Access tokens that are generated for an Azure Communication Services identity are used to access primitives such as chat or calling.
-
-## Identity
-
-You can create identities by using the Azure Communication Services Identity library. An identity serves as an identifier in conversations. It's used to create access tokens. The same identity might participate in multiple simultaneous sessions across multiple devices. An identity might have multiple active access tokens at the same time.
-
-The deletion of an identity, resource, or subscription invalidates all of its access tokens. This action also deletes all data that's stored for the identity. A deleted identity can't create new access tokens or access previously stored data (for example, chat messages).
-
-You aren't charged for the number of identities you have. Instead, you're charged for the use of primitives. The number of your identities doesn't have to restrict how you map your application's identities to the Azure Communication Services identities.
-
-With the freedom of mapping comes privacy responsibility. If a user wants to be deleted from your system, then you need to delete all identities that are associated with that user.
-
-Azure Communication Services doesn't provide special identities for anonymous users. It doesn't keep the mapping between the users and identities, and it can't determine whether an identity is anonymous. You can design the identity concept to fit your needs. Our recommendation is to create a new identity for each anonymous user on each application.
-
-Anyone who has a valid access token can access current identity content. For example, users can access chat messages that they sent. The access is restricted only to scopes that are part of the access token. For more information, see the [Access tokens](#access-tokens) section in this article.
-
-### Identity mapping
-
-Azure Communication Services doesn't replicate the functionality of the Azure identity management system. It doesn't provide a way for customers to use customer-specific identities. For example, customers can't use a phone number or email address. Instead, Azure Communication Services provides unique identifiers. You can assign these unique identifiers to your application's identities. Azure Communication Services doesn't store any kind of information that might reveal the real identity of your users.
-
-To avoid duplicating information in your system, plan how to map users from your identity domain to Azure Communication Services identities. You can follow any kind of pattern. For example, you can use 1:1, 1:N, N:1, or M:N. Decide whether a single user is mapped to a single identity or to multiple identities.
-
-When a new identity is created, store its mapping to your application's user or users. Because identities require access tokens to use primitives, the identity needs to be known to your application's user or users.
-
-If you use a relational database to store user information, then you can adjust your design based on your mapping scenario. For scenarios that map 1:1 or N:1, you might want to add a `CommunicationServicesId` column to the table to store your Azure Communication Services identity. In scenarios that use the relationship 1:N or N:M, you might consider creating a separate table in the relational database.
-
-## Access tokens
-
-An access token is a JSON Web Token (JWT) that can be used to get access to Azure Communication Service primitives. An access token that's issued 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.
-
-The properties of an access token are:
-* Identity.
-* Expiration.
-* Scopes.
-
-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.
-
-An identity needs a way to request a new access token from a server-side service. The *scope* parameter defines a nonempty set of primitives that can be used. Azure Communication Services supports the following scopes for access tokens.
-
-|Name|Description|
-|---|---|
-|Chat|	Grants the ability to participate in a chat|
-|VoIP|	Grants the ability to call identities and phone numbers|
-
-
-To revoke an access token before its expiration time, use the Azure Communication Services Identity library. Token revocation isn't immediate. It takes 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.
-
-In Azure Communication Services, a rotation of access keys revokes all active access tokens that were created by using a former access key. All identities lose access to Azure Communication Services, and they must issue new access tokens.
-
-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.
-
-The client application should use a trusted service endpoint that can authenticate your clients. The endpoint should issue access tokens on their behalf. For more information, see [Client and server architecture](./client-and-server-architecture.md).
-
-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.
+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| Y | 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](./client-and-server-architecture.md).
+- 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
 

articles/communication-services/concepts/voice-video-calling/calling-sdk-features.md

@@ -22,6 +22,9 @@ Once you've started development, check out the [known issues page](../known-issu
 Key features of the Calling SDK:
 
 - **Addressing** - Azure Communication Services provides generic [identities](../identity-model.md) that are used to address communication endpoints. Clients use these identities to authenticate to the service and communicate with each other. These identities are used in Calling APIs that provide clients visibility into who is connected to a call (the roster).
+- **User Access Security**
+  - **Roster** control, **Schedule** control, and user **roles/permissions** are enforced through [Virtual Rooms](../rooms/room-concept.md).
+  - Ability for a user to **Initiate a new call** or to **Join an existing call** can be managed through [User Identities and Tokens](../identity-model.md) 
 - **Encryption** - The Calling SDK encrypts traffic and prevents tampering on the wire.
 - **Device Management and Media** - The Calling SDK provides facilities for binding to audio and video devices, encodes content for efficient transmission over the communications dataplane, and renders content to output devices and views that you specify. APIs are also provided for screen and application sharing.
 - **PSTN** - The Calling SDK can initiate voice calls with the traditional publicly switched telephone network, [using phone numbers you acquire in the Azure portal](../../quickstarts/telephony/get-phone-number.md) or programmatically.