Skip to content

Commit 1225b20

Browse files
Stefan GilcaStefan Gilca
Stefan Gilca
authored and
Stefan Gilca
committed
Add documentation for the custom id
1 parent b96009f commit 1225b20

File tree

3 files changed

+124
-1
lines changed

3 files changed

+124
-1
lines changed

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

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,20 @@ 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 SDK version `1.4.0-beta1`.
38+
> [!NOTE]
39+
> This feature is currently in preview.
40+
41+
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.
42+
43+
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.
44+
45+
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.
46+
47+
## Access tokens
3548

3649
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.
3750

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

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,40 @@ 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+
> [!NOTE] 
124+
> This feature is currently in preview.
125+
126+
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.
127+
128+
```javascript
129+
const customId = "[email protected]";
130+
let identityResponse = await identityClient.createUser({customId });
131+
console.log(`\nCreated an identity with ID: ${identityResponse.communicationUserId}`);
132+
```
133+
134+
## (Preview) Get identity details
135+
136+
> [!IMPORTANT] 
137+
> This feature is available starting with the SDK version `1.4.0-beta1`.
138+
> [!NOTE] 
139+
> This feature is currently in preview.
140+
141+
You can use the `getUserDetail` method to retrieve information about a user, including the `customId` and the `lastTokenIssuedAt`.
142+
143+
```javascript
144+
const customId = "[email protected]";
145+
let identityResponse = await identityClient.createUser({customId });
146+
var identity = userResponse.Value;
147+
var userDetails = client.getUserDetail(identity);
148+
console.log(`\nCreated an identity with ID: ${identityResponse.communicationUserId}`);
149+
console.log(`\nCustom id: ${userDetails.customId}`);
150+
console.log(`\nLast token issued at: ${userDetails.lastTokenIssuedAt}`);
151+
```
152+
119153
## Issue an access token
120154

121155
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 +192,27 @@ console.log(`\nIssued an access token with 'voip' scope that expires at ${expire
158192
console.log(token);
159193
```
160194

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

163218
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: 55 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+
> [!NOTE] 
130+
> This feature is currently in preview.
131+
132+
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.
133+
134+
```csharp
135+
var identityResponse = client.CreateUser(customId: "[email protected]");
136+
var identity = userResponse.Value;
137+
Console.WriteLine($"\nCreated an identity with ID: {identity.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+
> [!NOTE] 
145+
> This feature is currently in preview.
146+
147+
You can use the `GetUserDetail` method to retrieve information about a user, including the `customId` and the `lastTokenIssuedAt`.
148+
149+
```csharp
150+
var identityResponse = await client.CreateUserAsync(customId: "[email protected]");
151+
var identity = userResponse.Value;
152+
var userDetails = client.GetUserDetail(identity);
153+
Console.WriteLine($"User id: {userDetails.Value.User.Id}");
154+
Console.WriteLine($"Custom id: {userDetails.Value.CustomId}");
155+
Console.WriteLine($"Last token issued at: {userDetails.Value.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,28 @@ 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+
> [!NOTE] 
208+
> This feature is currently in preview.
209+
210+
You can pass your custom ID to the `CreateUserAndTokenAsync` method to create an identity and issue an access token in a single call.
211+
212+
```csharp
213+
// Issue an identity and an access token with a validity of 24 hours and the "voip" scope for the new identity
214+
var identityAndTokenResponse = await client.CreateUserAndTokenAsync(customId: "[email protected]", scopes: new[] { CommunicationTokenScope.VoIP });
215+
216+
// Retrieve the identity, token, and expiration date from the response
217+
var identity = identityAndTokenResponse.Value.User;
218+
var token = identityAndTokenResponse.Value.AccessToken.Token;
219+
var expiresOn = identityAndTokenResponse.Value.AccessToken.ExpiresOn;
220+
Console.WriteLine($"\nCreated an identity with ID: {identity.Id}");
221+
Console.WriteLine($"\nIssued an access token with 'voip' scope that expires at {expiresOn}:");
222+
Console.WriteLine(token);
223+
```
224+
170225
## Refresh an access token
171226

172227
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)