Package com.azure.identity

package com.azure.identity

The Azure Identity library provides Microsoft Entra ID token authentication support across the Azure SDK. The library focuses on OAuth authentication with Microsoft Entra ID, and it offers various credential classes capable of acquiring a Microsoft Entra token to authenticate service requests. All the credential classes in this package are implementations of the `TokenCredential` interface offered by azure-core, and any of them can be used to construct service clients capable of authenticating with a `TokenCredential`.

Getting Started

The DefaultAzureCredential is appropriate for most scenarios where the application is intended to ultimately be run in Azure. This is because the DefaultAzureCredential combines credentials commonly used to authenticate when deployed, with credentials used to authenticate in a development environment.

Note: This credential is intended to simplify getting started with the SDK by handling common scenarios with reasonable default behaviors. Developers who want more control or whose scenario isn't served by the default settings should use other credential types (detailed below). For more information refer to the default azure credential conceptual documentation.

Sample: Construct a simple DefaultAzureCredential

The following code sample demonstrates the creation of a DefaultAzureCredential, using the DefaultAzureCredentialBuilder to configure it. Once this credential is created, it may be passed into the builder of many of the Azure SDK for Java client builders as the 'credential' parameter.

 TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder()
     .build();

Further, it is recommended to read DefaultAzureCredential JavaDocs for more detailed information about the credential usage and the chain of credentials it runs underneath.

The DefaultAzureCredential works well in most of the scenarios as it executes a chain of credentials underneath which covers well known authentication scenarios for both Azure hosted platforms and development environment. But, in some scenarios where only a specific authentication mechanism will work, it is recommended to use that specific credential to authenticate. Let's take a look at the individual authentication scenarios and their respective credential use below.

Authenticate in Developer Environment

Azure supports developer environment authentication via Azure CLI, Azure Powershell and Azure Tools for IntelliJ plugin in IntelliJ IDE. It involves interactively authenticating using user credentials locally on the developer machine. Once authenticated, the login information is persisted.

The Azure Identity library supports authenticating in developer environment via AzureCliCredential, AzurePowerShellCredential and IntelliJCredential. These credentials offer a seamless authentication experience by utilizing the cached Azure Plugin login information from their respective IDE tool. For more information refer to the developer environment authentication documentation.

Sample: Construct AzureCliCredential

The following code sample demonstrates the creation of a AzureCliCredential, using the AzureCliCredentialBuilder to configure it .Once this credential is created, it may be passed into the builder of many of the Azure SDK for Java client builders as the 'credential' parameter.

 TokenCredential azureCliCredential = new AzureCliCredentialBuilder()
     .build();

Further, it is recommended to read AzureCliCredential JavaDocs for more detailed information about the credential usage.

For other credentials that are compatible with developer tools authentication, refer to the table below.


Authenticate via development tools
Credential class Usage
AzurePowerShellCredential This credential authenticates in a development environment with the logged in user or service principal in Azure PowerShell. It utilizes the account of the already logged in user on Azure Powershell to get an access token. If there's no user logged in locally on Azure Powershell, then it will not work. Further, it is recommended to read AzurePowerShellCredential JavaDocs for more information about the credential usage.
IntelliJCredential This credential authenticates in a development environment with the logged in user or service principal in Azure Toolkit for IntelliJ plugin on IntelliJ IDE. It utilizes the cached login information of the Azure Toolkit for IntelliJ plugin to seamlessly authenticate the application. If there's no user logged in locally on Azure Toolkit for IntelliJ in IntelliJ IDE, then it will not work. Further, it is recommended to read IntelliJCredential JavaDocs for more information about the credential usage.

Authenticating on Azure Hosted Platforms via Managed Identity

Azure Managed Identity is a feature in Microsoft Entra ID that provides a way for applications running on Azure to authenticate themselves with Azure resources without needing to manage or store any secrets like passwords or keys.

The ManagedIdentityCredential authenticates the configured managed identity (system or user assigned) of an Azure resource. So, if the application is running inside an Azure resource that supports Managed Identity through IDENTITY/MSI, IMDS endpoints, or both, then the ManagedIdentityCredential will get your application authenticated, and offers a great secretless authentication experience. For more information refer to the managed identity authentication documentation.

Sample: Construct a Managed Identity Credential

The following code sample demonstrates the creation of a ManagedIdentityCredential, using the ManagedIdentityCredentialBuilder to configure it. Once this credential is created, it may be passed into the builder of many of the Azure SDK for Java client builders as the 'credential' parameter.

 TokenCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
     .build();

Further, it is recommended to read ManagedIdentityCredential JavaDocs for more detailed information about the credential usage and the Azure platforms it supports.

For other credentials that work well in Azure Hosted platforms, refer to the table below.


