azure-sdk-for-cpp/sdk/identity/azure-identity

Azure Identity client library for C++

The Azure Identity library provides Microsoft Entra ID (formerly 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 Microsoft Entra token authentication. This library follows the Azure SDK Design Guidelines for C++.

Source code | API reference documentation | Microsoft Entra ID documentation

Getting started

Include the package

The easiest way to acquire the C++ SDK is leveraging vcpkg package manager. See the corresponding Azure SDK for C++ readme section.

To install Azure Identity package via vcpkg:

> vcpkg install azure-identity-cpp

Then, use in your CMake file:

find_package(azure-identity-cpp CONFIG REQUIRED)
target_link_libraries(<your project name> PRIVATE Azure::azure-identity)

Prerequisites

• An [Azure subscription][azure_sub].
• The Azure CLI can also be useful for authenticating in a development environment, creating accounts, and managing account roles.

Authenticate the client

When debugging and executing code locally it is typical for a developer to use their own account for authenticating calls to Azure services. There are several developer tools which can be used to perform this authentication in your development environment.

Authenticate via the Azure CLI

Developers can use the Azure CLI to authenticate. Applications using the DefaultAzureCredential or the AzureCliCredential can then use this account to authenticate calls in their application when running locally.

To authenticate with the Azure CLI, users can run the command az login. For users running on a system with a default web browser, the Azure CLI will launch the browser to authenticate the user.

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 service clients use those credentials to authenticate requests to the service.

The Azure Identity library focuses on OAuth authentication with Microsoft Entra ID, and it offers a variety of credential classes capable of acquiring a Microsoft Entra token to authenticate service requests. All of the credential classes in this library are implementations of the TokenCredential abstract class in azure-core, and any of them can be used by to construct service clients capable of authenticating with a TokenCredential.

See Credential Classes for a complete listing of available credential types.

DefaultAzureCredential

DefaultAzureCredential combines credentials commonly used to authenticate when deployed, with credentials used to authenticate in a development environment.

Note: DefaultAzureCredential is intended to simplify getting started with the SDK by handling common scenarios with reasonable default behaviors. It is not recommended to use it in production. Developers who want more control or whose scenario isn't served by the default settings should use other credential types.

The DefaultAzureCredential attempts to authenticate via the following mechanisms, in this order, stopping when one succeeds:

1. Environment - The DefaultAzureCredential will read account information specified via environment variables and use it to authenticate.
2. Workload Identity Credential - If the developer authenticates using a Kubernetes service account token.
3. Azure CLI - If the developer has authenticated an account via the Azure CLI az login command, the DefaultAzureCredential will authenticate with that account.
4. Managed Identity - If the application is deployed to an Azure host with Managed Identity enabled, the DefaultAzureCredential will authenticate with that account.

Even though the credentials being used and their order is documented, it may change from release to release.

DefaultAzureCredential intends to provide a credential that "just works out of the box and without requiring any information", if only the environment is set up sufficiently for the credential to work. Therefore, it could be simple to use, but since it uses a chain of credentials, it could be a bit complicated to diagnose if the environment setup is not sufficient. To help with this, DefaultAzureCredential code paths are instrumented with log messages.

Examples

See the code samples.

Chained Token Credential

ChainedTokenCredential allows users to set up custom authentication flow consisting of multiple credentials.

An example below demonstrates using ChainedTokenCredential which will attempt to authenticate using EnvironmentCredential, and fall back to authenticate using ManagedIdentityCredential.

// A configuration demonstrated below would authenticate using EnvironmentCredential if it is
// available, and if it is not available, would fall back to use AzureCliCredential, and then to
// ManagedIdentityCredential.
auto chainedTokenCredential = std::make_shared<Azure::Identity::ChainedTokenCredential>(
    Azure::Identity::ChainedTokenCredential::Sources{
        std::make_shared<Azure::Identity::EnvironmentCredential>(),
        std::make_shared<Azure::Identity::AzureCliCredential>(),
        std::make_shared<Azure::Identity::ManagedIdentityCredential>()});

Azure::Service::Client azureServiceClient("serviceUrl", chainedTokenCredential);

Managed Identity Support

The Managed identity authentication is supported via the ManagedIdentityCredential for the following Azure Services:

• Azure App Service and Azure Functions
• Azure Cloud Shell
• Azure Arc
• Azure Virtual Machines

Specify a user-assigned managed identity with ManagedIdentityCredential

Many Azure hosts allow the assignment of a user-assigned managed identity. The following examples demonstrate configuring ManagedIdentityCredential to authenticate a user-assigned managed identity when deployed to an Azure host. The sample code uses the credential to authenticate a BlobClient from the Azure::Storage::Blobs client library. It also demonstrates how you can specify a user-assigned managed identity either by a client ID, resource ID, or an object ID.

Client ID

To use a client ID, create a ManagedIdentityId with ManagedIdentityIdKind::ClientId, set that as the IdentityId in the ManagedIdentityCredentialOptions, and pass that to the ManagedIdentityCredential constructor. For example:

// When deployed to an Azure host, ManagedIdentityCredential will authenticate the specified
// user-assigned managed identity.

std::string userAssignedClientId = "<your managed identity client ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::ClientId, userAssignedClientId);

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

Resource ID

Similarly, to use a resource ID, create a ManagedIdentityId with ManagedIdentityIdKind::ResourceId, set that as the IdentityId in the ManagedIdentityCredentialOptions, and pass that to the ManagedIdentityCredential constructor. The resource ID takes the form /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{identityName}. Because resource IDs can be built by convention, they can be more convenient when there are a large number of user-assigned managed identities in your environment. For example:

std::string userAssignedResourceId = "<your managed identity resource ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId
    = ManagedIdentityId(ManagedIdentityIdKind::ResourceId, userAssignedResourceId);

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

Object ID

Similarly, to use an object ID, create a ManagedIdentityId with ManagedIdentityIdKind::ObjectId, set that as the IdentityId in the ManagedIdentityCredentialOptions, and pass that to the ManagedIdentityCredential constructor. For example:

std::string userAssignedObjectId = "<your managed identity object ID>";
ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::ObjectId, userAssignedObjectId);

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

