Azure Identity client library for .NET

The Azure Identity library provides Azure Active Directory token authentication support across the Azure SDK. It provides a set of TokenCredential implementations which can be used to construct Azure SDK clients which support AAD token authentication.

This library is in preview and currently supports:

• Service principal authentication
• Managed identity authentication
• User principal authentication

Source code | Package (nuget) | API reference documentation | Azure Active Directory documentation

Getting started

Install the package

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

Install-Package Azure.Identity -IncludePrerelease

Prerequisites

• An Azure subscription.
• An existing Azure Active Directory service principal. If you need to create a service principal, you can use the Azure Portal or Azure CLI.

Creating a Service Principal with the Azure CLI

Use the Azure CLI snippet below to create/get client secret credentials.

• Create a service principal and configure its access to Azure resources:

  az ad sp create-for-rbac -n <your-application-name> --skip-assignment
  

  Output:

  {
      "appId": "generated-app-ID",
      "displayName": "dummy-app-name",
      "name": "http://dummy-app-name",
      "password": "random-password",
      "tenant": "tenant-ID"
  }
  

• Use the returned credentials above to set AZURE_CLIENT_ID(appId), AZURE_CLIENT_SECRET(password) and AZURE_TENANT_ID(tenant) environment variables.

Key concepts

Credentials

A credential is a class which contains or can obtain the data needed for a service client to authenticate requests. Service clients across Azure SDK accept credentials when they are constructed and use those credentials to authenticate requests to the service. Azure Identity offers a variety of credential classes in the Azure.Identity namespace capable of acquiring an AAD token. All of these credential classes are implementations of the TokenCredential abstract class in Azure.Core, and can be used by any service client which can be constructed with a TokenCredential.

The credential types in Azure Identity differ in the types of AAD identities they can authenticate and how they are configured:

credential class	identity	configuration
DefaultAzureCredential	service principal or managed identity	none for managed identity; environment variables for service principal
ManagedIdentityCredential	managed identity	constructor parameters
EnvironmentCredential	service principal	environment variables
ClientSecretCredential	service principal	constructor parameters
CertificateCredential	service principal	constructor parameters
UserPasswordCredential	user principal	constructor parameters
DeviceCodeCredential	user principal	constructor parameters / interactive
InteractiveBrowserCredential	user principal	constructor parameters / interactive

Credentials can be chained together to be tried in turn until one succeeds using the ChainedTokenCredential; see chaining credentials for details.

Note: All credential implementations in the Azure Identity library are threadsafe, and a single credential instance can be used to create multiple service clients.

DefaultAzureCredential

DefaultAzureCredential is appropriate for most scenarios where the application is intended to run in the Azure Cloud. This is because the DefaultAzureCredential determines the appropriate credential type based of the environment it is executing in. It supports authenticating both as a service principal or managed identity, and can be configured so that it will work both in a local development environment or when deployed to the cloud.

The DefaultAzureCredential will first attempt to authenticate using credentials provided in the environment. In a development environment you can authenticate as a service principal with the DefaultAzureCredential by providing configuration in environment variables as described in the next section.

If the environment configuration is not present or incomplete, the DefaultAzureCredential will then determine if a managed identity is available in the current environment. Authenticating as a managed identity requires no configuration, but does require platform support. See the managed identity documentation for more details on this.

Environment variables

DefaultAzureCredential and EnvironmentCredential are configured for service principal authentication with these environment variables:

variable name	value
AZURE_CLIENT_ID	service principal's app id
AZURE_TENANT_ID	id of the principal's Azure Active Directory tenant
AZURE_CLIENT_SECRET	one of the service principal's client secrets

Examples

Authenticating with DefaultAzureCredential

This example demonstrates authenticating the SecretClient from the Azure.Security.KeyVault.Secrets client library using the DefaultAzureCredential.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.azure.vaults.net/"), new DefaultAzureCredential());

When executing this in a development machine you need to first configure the environment setting the variables AZURE_CLIENT_ID, AZURE_TENANT_ID and AZURE_CLIENT_SECRET to the appropriate values for your service principal.

Chaining Credentials