Authenticate Azure-hosted applications
Credential class Usage
EnvironmentCredential This credential authenticates a service principal or user via credential information specified in environment variables. The service principal authentication works well in Azure hosted platforms when Managed Identity is not available. Further, it is recommended to read EnvironmentCredential JavaDocs for more information about the credential usage.
ChainedTokenCredential This credential allows users to define custom authentication flows by chaining multiple credentials together. For example, the ManagedIdentityCredential and EnvironmentCredential can be chained together to sequentially execute on Azure hosted platforms. The credential that first returns the token is used for authentication. Further, it is recommended to read ChainedTokenCredential JavaDocs for more information about the credential usage.

Authenticate with Service Principals

Service Principal authentication is a type of authentication in Azure that enables a non-interactive login to Microsoft Entra ID, allowing an application or service to authenticate itself with Azure resources. A Service Principal is essentially an identity created for an application in Microsoft Entra ID that can be used to authenticate with Azure resources. It's like a "user identity" for the application or service, and it provides a way for the application to authenticate itself with Azure resources without needing to use a user's credentials. Microsoft Entra ID allows users to register service principals which can be used as an identity for authentication. A client secret and/or a client certificate associated with the registered service principal is used as the password when authenticating the service principal.

The Azure Identity library supports both client secret and client certificate based service principal authentication via ClientSecretCredential and ClientCertificateCredential respectively. For more information refer to the service principal authentication documentation.

Sample: Construct a ClientSecretCredential

The following code sample demonstrates the creation of a ClientSecretCredential, using the ClientSecretCredentialBuilder to configure it. The tenantId, clientId and clientSecret parameters are required to create ClientSecretCredential .Once this credential is created, it may be passed into the builder of many of the Azure SDK for Java client builders as the 'credential' parameter.

 TokenCredential clientSecretCredential = new ClientSecretCredentialBuilder()
     .tenantId(tenantId)
     .clientId(clientId)
     .clientSecret(clientSecret)
     .build();

Further, it is recommended to read ClientSecretCredential JavaDocs for more detailed information about the credential usage.

For other credentials that are compatible with service principal authentication, refer to the table below.


Authenticate service principals
Credential class Usage
ClientAssertionCredential This credential authenticates a service principal using a signed client assertion. It allows clients to prove their identity to Microsoft Entra ID without requiring them to disclose their credentials (such as a username and password). Further, it is recommended to read ClientAssertionCredential JavaDocs for more information about the credential usage.
ClientCertificateCredential This credential authenticates a service principal using a certificate. It doesn't require transmission of a client secret and mitigates the security related password storage and network transmission issues. Further, it is recommended to read ClientCertificateCredential JavaDocs for more information about the credential usage.

Authenticate with User Credentials

User credential authentication is a type of authentication in Azure that involves a user providing their username and password to authenticate with Azure resources. In Azure, user credential authentication can be used to authenticate with Microsoft Entra ID.

The Azure Identity library supports user credentials based authentication via InteractiveBrowserCredential, DeviceCodeCredential and UsernamePasswordCredential. For more information refer to the user credential authentication documentation.

Sample: Construct InteractiveBrowserCredential

The following code sample demonstrates the creation of a InteractiveBrowserCredential, using the InteractiveBrowserCredentialBuilder to configure it .Once this credential is created, it may be passed into the builder of many of the Azure SDK for Java client builders as the 'credential' parameter.

 TokenCredential interactiveBrowserCredential = new InteractiveBrowserCredentialBuilder()
     .redirectUrl("http://localhost:8765")
     .build();

Further, it is recommended to read InteractiveBrowserCredential JavaDocs for more information about the credential usage.

For other credentials that are compatible with user credentials based authentication, refer to the table below.


Authenticate users
Credential class Usage
DeviceCodeCredential This credential interactively authenticates a user on devices with limited UI. It prompts users to open an authentication URL with a device code on a UI enabled device and requires them to interactively authenticate there. Once authenticated, the original device requesting authentication gets authenticated and receives the access token. Further, it is recommended to read DeviceCodeCredential JavaDocs for more information about the credential usage.
AuthorizationCodeCredential This credential authenticates a user with a previously obtained authorization code as part of an Oauth 2 flow. This is applicable for applications which control the logic of interactive user authentication to fetch an authorization code first. Once the application has received the authorization code, it can then configure it on this credential and use it to get an access token. Further, it is recommended to read AuthorizationCodeCredential JavaDocs for more information about the credential usage.
UsernamePasswordCredential This credential authenticates a user with a username and password without multi-factored auth. This credential can be used on developer environment for user principals which do not require 2FA/MFA (multi-facotred) authentication. Further, it is recommended to read UsernamePasswordCredential JavaDocs for more information about the credential usage.

See Also: