Skip navigation links

Azure SDK for Java Reference Documentation

Current version is 1.1.0-beta.1, click here for the index

See: Description

Azure Identity 
Package Description
com.azure.identity
Package containing various types of credentials and classes for retrieving access tokens from various configurations.
Current version is 1.1.0-beta.1, click here for the index

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

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.1.0-beta.1</version>
</dependency>

Prerequisites

Creating a Service Principal with the Azure CLI

Use the Azure CLI snippet below to create/get client secret credentials.

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:

device code enable

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:

device code permissions

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:

interactive redirect uri

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.

Open your Visual Studio account settings and you can see the list of accounts with cached tokens in the red rectangle below. Note the Personalization Account is not related to this token cache. You can delete all info and tokens of this account in the token cache by removing the account here and closing the Visual Studio window.

vs2019 account settings

If you have multiple accounts listed here, you must specify the AZURE_USERNAME environment variable to the email of the account you'd like to use for all the authentications.

If you see an error "MSAL V3 Deserialization failed", try clearing the cache in C:\Users\{username}\AppData\Local\.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.

If a managed identity isn't available, and the application is running on Windows, the DefaultAzureCredential will then attempt reading from a local user token cache. AZURE_USERNAME environment variable must be specified if there are more than one accounts in the cache. The local token cache is shared between this library, Visual Studio (2019+), and Azure CLI. See Enable applications for shared token cache credential to see how to populate / clean up this token cache.

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.
 * If environment configuration is incomplete, it will try managed identity.
 */
public void createDefaultAzureCredential() {
    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(defaultCredential)
        .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.

/**
 *  Authenticate with client secret.
 */
public void createClientSecretCredential() {
    ClientSecretCredential clientSecretCredential = new ClientSecretCredentialBuilder()
        .clientId("<YOUR_CLIENT_ID>")
        .clientSecret("<YOUR_CLIENT_SECRET>")
        .tenantId("<YOUR_TENANT_ID>")
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .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.

/**
 * Authenticate with device code credential.
 */
public void createDeviceCodeCredential() {
    DeviceCodeCredential deviceCodeCredential = new DeviceCodeCredentialBuilder()
        .challengeConsumer(challenge -> {
            // lets user know of the challenge
            System.out.println(challenge.getMessage());
        })
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .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.

/**
 * Authenticate with username, password.
 */
public void createUserNamePasswordCredential() {
    UsernamePasswordCredential usernamePasswordCredential = new UsernamePasswordCredentialBuilder()
        .clientId("<YOUR_CLIENT_ID>")
        .username("<YOUR_USERNAME>")
        .password("<YOUR_PASSWORD>")
        .build();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .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.

/**
 * Authenticate with authorization code.
 */
public void createAuthCodeCredential() {
    AuthorizationCodeCredential authCodeCredential = new AuthorizationCodeCredentialBuilder()
        .clientId("<YOUR CLIENT ID>")
        .authorizationCode("<AUTH CODE FROM QUERY PARAMETERS")
        .redirectUrl("<THE REDIRECT URL>")
        .build();
    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .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.

/**
 * Authenticate with chained credentials.
 */
public void createChainedCredential() {
    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();

    // Azure SDK client builders accept the credential as a parameter
    SecretClient client = new SecretClientBuilder()
        .vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
        .credential(credentialChain)
        .buildClient();
}

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.

Impressions

Skip navigation links
Visit the Azure for Java Developerssite for more Java documentation, including quick starts, tutorials, and code samples.

Copyright © 2020 Microsoft Corporation. All rights reserved.