Azure.Communication.Identity 1.2.0

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
.NET Standard 2.0
dotnet add package Azure.Communication.Identity --version 1.2.0
NuGet\Install-Package Azure.Communication.Identity -Version 1.2.0
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.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Azure.Communication.Identity --version 1.2.0
#r "nuget: Azure.Communication.Identity, 1.2.0"
#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.2.0

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

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}");

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 Versions
.NET net5.0 net5.0-windows net6.0 net6.0-android net6.0-ios net6.0-maccatalyst net6.0-macos net6.0-tvos net6.0-windows net7.0 net7.0-android net7.0-ios net7.0-maccatalyst net7.0-macos net7.0-tvos net7.0-windows
.NET Core netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1
.NET Standard netstandard2.0 netstandard2.1
.NET Framework net461 net462 net463 net47 net471 net472 net48 net481
MonoAndroid monoandroid
MonoMac monomac
MonoTouch monotouch
Tizen tizen40 tizen60
Xamarin.iOS xamarinios
Xamarin.Mac xamarinmac
Xamarin.TVOS xamarintvos
Xamarin.WatchOS xamarinwatchos
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

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

Package Downloads
ToolsLibrary1

Package Description

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.2.0 51,445 10/11/2022
1.1.0 27,249 7/19/2022
1.1.0-beta.1 23,572 10/29/2021
1.0.1 256,519 5/25/2021
1.0.0 50,688 3/29/2021
1.0.0-beta.5 503 3/10/2021
1.0.0-beta.4 3,410 2/10/2021