com.azure.identity

Reference

Package:: com.azure.identity

Maven Artifact:: com.azure:azure-identity:1.12.0

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 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 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 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 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 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 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 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 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 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 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 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 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 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 for more information about the credential usage.

Classes

AadCredentialBuilderBase<T>	The base class for credential builders that allow specifying a client ID, tenant ID, authority host, and additionally allowed tenants for Microsoft Entra ID.
AuthenticationRecord	Authentication Record represents the account information of the authenticated account.
AuthenticationRequiredException	The Authentication Required Exception is thrown by InteractiveBrowserCredential and DeviceCodeCredential to indicate to the user that automatic authentication is disabled and authentication needs to be initiated via authenticate() or authenticate() APIs respectively before fetching an access token.
AuthorizationCodeCredential	Authorization Code authentication in Azure is a type of authentication mechanism that allows users to authenticate with Microsoft Entra ID and obtain an authorization code that can be used to request an access token to access Azure resources.
AuthorizationCodeCredentialBuilder	Fluent credential builder for instantiating a AuthorizationCodeCredential.
AzureAuthorityHosts	Defines fields exposing the well known authority hosts for the Azure Public Cloud and sovereign clouds.
AzureCliCredential	The Azure CLI is a command-line tool that allows users to manage Azure resources from their local machine or terminal.
AzureCliCredentialBuilder	Fluent credential builder for instantiating a AzureCliCredential.
AzureDeveloperCliCredential	Azure Developer CLI is a command-line interface tool that allows developers to create, manage, and deploy resources in Azure.
AzureDeveloperCliCredentialBuilder	Fluent credential builder for instantiating a AzureDeveloperCliCredential.
AzurePowerShellCredential	The Azure Powershell is a command-line tool that allows users to manage Azure resources from their local machine or terminal.
AzurePowerShellCredentialBuilder	Fluent credential builder for instantiating a AzurePowerShellCredential.
BrowserCustomizationOptions	Represent Options to customize browser view.
ChainedTokenCredential	The ChainedTokenCredential is a convenience credential that allows users to chain together a set of TokenCredential together.
ChainedTokenCredentialBuilder	Fluent credential builder for instantiating a ChainedTokenCredential.
ClientAssertionCredential	The ClientAssertionCredential acquires a token via client assertion and service principal authentication.
ClientAssertionCredentialBuilder	Fluent credential builder for instantiating a ClientAssertionCredential.
ClientCertificateCredential	The ClientCertificateCredential acquires a token via service principal authentication.
ClientCertificateCredentialBuilder	Fluent credential builder for instantiating a ClientCertificateCredential.
ClientSecretCredential	The ClientSecretCredential acquires a token via service principal authentication.
ClientSecretCredentialBuilder	Fluent credential builder for instantiating a ClientSecretCredential.
CredentialBuilderBase<T>	The base class for all the credential builders.
CredentialUnavailableException	The exception thrown when a TokenCredential did not attempt to authenticate and retrieve AccessToken, as its prerequisite information or state was not available.
DefaultAzureCredential	The DefaultAzureCredential is appropriate for most scenarios where the application is intended to ultimately be run in Azure.
DefaultAzureCredentialBuilder	Fluent credential builder for instantiating a DefaultAzureCredential.
DeviceCodeCredential	Device code authentication is a type of authentication flow offered by Microsoft Entra ID that allows users to sign in to applications on devices that don't have a web browser or a keyboard.
DeviceCodeCredentialBuilder	Fluent credential builder for instantiating a DeviceCodeCredential.
DeviceCodeInfo	Device Code Info represents the response returned from the device code endpoint containing information necessary for device code flow.
EnvironmentCredential	The EnvironmentCredential is appropriate for scenarios where the application is looking to read credential information from environment variables.
EnvironmentCredentialBuilder	Fluent credential builder for instantiating a EnvironmentCredential.
IntelliJCredential	IntelliJ IDEA is an integrated development environment (IDE) developed by JetBrains, which provides a variety of features to support software development, such as code completion, debugging, and testing.
IntelliJCredentialBuilder	Fluent credential builder for instantiating a IntelliJCredential.
InteractiveBrowserCredential	Interactive browser authentication is a type of authentication flow offered by Microsoft Entra ID that enables users to sign in to applications and services using a web browser.
InteractiveBrowserCredentialBuilder	Fluent credential builder for instantiating a InteractiveBrowserCredential.
ManagedIdentityCredential	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.
ManagedIdentityCredentialBuilder	Fluent credential builder for instantiating a ManagedIdentityCredential.
OnBehalfOfCredential	On Behalf of authentication in Azure is a way for a user or application to authenticate to a service or resource using credentials from another identity provider.
OnBehalfOfCredentialBuilder	Fluent credential builder for instantiating a OnBehalfOfCredential.
SharedTokenCacheCredential	A credential provider that provides token credentials from the MSAL shared token cache.
SharedTokenCacheCredentialBuilder	Fluent credential builder for instantiating a SharedTokenCacheCredential.
TokenCachePersistenceOptions	Represents the Persistence Token Cache options used to setup the persistent access token cache.
UsernamePasswordCredential	Username password authentication is a common type of authentication flow used by many applications and services, including Microsoft Entra ID.
UsernamePasswordCredentialBuilder	Fluent credential builder for instantiating a UsernamePasswordCredential.
VisualStudioCodeCredential	Enables authentication to Microsoft Entra ID as the user signed in to Visual Studio Code via the 'Azure Account' extension.
VisualStudioCodeCredentialBuilder	Fluent credential builder for instantiating a VisualStudioCodeCredential.
WorkloadIdentityCredential	Workload Identity authentication is a feature in Azure that allows applications running on virtual machines (VMs) to access other Azure resources without the need for a service principal or managed identity.
WorkloadIdentityCredentialBuilder	Fluent credential builder for instantiating a WorkloadIdentityCredential.