The ChainedTokenCredential class provides the ability to link together multiple credential instances to be tried sequentially when authenticating. The following example demonstrates creating a credential which will attempt to authenticate using managed identity, and fall back to certificate authentication if a managed identity is unavailable in the current environment. This example authenticates an EventHubClient from the Azure.Messaging.EventHubs client library using the ChainedTokenCredential.

using Azure.Identity;
using Azure.Messaging.EventHubs;

var managedCredential = new ManagedIdentityCredential(clientId);

var certCredential = new CertificateCredential(tenantId, clientId, certificate);

// authenticate using managed identity if it is available otherwise use certificate auth
var credential = new ChainedTokenCredential(managedCredential, certCredential);

var eventHubClient = new EventHubClient("myeventhub.eventhubs.windows.net", "myhubpath", credential);

Authenticating a service principal with a client secret

This example demonstrates authenticating the BlobClient from the Azure.Storage.Blobs client library using the ClientSecretCredential.

using Azure.Identity;
using Azure.Storage.Blobs;

// authenticating a service principal with a client secret
var credential = new ClientSecretCredential(tenantId, clientId, clientSecret);

var blobClient = new BlobClient(new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"), credential);

Authenticating a service principal with a certificate

This example demonstrates authenticating the KeyClient from the Azure.Security.KeyVault.Keys client library using the CertificateCredential.

using Azure.Identity;
using Azure.Security.KeyVault.Keys;

// authenticating a service principal with a certificate
var certificate = new X509Certificate2("./app/certs/certificate.pfx");

var credential = new CertificateCredential(tenantId, clientId, certificate);

var keyClient = new KeyClient(new Uri("https://myvault.azure.vaults.net/"), credential);

Authenticating a user with the default browser

The InteractiveBrowserCredential allows an application to authenticate a user by launching the system's default browser. This example demonstrates authenticating the BlobClient from the Azure.Storage.Blobs client library using the InteractiveBrowserCredential.

using Azure.Identity;
using Azure.Storage.Blobs;

// authenticating a service principal with a client secret
var credential = new InteractiveBrowserCredential(clientId);

var blobClient = new BlobClient(new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"), credential);

Note: If a default browser is not available in the system, or the current application does not have permissions to create a process authentication with the DefaultBrowserCredential will fail with an AuthenticationFailedException.

Authenticating a user with the device code flow

The device code authentication flow allows an application to display a device code to a user, and then the user will authenticate using this code through a browser, typically on another client. This authentication flow is most often used on clients that have limited UI and no available browser, such as terminal clients and certain IoT devices.

This example demonstrates authenticating the SecretClient from the Azure.Security.KeyVault.Secrets client library using the DeviceCodeCredential. The sample constructs a DeviceCodeCredential with an application client id, and a callback which prints the device code.

using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using System.Threading.Tasks;

Func<DeviceCodeInfo, Task> PrintDeviceCode = code => 
{ 
    Console.WriteLine(code.Message);

    return Task.CompletedTask;
}

// Create a secret client using the DefaultAzureCredential
var client = new SecretClient(new Uri("https://myvault.azure.vaults.net/"), new DeviceCodeCredential(clientId, PrintDeviceCode));

Troubleshooting

Errors arising from authentication can be raised on any service client method which makes a request to the service. This is because the first time the token is requested from the credential is on the first call to the service, and any subsequent calls might need to refresh the token. In order to distinguish these failures from failures in the service client Azure Identity classes raise the AuthenticationFailedException with details to the source of the error in the exception message as well as possibly the error message.

For more details on dealing with errors arising from failed requests to Azure Active Directory, or managed identity endpoints please refer to the Azure Active Directory documentation on authorization error codes.

Next steps

Currently the following client libraries support authenticating with TokenCredential and the Azure Identity library. You can learn more about their use, and find additional documentation on use of these client libraries along samples with can be found in the links below.

• Azure.Messaging.EventHubs
• Azure.Security.KeyVault.Keys
• Azure.Security.KeyVault.Secrets
• Azure.Storage.Blobs
• Azure.Storage.Queues

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 https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

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.