Skip to content

Commit 96bc054

Browse files
prmerger-automator[bot]prmerger-automator[bot]
authored
Merge pull request #299399 from stefang931/gistefan/add_custom_id_documentation
Add preview support for customId in identity creation and mapping documentation
2 parents a93d674 + 3341a5c commit 96bc054

File tree

3 files changed

+128
-1
lines changed

3 files changed

+128
-1
lines changed

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

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,21 @@ You can create Azure Communication Service user identities for free. The only ch
3131

3232
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).
3333

34-
## Access tokens
34+
## (Preview) Simplify identity mapping with `customId`
35+
36+
> [!IMPORTANT]
37+
> This feature is available starting with the Identity SDK version `1.4.0-beta1` and REST API version `2025-03-02-preview`.
38+
39+
> [!NOTE]
40+
> This feature is currently in preview.
41+
42+
Previously, developers were responsible for maintaining a mapping between their own user identity system and Azure Communication Services identities. With the introduction of the `customId` parameter, you can now associate your own user identifiers—such as email addresses or internal user IDs—directly when creating a Communication Services identity.
43+
44+
When you create a user with a `customId`, Azure Communication Services will return the same identity if you call the method again with the same `customId`. This eliminates the need to store and manage the mapping yourself.
45+
46+
This feature is supported in both the SDK and REST API, and is especially useful for scenarios where you want to maintain a consistent identity across sessions, devices, or services without additional storage overhead.
47+
48+
## Access tokens
3549

3650
After you create a user identity, the end-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 of `chat` scope can participate in chat. Only a user with a token of `voip` scope can participate in a VoIP call.
3751

