|
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
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:
Then, use in your CMake file:
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.
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.
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
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:
DefaultAzureCredential
will read account information specified via environment variables and use it to authenticate.az login
command, the DefaultAzureCredential
will authenticate with that account.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.
See the code samples.
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
.
The Managed identity authentication is supported via the ManagedIdentityCredential
for the following Azure Services:
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.
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:
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:
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:
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:
An alternative way to specify a system-assigned managed identity, implicitly, is by calling the default ManagedIdentityCredential
constructor. For example:
DefaultAzureCredential
and EnvironmentCredential
can be configured with environment variables. Each type of authentication requires values for specific variables:
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 |
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 | 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. |
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. |
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. |
Credential | Usage |
---|---|
AzureCliCredential | Authenticates in a development environment with the Azure CLI. |
AuthenticationException
is thrown. The exception has the what()
function that provides more information about the failure.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.
Many people all over the world have helped make this project better. You'll want to check out:
Security issues and bugs should be reported privately, via email, to the Microsoft Security Response Center (MSRC) secur.nosp@m.e@mi.nosp@m.croso.nosp@m.ft.c.nosp@m.om. 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.
Azure SDK for C++ is licensed under the MIT license.