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
#Customer intent: As a developer, I want learn how to correctly handle Credential objects so that I can build applications that run efficiently.
13
14
---
14
15
15
-
# Credentials in Communication SDKs
16
+
# Credentials best practices
16
17
17
-
This article provides best practices for managing [User Access Tokens](./authentication.md#user-access-tokens) in Azure Communication Services SDKs. Following this guidance will help you optimize the resources used by your application and reduce the number of roundtrips to the Azure Communication Identity API.
18
+
This article provides best practices for managing [User Access Tokens](./authentication.md#user-access-tokens) in Azure Communication Services SDKs. Follow this guidance to optimize the resources used by your application and reduce the number of roundtrips to the Azure Communication Identity API.
18
19
19
20
## Communication Token Credential
20
21
@@ -28,7 +29,7 @@ Depending on your scenario, you may want to adjust the lifespan of tokens issued
28
29
- Use a [callback function](#callback-function) for agents using the application for longer periods of time.
29
30
30
31
### Setting a custom token expiration time
31
-
When requesting a new token, we recommend using short lifetime tokens for one-off Chat messages or time-limited Calling sessions and longer lifetime tokens for agents using the application for longer periods of time. The default token expiration time is 24 hours but you can customize it by providing a value between an hour and 24 hours to the optional parameter as follows:
32
+
When requesting a new token, we recommend using short lifetime tokens for one-off Chat messages or time-limited Calling sessions. We recommend longer lifetime tokens for agents using the application for longer periods of time. The default token expiration time is 24 hours. You can customize the expiration time by providing a value between an hour and 24 hours to the optional parameter as follows:
32
33
33
34
```javascript
34
35
consttokenOptions= { tokenExpiresInMinutes:60 };
@@ -58,7 +59,7 @@ const tokenCredential = new AzureCommunicationTokenCredential({
58
59
59
60
## Token refreshing
60
61
61
-
To correctly implement the token refresher callback, the code must return a string with a valid JSON Web Token (JWT). It's necessary that the returned token is valid (its expiration date is set in the future) at all times. Some platforms, such as JavaScript and .NET, offer a way to abort the refresh operation, and pass `AbortSignal` or `CancellationToken` to your function. It's recommended to accept these objects, utilize them or pass them further.
62
+
To correctly implement the token refresher callback, the code must return a string with a valid JSON Web Token (JWT). The returned token must always be valid and its expiration date set in the future. Some platforms, such as JavaScript and .NET, offer a way to abort the refresh operation, and pass `AbortSignal` or `CancellationToken` to your function. We recommended that you accept these objects, utilize them, or pass them further.
62
63
63
64
### Example 1: Refreshing a token for a Communication User
To further optimize your code, you can fetch the token at the application's startup and pass it to the Credential directly. Providing an initial token will skip the first call to the refresher callback function while preserving all subsequent calls to it.
175
+
To further optimize your code, you can fetch the token at the application's startup and pass it to the Credential directly. Providing an initial token skips the first call to the refresher callback function while preserving all subsequent calls to it.
@@ -182,7 +183,7 @@ const tokenCredential = new AzureCommunicationTokenCredential({
182
183
183
184
## Proactive token refreshing
184
185
185
-
Use proactive refreshing to eliminate any possible delay during the on-demand fetching of the token. The proactive refreshing will refresh the token in the background at the end of its lifetime. When the token is about to expire, 10 minutes before the end of its validity, the Credential will start attempting to retrieve the token. It will trigger the refresher callback with increasing frequency until it succeeds and retrieves a token with long enough validity.
186
+
Use proactive refreshing to eliminate any possible delay during the on-demand fetching of the token. The proactive refreshing updates the token in the background at the end of its lifetime. When the token is about to expire, 10 minutes before the end of its validity, the Credential start attempting to retrieve the token. It triggers the refresher callback with increasing frequency until it succeeds and retrieves a token with long enough validity.
@@ -242,7 +243,7 @@ const publicClientApplication = new PublicClientApplication({
242
243
## Canceling refreshing
243
244
244
245
For the Communication clients to be able to cancel ongoing refresh tasks, it's necessary to pass a cancellation object to the refresher callback.
245
-
*Note that this pattern applies only to JavaScript and .NET.*
246
+
*This pattern applies only to JavaScript and .NET.*
246
247
247
248
```javascript
248
249
var controller =newAbortController();
@@ -286,7 +287,7 @@ If you want to cancel subsequent refresh tasks, [dispose](#cleaning-up-resources
286
287
287
288
### Cleaning up resources
288
289
289
-
Since the Credential object can be passed to multiple Chat or Calling client instances, the SDK will make no assumptions about its lifetime and leaves the responsibility of its disposal to the developer. It's up to the Communication Services applications to dispose the Credential instance when it's no longer needed. Disposing the credential will also cancel scheduled refresh actions when the proactive refreshing is enabled.
290
+
Since the Credential object can be passed to multiple Chat or Calling client instances, the SDK makes no assumptions about its lifetime and leaves the responsibility of its disposal to the developer. It's up to the Communication Services applications to dispose the Credential instance when it's no longer needed. Disposing the credential also cancels scheduled refresh actions when proactive refreshing is enabled.
290
291
291
292
Call the `.dispose()` function.
292
293
@@ -309,14 +310,14 @@ Depending on your scenario, you may want to sign a user out from one or more ser
309
310
310
311
## Next steps
311
312
312
-
In this article, you learned how to:
313
+
This article described how to:
313
314
314
315
> [!div class="checklist"]
315
316
> * Correctly initialize and dispose of a Credential object
316
317
> * Implement a token refresher callback
317
318
> * Optimize your token refreshing logic
318
319
319
-
To learn more, you may want to explore the following quickstart guides:
320
+
## Related articles
320
321
321
322
* [Create and manage access tokens](../quickstarts/identity/access-tokens.md)
322
323
* [Manage access tokens for Teams users](../quickstarts/manage-teams-identity.md)
Communication Services SDKs and REST APIs use the *identifier* type to identify who is communicating with whom. For example, identifiers specify who to call, or who has sent a chat message.
20
+
Communication Services SDKs and REST APIs use the *identifier* type to identify who is communicating with whom. For example, identifiers specify who to call, or who sent a chat message.
21
21
22
22
Depending on context, identifiers get wrapped with extra properties, like inside the `ChatParticipant` in the Chat SDK or inside the `RemoteParticipant` in the Calling SDK.
23
23
24
-
In this article, you'll learn about different types of identifiers and how they look across programming languages. You'll also get tips on how to use them.
24
+
This article describes different types of identifiers and how they look across programming languages. You also get tips on how to use them.
25
25
26
26
27
-
## The CommunicationIdentifier type
27
+
## The `CommunicationIdentifier` type
28
28
29
29
There are user identities that you create yourself and there are external identities. Microsoft Teams users and phone numbers are external identities that come to play in interop scenarios. Each of these different identity types has a corresponding identifier that represents it. An identifier is a structured type that offers type-safety and works well with your editor's code completion.
Copy file name to clipboardExpand all lines: articles/communication-services/concepts/includes/identifiers/identifiers-android.md
+6-7Lines changed: 6 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,8 +15,7 @@ ms.author: domessin
15
15
16
16
### Communication user
17
17
18
-
The `CommunicationUserIdentifier` represents a user identity that was created using the [Identity SDK or REST API](../../../quickstarts/identity/access-tokens.md). It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.
19
-
18
+
The `CommunicationUserIdentifier` represents a user identity created using the [Identity SDK or REST API](../../../quickstarts/identity/access-tokens.md). It's the only identifier used if your application doesn't use Microsoft Teams interoperability or Telephony features.
20
19
21
20
#### Basic usage
22
21
@@ -35,7 +34,7 @@ CommunicationUserIdentifier sameUser = new CommunicationUserIdentifier(newUserId
35
34
36
35
### Microsoft Teams user
37
36
38
-
The `MicrosoftTeamsUserIdentifier` represents a Teams user with its Microsoft Entra user object ID. You can retrieve the Microsoft Entra user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response. For more information on how to work with Microsoft Graph, try the [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer?request=users%2F%7Buser-mail%7D&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com) and look into the [Graph SDK](/graph/sdks/sdks-overview). Alternatively, you can find the ID as the `oid` claim in an [ID token](/entra/identity-platform/id-token-claims-reference#payload-claims) or [Microsoft Entra access token](/entra/identity-platform/access-token-claims-reference#payload-claims) after your user has signed in and acquired a token.
37
+
The `MicrosoftTeamsUserIdentifier` represents a Teams user with its Microsoft Entra user object ID. You can retrieve the Microsoft Entra user object ID via the [Microsoft Graph REST API /users](/graph/api/user-get) endpoint from the `id` property in the response. For more information about working with Microsoft Graph, see [Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer?request=users%2F%7Buser-mail%7D&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com) and look into the [Graph SDK](/graph/sdks/sdks-overview). Alternatively, you can find the ID as the `oid` claim in an [ID token](/entra/identity-platform/id-token-claims-reference#payload-claims) or [Microsoft Entra access token](/entra/identity-platform/access-token-claims-reference#payload-claims) after your user signed in and acquired a token.
39
38
40
39
#### Basic usage
41
40
@@ -73,7 +72,7 @@ PhoneNumberIdentifier phoneNumber = new PhoneNumberIdentifier("+112345556789");
73
72
74
73
### Microsoft Teams Application
75
74
76
-
The `MicrosoftTeamsAppIdentifier` interface represents a bot of the Teams Voice applications such as Call Queue and Auto Attendant with its Microsoft Entra bot object ID. The Teams applications should be configured with a resource account. You can retrieve the Microsoft Entra bot object ID via the [Microsoft Graph REST API /users](/graph/api/user-list) endpoint from the `id` property in the response. For more information on how to work with Microsoft Graph, try the[Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer?request=users%2F%7Buser-mail%7D&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com) and look into the [Graph SDK](/graph/sdks/sdks-overview).
75
+
The `MicrosoftTeamsAppIdentifier` interface represents a bot of the Teams Voice applications such as Call Queue and Auto Attendant with its Microsoft Entra bot object ID. Configure the Teams applications with a resource account. You can retrieve the Microsoft Entra bot object ID via the [Microsoft Graph REST API /users](/graph/api/user-list) endpoint from the `id` property in the response. For more information about working with Microsoft Graph, see[Graph Explorer](https://developer.microsoft.com/en-us/graph/graph-explorer?request=users%2F%7Buser-mail%7D&method=GET&version=v1.0&GraphUrl=https://graph.microsoft.com) and look into the [Graph SDK](/graph/sdks/sdks-overview).
77
76
78
77
#### Basic usage
79
78
@@ -101,7 +100,7 @@ MicrosoftTeamsAppIdentifier gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdenti
101
100
102
101
### Unknown
103
102
104
-
The `UnknownIdentifier` exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type has been introduced recently. Any unknown identifier from the service will be deserialized to the`UnknownIdentifier` in the SDK.
103
+
The `UnknownIdentifier` exists for future-proofing and you might encounter it when you are on an old version of the SDK and a new identifier type is recently introduced. Any unknown identifier from the service deserializes to`UnknownIdentifier` in the SDK.
105
104
106
105
#### Basic usage
107
106
@@ -142,7 +141,7 @@ else {
142
141
143
142
## Raw ID representation
144
143
145
-
Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you'd like to use it as a URL parameter.
144
+
Sometimes you need to serialize an identifier to a flat string. For example, if you want to store the identifier in a database table or if you want to use it as a URL parameter.
146
145
147
146
For that purpose, identifiers have another representation called `RawId`. An identifier can always be translated to its corresponding raw ID, and a valid raw ID can always be converted to an identifier.
0 commit comments