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 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.
| Credential class | Usage |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <xref uid="com.azure.identity.AzurePowerShellCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.AzurePowerShellCredential"></xref> | 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 <xref uid="com.azure.identity.AzurePowerShellCredential" data-throw-if-not-resolved="false" data-raw-source="AzurePowerShellCredential JavaDocs"></xref> for more information about the credential usage. |
| <xref uid="com.azure.identity.IntelliJCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.IntelliJCredential"></xref> | 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 <xref uid="com.azure.identity.IntelliJCredential" data-throw-if-not-resolved="false" data-raw-source="IntelliJCredential JavaDocs"></xref> 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.
| Credential class | Usage |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <xref uid="com.azure.identity.EnvironmentCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.EnvironmentCredential"></xref> | 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 <xref uid="com.azure.identity.EnvironmentCredential" data-throw-if-not-resolved="false" data-raw-source="EnvironmentCredential JavaDocs"></xref> for more information about the credential usage. |
| <xref uid="com.azure.identity.ChainedTokenCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.ChainedTokenCredential"></xref> | This credential allows users to define custom authentication flows by chaining multiple credentials together. For example, the <xref uid="com.azure.identity.ManagedIdentityCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.ManagedIdentityCredential"></xref> and <xref uid="com.azure.identity.EnvironmentCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.EnvironmentCredential"></xref> 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 <xref uid="com.azure.identity.ChainedTokenCredential" data-throw-if-not-resolved="false" data-raw-source="ChainedTokenCredential JavaDocs"></xref> 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.
| Credential class | Usage |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <xref uid="com.azure.identity.ClientAssertionCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.ClientAssertionCredential"></xref> | 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 <xref uid="com.azure.identity.ClientAssertionCredential" data-throw-if-not-resolved="false" data-raw-source="ClientAssertionCredential JavaDocs"></xref> for more information about the credential usage. |
| <xref uid="com.azure.identity.ClientCertificateCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.ClientCertificateCredential"></xref> | 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 <xref uid="com.azure.identity.ClientCertificateCredential" data-throw-if-not-resolved="false" data-raw-source="ClientCertificateCredential JavaDocs"></xref> 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.
| Credential class | Usage |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <xref uid="com.azure.identity.DeviceCodeCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.DeviceCodeCredential"></xref> | 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 <xref uid="com.azure.identity.DeviceCodeCredential" data-throw-if-not-resolved="false" data-raw-source="DeviceCodeCredential JavaDocs"></xref> for more information about the credential usage. |
| <xref uid="com.azure.identity.AuthorizationCodeCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.AuthorizationCodeCredential"></xref> | 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 <xref uid="com.azure.identity.AuthorizationCodeCredential" data-throw-if-not-resolved="false" data-raw-source="AuthorizationCodeCredential JavaDocs"></xref> for more information about the credential usage. |
| <xref uid="com.azure.identity.UsernamePasswordCredential" data-throw-if-not-resolved="false" data-raw-source="com.azure.identity.UsernamePasswordCredential"></xref> | 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 <xref uid="com.azure.identity.UsernamePasswordCredential" data-throw-if-not-resolved="false" data-raw-source="UsernamePasswordCredential JavaDocs"></xref> 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. |
| AuthenticationUtil |
Utility methods for working with authentication. |
| 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. |
| AzurePipelinesCredential |
The AzurePipelinesCredential acquires a token using the Azure Pipelines service connection. |
| AzurePipelinesCredentialBuilder |
The AzurePipelinesCredentialBuilder provides a fluent builder for AzurePipelinesCredential. |
| 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 |
ChainedTokenCredential allows you to chain together a set of TokenCredential instances. |
| ChainedTokenCredentialBuilder |
Fluent credential builder for instantiating 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 |
DefaultAzureCredential simplifies authentication while developing apps that deploy to Azure by combining credentials used in Azure hosting environments with credentials used in local development. |
| DefaultAzureCredentialBuilder |
Fluent credential builder for instantiating 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. |
Azure SDK for Java