Skip to content

Commit dc85e61

Browse files
committed
Next batch
second commit
1 parent 626581e commit dc85e61

14 files changed

+116
-102
lines changed

articles/communication-services/concepts/authentication.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,5 +92,6 @@ The user identity is intended to act as a primary key for logs and metrics colle
9292
> [!div class="nextstepaction"]
9393
> [Trusted authentication service hero sample](../samples/trusted-auth-sample.md)
9494
95-
For more information, see the following articles:
95+
## Related articles
96+
9697
- [Learn about client and server architecture](../concepts/identity-model.md#client-server-architecture)

articles/communication-services/concepts/credentials-best-practices.md

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
2-
title: Azure Communication Services - Credentials best practices
2+
title: Credentials best practices
3+
titleSuffix: An Azure Communication Services article
34
description: Learn more about the best practices for managing User Access Tokens in SDKs
45
author: petrsvihlik
56
manager: soricos
@@ -12,9 +13,9 @@ ms.service: azure-communication-services
1213
#Customer intent: As a developer, I want learn how to correctly handle Credential objects so that I can build applications that run efficiently.
1314
---
1415

15-
# Credentials in Communication SDKs
16+
# Credentials best practices
1617

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.
1819

1920
## Communication Token Credential
2021

@@ -28,7 +29,7 @@ Depending on your scenario, you may want to adjust the lifespan of tokens issued
2829
- Use a [callback function](#callback-function) for agents using the application for longer periods of time.
2930

3031
### 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:
3233

3334
```javascript
3435
const tokenOptions = { tokenExpiresInMinutes: 60 };
@@ -58,7 +59,7 @@ const tokenCredential = new AzureCommunicationTokenCredential({
5859

5960
## Token refreshing
6061

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.
6263

6364
### Example 1: Refreshing a token for a Communication User
6465

@@ -106,10 +107,10 @@ app.post('/getTokenForTeamsUser', async (req, res) => {
106107
});
107108
```
108109

109-
Next, we need to implement a token refresher callback in the client application, whose responsibility will be to:
110+
Next, we need to implement a token refresher callback in the client application, whose responsibility is to:
110111

111-
1. Refresh the Microsoft Entra access token of the Teams User
112-
2. Exchange the Microsoft Entra access token of the Teams User for a Communication Identity access token
112+
1. Refresh the Microsoft Entra access token of the Teams User.
113+
2. Exchange the Microsoft Entra access token of the Teams User for a Communication Identity access token.
113114

114115
```javascript
115116
const fetchTokenFromMyServerForUser = async function (abortSignal, username) {
@@ -171,7 +172,7 @@ const refreshAadToken = async function (abortSignal, username) {
171172

172173
## Providing an initial token
173174

174-
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.
175176

176177
```javascript
177178
const tokenCredential = new AzureCommunicationTokenCredential({
@@ -182,7 +183,7 @@ const tokenCredential = new AzureCommunicationTokenCredential({
182183

183184
## Proactive token refreshing
184185

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.
186187

187188
```javascript
188189
const tokenCredential = new AzureCommunicationTokenCredential({
@@ -242,7 +243,7 @@ const publicClientApplication = new PublicClientApplication({
242243
## Canceling refreshing
243244
244245
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.*
246247
247248
```javascript
248249
var controller = new AbortController();
@@ -286,7 +287,7 @@ If you want to cancel subsequent refresh tasks, [dispose](#cleaning-up-resources
286287
287288
### Cleaning up resources
288289
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.
290291
291292
Call the `.dispose()` function.
292293
@@ -309,14 +310,14 @@ Depending on your scenario, you may want to sign a user out from one or more ser
309310
310311
## Next steps
311312
312-
In this article, you learned how to:
313+
This article described how to:
313314
314315
> [!div class="checklist"]
315316
> * Correctly initialize and dispose of a Credential object
316317
> * Implement a token refresher callback
317318
> * Optimize your token refreshing logic
318319
319-
To learn more, you may want to explore the following quickstart guides:
320+
## Related articles
320321
321322
* [Create and manage access tokens](../quickstarts/identity/access-tokens.md)
322323
* [Manage access tokens for Teams users](../quickstarts/manage-teams-identity.md)

articles/communication-services/concepts/government.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,8 @@ Azure Communication Services is committed to releasing these features as part of
3838

3939
## Related articles
4040

41-
- [Office 365 Government plans](https://www.microsoft.com/en-us/microsoft-365/enterprise/government-plans-and-pricing)
41+
- [Office 365 Government plans](https://www.microsoft.com/microsoft-365/enterprise/government-plans-and-pricing)
4242

4343
- [Office 365 GCC High and DoD](/office365/servicedescriptions/office-365-platform-service-description/office-365-us-government/gcc-high-and-dod)
4444

45-
- [Eligibility requirements for Azure Government](https://azure.microsoft.com/en-us/explore/global-infrastructure/government/how-to-buy/)
45+
- [Eligibility requirements for Azure Government](https://azure.microsoft.com/explore/global-infrastructure/government/how-to-buy/)

articles/communication-services/concepts/identifiers.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: Communication Identifier types
3-
titleSuffix: An Azure Communication Services concept
4-
description: Understand identifier types and their usage
2+
title: Understand Identifiers
3+
titleSuffix: An Azure Communication Services article
4+
description: Understand identifier types and how to use them.
55
author: DominikMe
66
manager: RezaJooyandeh
77
services: azure-communication-services
@@ -15,16 +15,16 @@ ms.custom: devx-track-extended-java, devx-track-js, devx-track-python
1515
zone_pivot_groups: acs-js-csharp-java-python-ios-android-rest
1616
---
1717

18-
# Understand identifier types
18+
# Understand identifiers
1919

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 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.
2121

2222
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.
2323

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.
2525

2626

27-
## The CommunicationIdentifier type
27+
## The `CommunicationIdentifier` type
2828

2929
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.
3030

articles/communication-services/concepts/includes/identifiers/identifiers-android.md

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,7 @@ ms.author: domessin
1515

1616
### Communication user
1717

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.
2019

2120
#### Basic usage
2221

@@ -35,7 +34,7 @@ CommunicationUserIdentifier sameUser = new CommunicationUserIdentifier(newUserId
3534

3635
### Microsoft Teams user
3736

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.
3938

4039
#### Basic usage
4140

@@ -73,7 +72,7 @@ PhoneNumberIdentifier phoneNumber = new PhoneNumberIdentifier("+112345556789");
7372

7473
### Microsoft Teams Application
7574

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).
7776

7877
#### Basic usage
7978

@@ -101,7 +100,7 @@ MicrosoftTeamsAppIdentifier gcchTeamsAppIdentifier = new MicrosoftTeamsAppIdenti
101100

102101
### Unknown
103102

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.
105104

106105
#### Basic usage
107106

@@ -142,7 +141,7 @@ else {
142141

143142
## Raw ID representation
144143

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.
146145

147146
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.
148147

@@ -156,4 +155,4 @@ String rawId = communicationIdentifier.getRawId();
156155
CommunicationIdentifier identifier = CommunicationIdentifier.fromRawId(rawId);
157156
```
158157

159-
An invalid raw ID will just convert to an `UnknownIdentifier` in the SDK and any validation only happens service-side.
158+
An invalid raw ID converts to `UnknownIdentifier` in the SDK and any validation only happens service-side.

0 commit comments

Comments
 (0)