You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/communication-services/concepts/identity-model.md
+50-32Lines changed: 50 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -16,31 +16,31 @@ ms.subservice: identity
16
16
# Identity model
17
17
Azure Communication Services is an identity-agnostic service, which offers multiple benefits:
18
18
19
-
- Reuse existing identities from your identity management system and simply map them with Azure Communication Services identities.
20
-
-Provides integration flexibility as identity-agnostic model works well with your existing identity system.
21
-
-You can Keep your user's data, such as their name, private as you don't need to duplicate it in Azure Communication Services.
19
+
- Reuse existing identities from your identity management system and map them with Azure Communication Services identities.
20
+
-Works well with any existing identity system and has no dependency on a specific identity provider.
21
+
- Keep your user's data, such as their name, private as you don't need to duplicate it in Azure Communication Services.
22
22
23
23
Azure Communication Services identity model works with two key concepts.
24
24
25
25
## User identity / mapping
26
-
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.
26
+
When you create a user identity via SDK or REST API, Azure Communication Services creates a unique user identifier. External identifiers such as phone numbers, user/device/application IDs, or user names can't be used directly in Azure Communication Services. Instead you have to use the Communication Services identities and maintain a mapping to your own user ID system as needed. Creating Azure Communication Service user identities is free and charges are only incurred when the user consumes communication modalities 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. A 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](#client-server-architecture).
27
27
28
28
## Access tokens
29
-
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.
29
+
After a user identity is created, a 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 with the `chat` scope can participate in chat and a user with a token with `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.
30
30
31
31
|Property|Description|
32
32
|---|----|
33
-
|Identity|Uniquely identifies a token|
34
-
|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|
35
-
|Scope|The scope parameter defines a nonempty set of primitives (Chat/VoIP) that can be used.
33
+
|Subject|The user identity which is represented by the token.|
34
+
|Expiration|An access token is valid for at least 1 hour and up to 24 hours. After it expires, the access token is invalid and can't be used to access the service. To create a token with a custom expiration time, specify the desired validity in minutes (>=60, <1440). By default, the token is valid for 24 hours. We recommend using short lifetime tokens for one-off meetings and longer lifetime tokens for users who use your application for longer periods of time.|
35
+
|Scopes|The scopes define which communication primitives (Chat/VoIP) can be accessed with the token.|
36
36
37
-
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.
37
+
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.
38
38
39
-
## Chat token scopes
40
-
Three types of chat token scopes are supported. Permissions for each token are described below.
41
-
- chat
42
-
- chat.join
43
-
- chat.join.limited
39
+
###Chat token scopes
40
+
Three different chat token scopes are supported. Permissions for each scope are described in the following table.
@@ -60,35 +60,53 @@ Three types of chat token scopes are supported. Permissions for each token are d
60
60
|Send typing indicator | Y | Y | Y |
61
61
|Get participant for thread ID | Y | Y | Y |
62
62
63
-
## VoIP token scopes
64
-
Two types of VoIP token scopes are supported. Permissions for each token are described below.
65
-
- voip
66
-
- voip.join
63
+
###VoIP token scopes
64
+
Two VoIP token scopes are supported. Permissions for each scope are described in the following table.
65
+
-`voip`
66
+
-`voip.join`
67
67
68
68
|Capability / Token scope| voip | voip.join |
69
69
|---|---|---|
70
70
|Start a VoIP call | Y | N |
71
71
|Start a VoIP call in Virtual Rooms, when the user is already invited to the Room| Y | Y |
72
72
|Join an InProgress VoIP call | Y | Y |
73
73
|Join an InProgress VoIP call in Virtual Rooms, when the user is already invited to the Room| Y | Y |
74
-
|All other in-call operations such as mute/unmute, screen share etc. | Y | Y |
75
-
|All other in-call operations such as mute/unmute, screen share etc. in Virtual Rooms| Determined by user role | Determined by user role |
74
+
|All other in-call operations such as mute/unmute, screen share, etc. | Y | Y |
75
+
|All other in-call operations such as mute/unmute, screen share, etc. in Virtual Rooms| Determined by user role | Determined by user role |
76
76
77
-
## Revoke or update access token
77
+
You can use the `voip.join` scope together with [Rooms](./rooms/room-concept.md) to create a scheduled call where only invited users get access and where users are prohibited from creating any other calls.
78
+
79
+
### Revoke or update access token
78
80
- 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.
79
-
- The removal of an identity, resource, or subscription revokes all access tokens.
80
-
- 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.
81
-
- 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.
81
+
- The deletion of an identity, resource, or subscription revokes all access tokens.
82
+
- 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.
83
+
- Rotation of access keys revokes all active access tokens that were created by using a former access key. Consequently, all identities lose access to Azure Communication Services and need new access tokens.
84
+
85
+
## Client-server architecture
86
+
87
+
You should create and manage user access tokens through a trusted service and not create tokens in your client application. The connection string or Microsoft Entra credentials that are necessary to create user access tokens need to be protected, 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 get misused by somebody else.
88
+
89
+
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.
90
+
91
+
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.
92
+
93
+
:::image type="content" source="./media/architecture-identity.png" alt-text="Diagram that shows the user access token architecture." border="false":::
94
+
95
+
1. A user starts the client application.
96
+
1. The client application contacts your identity management service.
97
+
1. 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.
98
+
1. Create or find a Communication Services identity for the user.
99
+
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.
100
+
1._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.
101
+
1. The identity management service issues a user access token for the applicable identity and returns it to the client application.
82
102
83
-
## Considerations
84
-
- 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.
85
-
- 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).
86
-
- 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.
87
-
- We recommend issuing access tokens that have only the required scopes.
103
+
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](../../app-service/overview-authentication-authorization.md) users. They're integrated with [OpenID](../../app-service/configure-authentication-provider-openid-connect.md) and third-party identity providers like [Facebook](../../app-service/configure-authentication-provider-facebook.md).
88
104
89
105
## Next steps
90
106
91
-
*For an introduction to access token management, see [Create and manage access tokens](../quickstarts/identity/access-tokens.md).
107
+
*To learn how to issue tokens, see [Create and manage access tokens](../quickstarts/identity/access-tokens.md).
92
108
* For an introduction to authentication, see [Authenticate to Azure Communication Services](./authentication.md).
93
-
* For an introduction to data residency and privacy, see [Region availability and data residency](./privacy.md).
94
-
* To learn how to quickly create identities for testing, see the [quick-create identity quickstart](../quickstarts/identity/quick-create-identity.md).
109
+
* To read about data residency and privacy, see [Region availability and data residency](./privacy.md).
110
+
* To learn how to quickly create identities and tokens for testing, see the [quick-create identity quickstart](../quickstarts/identity/quick-create-identity.md).
111
+
* For a full sample of a simple identity management service, visit the [Trusted service tutorial](../tutorials/trusted-service-tutorial.md).
112
+
* For a more advanced identity management sample which integrates with Entra ID and Microsoft Graph, head over to [Authentication service hero sample](../samples/trusted-auth-sample.md).
Access tokens enable Azure Communication Services SDKs to [authenticate](../../concepts/authentication.md) directly against Azure Communication Services as a particular identity. You need to create access tokens if you want your users to join a call or chat thread within your application.
20
20
21
-
This article describes how to use the Azure Communication Services SDKs to create identities and manage your access tokens. For production use cases, we recommend that you generate access tokens on a server-side service as described in [Mobile architecture design](../../concepts/client-and-server-architecture.md).
21
+
This article describes how to use the Azure Communication Services SDKs to create identities and manage your access tokens. For production use cases, we recommend that you generate access tokens on a server-side service as described in [Client and server architecture](../../concepts/identity-model.md#client-server-architecture).
Copy file name to clipboardExpand all lines: articles/communication-services/tutorials/events-playbook.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -108,7 +108,7 @@ Attendee experience can be directly embedded into an application or platform usi
108
108
109
109
2. Before developers dive into using [Azure Communication Services](../overview.md), they must [create a resource](../quickstarts/create-communication-resource.md?pivots=platform-azp&tabs=windows&preserve-view=true).
110
110
111
-
3. Once a resource is created, developers must [generate access tokens](../quickstarts/identity/access-tokens.md?pivots=programming-language-javascript&preserve-view=true) for attendees to access Azure Communication Services. We recommend using a [trusted service architecture](../concepts/client-and-server-architecture.md).
111
+
3. Once a resource is created, developers must [generate access tokens](../quickstarts/identity/access-tokens.md?pivots=programming-language-javascript&preserve-view=true) for attendees to access Azure Communication Services. We recommend using a [trusted service architecture](../concepts/identity-model.md#client-server-architecture).
112
112
113
113
4. Developers can leverage [headless SDKs](../concepts/teams-interop.md) or [UI Library](../concepts/ui-library/ui-library-overview.md) using the join link URL to join the Teams meeting through [Teams Interoperability](../concepts/teams-interop.md). Details below:
0 commit comments