Azure Identity client library for Java
The Azure Identity library provides 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 AAD token authentication.
This library currently supports: - Service principal authentication - Managed identity authentication - Device code authentication - Interactive browser authentication, based on OAuth2 authentication code - Username + password authentication - Shared Token Cache credential, which shares login information with Visual Studio, Azure CLI, and more
Source code | API reference documentation | Azure Active Directory documentation
Table of contents
- Getting started
- Adding the package to your project
- Prerequisites
- Creating a Service Principal with the Azure CLI
- Enable applications for device code flow
- Enable applications for interactive browser oauth 2 flow
- Enable applications for oauth 2 auth code flow
- Enable applications for shared token cache credential
- Key concepts
- Credentials
- DefaultAzureCredential
- Environment variables
- Examples
- Troubleshooting
- Next steps
- Contributing
Getting started
Adding the package to your project
Maven dependency for Azure Secret Client library. Add it to your project's pom file.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.0.0</version>
</dependency>
Prerequisites
- An Azure subscription.
- An existing Azure Active Directory service principal. If you need to create a service principal, you can use the Azure Portal or Azure CLI.
Creating a Service Principal with the Azure CLI
Use the Azure CLI snippet below to create/get client secret credentials.
Create a service principal and configure its access to Azure resources:
az ad sp create-for-rbac -n <your-application-name> --skip-assignmentOutput:
{ "appId": "generated-app-ID", "displayName": "dummy-app-name", "name": "http://dummy-app-name", "password": "random-password", "tenant": "tenant-ID" }- Use the returned credentials above to set AZURECLIENTID(appId), AZURECLIENTSECRET(password) and AZURETENANTID(tenant) environment variables.
Enable applications for device code flow
In order to authenticate a user through device code flow, you need to go to Azure Active Directory on Azure Portal and find you app registration and enable the following 2 configurations:
This will let the application authenticate, but the application still doesn't have permission to log you into Active Directory, or access resources on your behalf. Open API Permissions, and enable Microsoft Graph, and the resources you want to access, e.g., Azure Service Management, Key Vault, etc:
Note that you also need to be the admin of your tenant to grant consent to your application when you login for the first time. Also note after 2018 your Active Directory may require your application to be multi-tenant. Select "Accounts in any organizational directory" under Authentication panel (where you enabled Device Code) to make your application a multi-tenant app.
Enable applications for interactive browser oauth 2 flow
You need to register an application in Azure Active Directory with permissions to login on behalf of a user to use InteractiveBrowserCredential. Follow all the steps above for device code flow to register your application to support logging you into Active Directory and access certain resources. Note the same limitations apply that an admin of your tenant must grant consent to your application before any user account can login.
You may notice in InteractiveBrowserCredentialBuilder, a port number is required, and you need to add the redirect URL on this page too:
In this case, the port number is 8765.
Enable applications for oauth 2 auth code flow
You need the same application registered as in Enable applications for interactive browser oauth 2 flow, except that the redirect URL must be an API endpoint on your web application where the auth code must be handled as a query parameter.
Enable applications for shared token cache credential
You will need to have Visual Studio 2019 installed. Login to Visual Studio with your org ID or live ID and you are ready to use shared token cache credential.
If you see an error "MSAL V3 Deserialization failed", try clearing the cache in C:\Users\{username}\AppData\.IdentityService.
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 use those credentials to authenticate requests to the service.Azure Identity offers a variety of credential classes in the azure-identity package capable of acquiring an AAD token. All of these credential classes are implementations of the TokenCredential abstract class in Azure Core, and can be used by any service client which can be constructed with a TokenCredential.
The credential types in Azure Identity differ in the types of AAD identities they can authenticate and how they are configured:
|credential class|identity|configuration
|-|-|-
|DefaultAzureCredential|service principal or managed identity|none for managed identity; environment variables for service principal
|ManagedIdentityCredential|managed identity|ManagedIdentityCredentialBuilder
|EnvironmentCredential|service principal|environment variables
|ClientSecretCredential|service principal|ClientSecretCredentialBuilder
|ClientCertificateCredential|service principal|ClientCertificateCredentialBuilder
|DeviceCodeCredential|user account|DeviceCodeCredentialBuilder
|InteractiveBrowserCredential|user account|InteractiveBrowserCredentialBuilder
|UsernamePasswordCredential|user account|UsernamePasswordCredentialBuilder
Credentials can be chained together to be tried in turn until one succeeds using the ChainedTokenCredential; see chaining credentials for details.
DefaultAzureCredential
DefaultAzureCredential is appropriate for most scenarios where the application is intended to run in the Azure Cloud. This is because the DefaultAzureCredential determines the appropriate credential type based of the environment it is executing in. It supports authenticating both as a service principal or managed identity, and can be configured so that it will work both in a local development environment or when deployed to the cloud.
The DefaultAzureCredential will first attempt to authenticate using credentials provided in the environment. In a development environment you can authenticate as a service principal with the DefaultAzureCredential by providing configuration in environment variables as described in the next section.
If the environment configuration is not present or incomplete, the DefaultAzureCredential will then determine if a managed identity is available in the current environment. Authenticating as a managed identity requires no configuration, but does
require platform support. See the
managed identity documentation for more details on this.
Environment variables
DefaultAzureCredential and EnvironmentCredential are configured for service
principal authentication with these environment variables:
|variable name|value
|-|-
|AZURE_CLIENT_ID|service principal's app id
|AZURE_TENANT_ID|id of the principal's Azure Active Directory tenant
|AZURE_CLIENT_SECRET|one of the service principal's client secrets
Examples
Authenticating with DefaultAzureCredential
This example demonstrates authenticating the SecretClient from the azure-security-keyvault-secrets client library using the DefaultAzureCredential. There's also a compilable sample to create a Key Vault secret client you can copy-paste.
// The default credential first checks environment variables for configuration as described above.
// If environment configuration is incomplete, it will try managed identity.
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
// Azure SDK client builders accept the credential as a parameter
SecretClient client = new SecretClientBuilder()
.vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
.credential(credential)
.buildClient();
When executing this in a development machine you need to first configure the environment setting the variables AZURE_CLIENT_ID, AZURE_TENANT_ID and AZURE_CLIENT_SECRET to the appropriate values for your service principal.
Authenticating a service principal with a client secret
This example demonstrates authenticating the KeyClient from the azure-security-keyvault-keys client library using the ClientSecretCredential. There's also a compilable sample to create a Key Vault secret client you can copy-paste.
import com.azure.identity.ClientSecretCredential;
import com.azure.identity.ClientSecretCredentialBuilder;
import com.azure.security.keyvault.keys.KeyClient;
// authenticate with client secret,
ClientSecretCredential clientSecretCredential = new ClientSecretCredentialBuilder()
.clientId("<YOUR_CLIENT_ID>")
.clientSecret("<YOUR_CLIENT_SECRET>")
.tenantId("<YOUR_TENANT_ID>")
.build();
KeyClient client = new KeyClientBuilder()
.vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
.credential(clientSecretCredential)
.buildClient();
Authenticating a user account with device code flow
This example demonstrates authenticating the KeyClient from the azure-security-keyvault-keys client library using the DeviceCodeCredential on an IoT device. There's also a compilable sample to create a Key Vault secret client you can copy-paste.
import com.azure.identity.DeviceCodeCredential;
import com.azure.identity.DeviceCodeCredentialBuilder;
import com.azure.security.keyvault.keys.KeyClient;
// authenticate with client secret,
DeviceCodeCredential deviceCodeCredential = new DeviceCodeCredentialBuilder()
.challengeConsumer(challenge -> {
// lets user know of the challenge, e.g., display the message on an IoT device
displayMessage(challenge.message());
})
.build();
KeyClient client = new KeyClientBuilder()
.vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
.credential(deviceCodeCredential)
.buildClient();
Authenticating a user account with username and password
This example demonstrates authenticating the KeyClient from the azure-security-keyvault-keys client library using the UsernamePasswordCredential. The user must not have Multi-factor auth turned on. There's also a compilable sample to create a Key Vault secret client you can copy-paste.
import com.azure.identity.UsernamePasswordCredential;
import com.azure.identity.UsernamePasswordCredentialBuilder;
import com.azure.security.keyvault.keys.KeyClient;
// authenticate with client secret,
UsernamePasswordCredential usernamePasswordCredential = new UsernamePasswordCredentialBuilder()
.clientId("<YOUR_CLIENT_ID>")
.username("<YOUR_USERNAME>")
.password("<YOUR_PASSWORD>")
.build();
KeyClient client = new KeyClientBuilder()
.vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
.credential(usernamePasswordCredential)
.buildClient();
Authenticating a user account with auth code flow
This example demonstrates authenticating the KeyClient from the azure-security-keyvault-keys client library using the AuthorizationCodeCredential on a web application.
First, prompt the user to login at the URL documented at Microsoft identity platform and OAuth 2.0 authorization code flow. You will need the client id, tenant id, redirect URL, and the scopes your application plans to access.
Then create an API at the redirect URL with the following code to access the Key Vault service.
import com.azure.identity.AuthorizationCodeCredential;
import com.azure.identity.AuthorizationCodeCredentialBuilder;
import com.azure.security.keyvault.keys.KeyClient;
AuthorizationCodeCredential authCodeCredential = new AuthorizationCodeCredentialBuilder()
.clientId("<YOUR CLIENT ID>")
.authorizationCode("<AUTH CODE FROM QUERY PARAMETERS")
.redirectUrl("<THE REDIRECT URL>")
.build();
KeyClient client = new KeyClientBuilder()
.vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
.credential(authCodeCredential)
.buildClient();
Chaining credentials
The ChainedTokenCredential class provides the ability to link together multiple credential instances to be tried sequentially when authenticating. The following example demonstrates creating a credential which will attempt to authenticate using managed identity, and fall back to certificate authentication if a managed identity is unavailable in the current environment. This example authenticates an EventHubClient from the azure-eventhubs client library using the ChainedTokenCredential. There's also a compilable sample to create a Key Vault secret client you can copy-paste.
ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
.clientId("<YOUR_CLIENT_ID>")
.build();
ClientSecretCredential secondServicePrincipal = new ClientSecretCredentialBuilder()
.clientId("<YOUR_CLIENT_ID>")
.clientSecret("<YOUR_CLIENT_SECRET>")
.tenantId("<YOUR_TENANT_ID>")
.build();
// when an access token is requested, the chain will try each
// credential in order, stopping when one provides a token
ChainedTokenCredential credentialChain = new ChainedTokenCredentialBuilder()
.addLast(managedIdentityCredential)
.addLast(secondServicePrincipal)
.build();
// the chain can be used anywhere a credential is required
// The fully qualified name for the Event Hubs namespace. This is likely to be similar to:
// {your-namespace}.servicebus.windows.net
String fullyQualifiedNamespace = "<< EVENT HUBS FULLY QUALIFIED NAMESPACE >>";
String eventHubName = "<< NAME OF THE EVENT HUB >>";
EventHubAsyncClient client = new EventHubClientBuilder()
.credential(fullyQualifiedNamespace, eventHubName, credentialChain)
.buildAsyncClient();
Troubleshooting
Credentials raise exceptions when they fail to authenticate. ClientAuthenticationException has a message attribute which
describes why authentication failed. When raised by ChainedTokenCredential, the message collects error messages from each credential in the chain.
Next steps
Currently the following client libraries support authenticating with TokenCredential and the Azure Identity library. You can learn more about their use, and find additional documentation on use of these client libraries along samples with can be found in the links below.
Contributing
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 https://cla.microsoft.com.
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.