‎articles/communication-services/quickstarts/identity/includes/access-tokens/access-token-js.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,41 @@ console.log(`\nCreated an identity with ID: ${identityResponse.communicationUser
116116

117117
Store the received identity with mapping to your application's users (for example, by storing it in your application server database).
118118
119+
## (Preview) Create an identity with an associated custom ID
120+
121+
> [!IMPORTANT]
122+
> This feature is available starting with the SDK version `1.4.0-beta1`.
123+
124+
> [!NOTE]
125+
> This feature is currently in preview.
126+
127+
You can create an identity with an associated `customId` to map your application's user identities to Azure Communication Services identities. When you call `createUser` with the same `customId`, the service returns the same `communicationUserId`. This eliminates the need to store the mapping yourself.
128+
129+
```javascript
130+
const customId = "[email protected]";
131+
let user = await identityClient.createUser({ customId });
132+
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
133+
```
134+
135+
## (Preview) Get identity details
136+
137+
> [!IMPORTANT]
138+
> This feature is available starting with the SDK version `1.4.0-beta1`.
139+
140+
> [!NOTE]
141+
> This feature is currently in preview.
142+
143+
You can use the `getUserDetail` method to retrieve information about a user, including the `customId` and the `lastTokenIssuedAt`.
144+
145+
```javascript
146+
const customId = "[email protected]";
147+
let user = await identityClient.createUser({ customId });
148+
let userDetails = client.getUserDetail(user);
149+
console.log(`\nUser ID: ${user.communicationUserId}`);
150+
console.log(`\nCustom ID: ${userDetails.customId}`);
151+
console.log(`\nLast token issued at: ${userDetails.lastTokenIssuedAt}`);
152+
```
153+
119154
## Issue an access token
120155

121156
Use the `getToken` method to issue an access token for your Communication Services identity. The `scopes` parameter defines a set of access token permissions and roles. For more information, see the list of supported actions in [Identity model](../../../../concepts/identity-model.md#access-tokens). You can also construct a new instance of a `communicationUser` based on a string representation of the Azure Communication Service identity.
@@ -158,6 +193,28 @@ console.log(`\nIssued an access token with 'voip' scope that expires at ${expire
158193
console.log(token);
159194
```
160195

196+
### (Preview) Create an identity and issue a token in one method call including a customId
197+
198+
> [!IMPORTANT]
199+
> This feature is available starting with the SDK version `1.4.0-beta1`.
200+
201+
> [!NOTE]
202+
> This feature is currently in preview.
203+
204+
You can pass your custom ID to the `createUserAndToken` method to create an identity and issue an access token in a single call.
205+
206+
```javascript
207+
// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
208+
const customId = "[email protected]";
209+
let identityTokenResponse = await identityClient.createUserAndToken(["voip"], { customId });
210+
211+
// Get the token, its expiration date, and the user from the response
212+
const { token, expiresOn, user } = identityTokenResponse;
213+
console.log(`\nCreated an identity with ID: ${user.communicationUserId}`);
214+
console.log(`\nIssued an access token with 'voip' scope that expires at ${expiresOn}:`);
215+
console.log(token);
216+
```
217+
161218
## Refresh an access token
162219

163220
As tokens expire, you need to refresh them. To refresh tokens, call `getToken` again with the same identity used to issue the tokens. You also need to provide the `scopes` of the refreshed tokens.

‎articles/communication-services/quickstarts/identity/includes/access-tokens/access-token-net.md

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,39 @@ Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
122122

123123
Store the received identity with mapping to your application users (for example, by storing it in your application server database).
124124

125+
## (Preview) Create an identity with an associated customId
126+
127+
> [!IMPORTANT]
128+
> This feature is available starting with the SDK version `1.4.0-beta1`.
129+
130+
> [!NOTE]
131+
> This feature is currently in preview.
132+
133+
You can create an identity with an associated `customId` to map your application's user identities with Azure Communication Services identities. If you call the `CreateUser` method again with the same `customId`, it will return the same `user.Id`. This eliminates the need to store the mapping yourself.
134+
135+
```csharp
136+
Response<CommunicationUserIdentifier> user = await client.CreateUserAsync(customId: "[email protected]");
137+
Console.WriteLine($"\nCreated an identity with ID: {user.Id}");
138+
```
139+
140+
## (Preview) Get identity details
141+
142+
> [!IMPORTANT]
143+
> This feature is available starting with the SDK version `1.4.0-beta1`.
144+
145+
> [!NOTE]
146+
> This feature is currently in preview.
147+
148+
You can use the `GetUserDetail` method to retrieve information about a user, including the `customId` and the `lastTokenIssuedAt`.
149+
150+
```csharp
151+
Response<CommunicationUserIdentifier> user = await client.CreateUserAsync(customId: "[email protected]");
152+
var userDetails = client.GetUserDetail(user);
153+
Console.WriteLine($"User ID: {userDetails.Id}");
154+
Console.WriteLine($"Custom ID: {userDetails.CustomId}");
155+
Console.WriteLine($"Last token issued at: {userDetails.LastTokenIssuedAt}");
156+
```
157+
125158
## Issue an access token
126159

127160
After you have a Communication Services identity, use the `GetToken` method to issue an access token for it. The `scopes` parameter defines a set of access token permissions and roles. For more information, see the list of supported actions in [Identity model](../../../../concepts/identity-model.md#access-tokens). You can also construct a new instance of `communicationUser` based on a string representation of an Azure Communication Service identity.
@@ -167,6 +200,29 @@ Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {
167200
Console.WriteLine(token);
168201
```
169202

203+
### (Preview) Create and identity and issue a token in the same request with a custom ID
204+
205+
> [!IMPORTANT]
206+
> This feature is available starting with the SDK version `1.4.0-beta1`.
207+
208+
> [!NOTE]
209+
> This feature is currently in preview.
210+
211+
You can pass your custom ID to the `CreateUserAndTokenAsync` method to create an identity and issue an access token in a single call.
212+
213+
```csharp
214+
// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
215+
Response<CommunicationUserIdentifierAndToken> identityAndTokenResponse = await client.CreateUserAndTokenAsync(customId: "[email protected]", scopes: new[] { CommunicationTokenScope.VoIP });
216+
217+
// Retrieve the identity, token, and expiration date from the response
218+
var identity = identityAndTokenResponse.User;
219+
var token = identityAndTokenResponse.AccessToken.Token;
220+
var expiresOn = identityAndTokenResponse.AccessToken.ExpiresOn;
221+
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
222+
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
223+
Console.WriteLine(token);
224+
```
225+
170226
## Refresh an access token
171227

172228
To refresh an access token, pass an instance of the `CommunicationUserIdentifier` object into `GetTokenAsync`. If you stored this `Id` and need to create a new `CommunicationUserIdentifier`, you can do so by passing your stored `Id` into the `CommunicationUserIdentifier` constructor as follows:

0 commit comments

Comments
 (0)