Specify a system-assigned managed identity with ManagedIdentityCredential

You can express your intent to use a system-assigned managed identity, explicitly, by creating a ManagedIdentityId with ManagedIdentityIdKind::SystemAssigned and an empty ID value, set that as the IdentityId in the ManagedIdentityCredentialOptions, and pass that to the ManagedIdentityCredential constructor. For example:

ManagedIdentityCredentialOptions options;
options.IdentityId = ManagedIdentityId(ManagedIdentityIdKind::SystemAssigned, {});

auto credential = std::make_shared<ManagedIdentityCredential>(options);
auto blobClient = BlobClient(blobUrl, credential);

An alternative way to specify a system-assigned managed identity, implicitly, is by calling the default ManagedIdentityCredential constructor. For example:

auto credential = std::make_shared<ManagedIdentityCredential>();
auto blobClient = BlobClient(blobUrl, credential);

Environment Variables

DefaultAzureCredential and EnvironmentCredential can be configured with environment variables. Each type of authentication requires values for specific variables:

Service principal with secret

Variable name	Value
AZURE_TENANT_ID	ID of the application's Microsoft Entra tenant
AZURE_CLIENT_ID	ID of a Microsoft Entra application
AZURE_CLIENT_SECRET	one of the application's client secrets
AZURE_AUTHORITY_HOST	(optional) authentication authority URL

Service principal with certificate

variable name	Value
AZURE_CLIENT_ID	ID of a Microsoft Entra application
AZURE_TENANT_ID	ID of the application's Microsoft Entra tenant
AZURE_CLIENT_CERTIFICATE_PATH	path to a PFX or PEM-encoded certificate file including private key
AZURE_AUTHORITY_HOST	(optional) authentication authority URL

Configuration is attempted in the above order. For example, if values for a client secret and certificate are both present, the client secret will be used.

Credential classes

Credential chains

Credential	Usage
DefaultAzureCredential	Provides a simplified authentication experience to quickly start developing applications run in Azure.
ChainedTokenCredential	Allows users to define custom authentication flows composing multiple credentials.

Authenticate Azure-hosted applications

Credential	Usage
ManagedIdentityCredential	Authenticates the managed identity of an Azure resource.
EnvironmentCredential	Authenticates a service principal or user via credential information specified in environment variables.
WorkloadIdentityCredential	Authenticate a workload identity on Kubernetes.

Authenticate service principals

Credential	Usage
AzurePipelinesCredential	Supports Microsoft Entra Workload ID on Azure Pipelines.
ClientAssertionCredential	Authenticates a service principal using a signed client assertion.
ClientSecretCredential	Authenticates a service principal using a secret.
ClientCertificateCredential	Authenticates a service principal using a certificate.

Authenticate via development tools

Credential	Usage
AzureCliCredential	Authenticates in a development environment with the Azure CLI.

Troubleshooting

1. Azure Identity SDK log messages contain disgnostic information, and start with "Identity: ".
2. Credentials raise exceptions either when they fail to authenticate or cannot execute authentication. When a credential fails to authenticate, an AuthenticationException is thrown. The exception has the what() function that provides more information about the failure.

Contributing

For details on contributing to this repository, see the contributing guide.

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 the Contributor License Agreement.

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.

Additional Helpful Links for Contributors

Many people all over the world have helped make this project better. You'll want to check out:

• What are some good first issues for new contributors to the repo?
• How to build and test your change
• How you can make a change happen!
• Frequently Asked Questions (FAQ) and Conceptual Topics in the detailed Azure SDK for C++ wiki.

Reporting security issues and security bugs

Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) secure@microsoft.com. You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Further information, including the MSRC PGP key, can be found in the Security TechCenter.

License

Azure SDK for C++ is licensed under the MIT license.