Azure.Communication.Identity 1.3.1

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
dotnet add package Azure.Communication.Identity --version 1.3.1
NuGet\Install-Package Azure.Communication.Identity -Version 1.3.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Azure.Communication.Identity" Version="1.3.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Azure.Communication.Identity --version 1.3.1
#r "nuget: Azure.Communication.Identity, 1.3.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Azure.Communication.Identity as a Cake Addin
#addin nuget:?package=Azure.Communication.Identity&version=1.3.1

// Install Azure.Communication.Identity as a Cake Tool
#tool nuget:?package=Azure.Communication.Identity&version=1.3.1

Azure Communication Identity client library for .NET

Azure Communication Identity is managing tokens for Azure Communication Services.

Source code | Product documentation | Samples

Getting started

Install the package

Install the Azure Communication Identity client library for .NET with NuGet:

dotnet add package Azure.Communication.Identity

Prerequisites

You need an Azure subscription and a Communication Service Resource to use this package.

To create a new Communication Service, you can use the Azure Portal, the Azure PowerShell, or the .NET management client library.

Authenticate the client

The identity client can be authenticated using a connection string acquired from an Azure Communication Resources in the Azure Portal.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);

Or alternatively using the endpoint and access key acquired from an Azure Communication Resources in the Azure Portal.

var endpoint = new Uri("https://my-resource.communication.azure.com");
var accessKey = "<access_key>";
var client = new CommunicationIdentityClient(endpoint, new AzureKeyCredential(accessKey));

Clients also have the option to authenticate using a valid Active Directory token.

var endpoint = new Uri("https://my-resource.communication.azure.com");
TokenCredential tokenCredential = new DefaultAzureCredential();
var client = new CommunicationIdentityClient(endpoint, tokenCredential);

Key concepts

CommunicationIdentityClient provides the functionalities to manage user access tokens: creating new ones and revoking them.

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

Creating a new user

Response<CommunicationUserIdentifier> userResponse = await client.CreateUserAsync();
CommunicationUserIdentifier user = userResponse.Value;
Console.WriteLine($"User id: {user.Id}");

Getting a token for an existing user

Response<AccessToken> tokenResponse = await client.GetTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat });
string token = tokenResponse.Value.Token;
DateTimeOffset expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"Token: {token}");
Console.WriteLine($"Expires On: {expiresOn}");

The GetToken function takes in a list of CommunicationTokenScope. Scope options include:

  • Chat (Use this for full access to Chat APIs)
  • VoIP (Use this for full access to Calling APIs)
  • ChatJoin (Access to Chat APIs but without the authorization to create, delete or update chat threads)
  • ChatJoinLimited (A more limited version of ChatJoin that doesn't allow to add or remove participants)
  • VoIPJoin (Access to Calling APIs but without the authorization to start new calls)

It's also possible to create a Communication Identity access token by customizing the expiration time. Validity period of the token must be within [1,24] hours range. If not provided, the default value of 24 hours will be used.

TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
Response<AccessToken> tokenResponse = await client.GetTokenAsync(user, scopes: new[] { CommunicationTokenScope.Chat }, tokenExpiresIn);
string token = tokenResponse.Value.Token;
DateTimeOffset expiresOn = tokenResponse.Value.ExpiresOn;
Console.WriteLine($"Token: {token}");
Console.WriteLine($"Expires On: {expiresOn}");

Creating a user and a token in the same request

Response<CommunicationUserIdentifierAndToken> response = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.Chat });
var (user, token) = response.Value;
Console.WriteLine($"User id: {user.Id}");
Console.WriteLine($"Token: {token.Token}");

It's also possible to create a Communication Identity access token by customizing the expiration time. Validity period of the token must be within [1,24] hours range. If not provided, the default value of 24 hours will be used.

TimeSpan tokenExpiresIn = TimeSpan.FromHours(1);
Response<CommunicationUserIdentifierAndToken> response = await client.CreateUserAndTokenAsync(scopes: new[] { CommunicationTokenScope.Chat }, tokenExpiresIn);
var (user, token) = response.Value;
Console.WriteLine($"User id: {user.Id}");
Console.WriteLine($"Token: {token.Token}");

Revoking a user's tokens

In case a user's tokens are compromised or need to be revoked:

Response revokeResponse = await client.RevokeTokensAsync(user);

Deleting a user

Response deleteResponse = await client.DeleteUserAsync(user);

Exchanging Azure AD access token of a Teams User for a Communication Identity access token

The CommunicationIdentityClient can be used to exchange an Azure AD access token of a Teams user for a new Communication Identity access token with a matching expiration time.

The GetTokenForTeamsUser function accepts the following parameters wrapped into the GetTokenForTeamsUserOptions option bag:

  • teamsUserAadToken Azure Active Directory access token of a Teams user
  • clientId Client ID of an Azure AD application to be verified against the appId claim in the Azure AD access token
  • userObjectId Object ID of an Azure AD user (Teams User) to be verified against the OID claim in the Azure AD access token
Response<AccessToken> tokenResponse = await client.GetTokenForTeamsUserAsync(new GetTokenForTeamsUserOptions(teamsUserAadToken, clientId, userObjectId));
string token = tokenResponse.Value.Token;
Console.WriteLine($"Token: {token}");

Troubleshooting

All User token service operations will throw a RequestFailedException on failure.

// Get a connection string to our Azure Communication resource.
var connectionString = "<connection_string>";
var client = new CommunicationIdentityClient(connectionString);

try
{
    Response<CommunicationUserIdentifier> response = await client.CreateUserAsync();
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.Message);
}

Next steps

Read more about Communication user access tokens

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit cla.microsoft.com.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on Azure.Communication.Identity:

Package Downloads
ToolsLibrary1

Package Description

Promact.EmailService.Azure

Email service implementation for sending emails via Azure

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Azure.Communication.Identity:

Repository Stars
Azure/azure-functions-kafka-extension
Kafka extension for Azure Functions
Version Downloads Last updated
1.3.1 7,438 3/22/2024
1.3.0 63,986 11/28/2023
1.2.0 281,413 10/11/2022
1.1.0 43,461 7/19/2022
1.1.0-beta.1 25,771 10/29/2021
1.0.1 311,611 5/25/2021
1.0.0 94,068 3/29/2021
1.0.0-beta.5 557 3/10/2021
1.0.0-beta.4 4,323 2/10/2021