or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-authentication-flows.mdauthorization-code-authentication.mdazure-developer-cli-authentication.mdazure-pipelines-authentication.mdclient-assertion-authentication.mdconfiguration-and-utilities.mdcredential-chaining.mddefault-azure-credential.mddeveloper-tool-credentials.mdenvironment-credential.mdindex.mdinteractive-user-authentication.mdmanaged-identity-credential.mdservice-principal-authentication.mdshared-token-cache-authentication.mdusername-password-authentication.mdvisual-studio-code-authentication.md
tile.json

tessl/maven-com-azure--azure-identity

The Azure Identity library provides Microsoft Entra ID token authentication support across the Azure SDK with a comprehensive set of TokenCredential implementations.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.azure/azure-identity@1.16.x

To install, run

npx @tessl/cli install tessl/maven-com-azure--azure-identity@1.16.0

index.mddocs/

Azure Identity

The Azure Identity library provides Microsoft Entra ID (formerly Azure Active Directory) token authentication support across the Azure SDK. It offers a comprehensive set of TokenCredential implementations that can authenticate with Azure services using various authentication flows including managed identity, service principals, developer tools, and interactive authentication methods.

Package Information

  • Package Name: azure-identity
  • Package Type: maven
  • Group ID: com.azure
  • Artifact ID: azure-identity
  • Language: Java
  • Installation: Add to Maven dependencies with group com.azure and artifact azure-identity

Core Imports

import com.azure.identity.*;
import com.azure.core.credential.TokenCredential;

For specific credential types:

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;
import com.azure.identity.ClientSecretCredential;
import com.azure.identity.ClientSecretCredentialBuilder;

Basic Usage

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

// Create default credential chain for most common scenarios
TokenCredential credential = new DefaultAzureCredentialBuilder().build();

// Use with any Azure SDK client
SecretClient client = new SecretClientBuilder()
    .vaultUrl("https://myvault.vault.azure.net/")
    .credential(credential)
    .buildClient();

Architecture

The Azure Identity library is built around several key concepts:

  • TokenCredential Interface: All credentials implement this interface from azure-core
  • Credential Builders: Fluent builder pattern for configuring credentials
  • Authentication Flows: Support for various OAuth2 and Azure-specific flows
  • Token Caching: Automatic token caching and refresh capabilities
  • Multi-tenant Support: Ability to authenticate across multiple Azure tenants

Capabilities

Default Authentication Chain

The recommended approach for most applications, trying multiple authentication methods in sequence.

class DefaultAzureCredential extends ChainedTokenCredential implements TokenCredential {
    // Built using DefaultAzureCredentialBuilder
}

class DefaultAzureCredentialBuilder extends CredentialBuilderBase<DefaultAzureCredentialBuilder> {
    DefaultAzureCredentialBuilder tenantId(String tenantId);
    DefaultAzureCredentialBuilder authorityHost(String authorityHost);
    DefaultAzureCredentialBuilder managedIdentityClientId(String clientId);
    DefaultAzureCredentialBuilder workloadIdentityClientId(String clientId);
    DefaultAzureCredentialBuilder managedIdentityResourceId(String resourceId);
    DefaultAzureCredentialBuilder executorService(ExecutorService executorService);
    DefaultAzureCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
    DefaultAzureCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
    DefaultAzureCredentialBuilder credentialProcessTimeout(Duration credentialProcessTimeout);
    DefaultAzureCredentialBuilder disableInstanceDiscovery();
    DefaultAzureCredential build();
}

Default Azure Credential

Managed Identity Authentication

Authenticate using Azure Managed Identity for Azure-hosted applications.

class ManagedIdentityCredential implements TokenCredential {
    String getClientId();
    Mono<AccessToken> getToken(TokenRequestContext request);
}

class ManagedIdentityCredentialBuilder extends CredentialBuilderBase<ManagedIdentityCredentialBuilder> {
    ManagedIdentityCredentialBuilder clientId(String clientId);
    ManagedIdentityCredentialBuilder resourceId(String resourceId);
    ManagedIdentityCredentialBuilder objectId(String objectId);
    ManagedIdentityCredentialBuilder executorService(ExecutorService executorService);
    ManagedIdentityCredential build();
}

Managed Identity Credential

Service Principal Authentication

Authenticate using service principal credentials with client secrets or certificates.

class ClientSecretCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class ClientSecretCredentialBuilder extends AadCredentialBuilderBase<ClientSecretCredentialBuilder> {
    ClientSecretCredentialBuilder clientSecret(String clientSecret);
    ClientSecretCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
    ClientSecretCredential build();
}

class ClientCertificateCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class ClientCertificateCredentialBuilder extends AadCredentialBuilderBase<ClientCertificateCredentialBuilder> {
    ClientCertificateCredentialBuilder pemCertificate(String certificatePath);
    ClientCertificateCredentialBuilder pemCertificate(InputStream certificate);
    ClientCertificateCredentialBuilder pfxCertificate(String certificatePath);
    ClientCertificateCredentialBuilder pfxCertificate(InputStream certificate);
    ClientCertificateCredentialBuilder clientCertificatePassword(String clientCertificatePassword);
    ClientCertificateCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
    ClientCertificateCredentialBuilder sendCertificateChain(boolean sendCertificateChain);
    ClientCertificateCredential build();
}

Service Principal Authentication

Interactive User Authentication

Authenticate users through interactive flows including browser-based and device code authentication.

class InteractiveBrowserCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
    Mono<AuthenticationRecord> authenticate(TokenRequestContext request);
    Mono<AuthenticationRecord> authenticate();
}

class InteractiveBrowserCredentialBuilder extends AadCredentialBuilderBase<InteractiveBrowserCredentialBuilder> {
    InteractiveBrowserCredentialBuilder authenticationRecord(AuthenticationRecord authenticationRecord);
    InteractiveBrowserCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
    InteractiveBrowserCredentialBuilder redirectUrl(String redirectUrl);
    InteractiveBrowserCredentialBuilder disableAutomaticAuthentication();
    InteractiveBrowserCredentialBuilder loginHint(String loginHint);
    InteractiveBrowserCredentialBuilder browserCustomizationOptions(BrowserCustomizationOptions browserCustomizationOptions);
    InteractiveBrowserCredential build();
}

class DeviceCodeCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
    Mono<AuthenticationRecord> authenticate(TokenRequestContext request);
    Mono<AuthenticationRecord> authenticate();
}

class DeviceCodeCredentialBuilder extends AadCredentialBuilderBase<DeviceCodeCredentialBuilder> {
    DeviceCodeCredentialBuilder challengeConsumer(Consumer<DeviceCodeInfo> challengeConsumer);
    DeviceCodeCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
    DeviceCodeCredentialBuilder authenticationRecord(AuthenticationRecord authenticationRecord);
    DeviceCodeCredentialBuilder disableAutomaticAuthentication();
    DeviceCodeCredential build();
}

Interactive User Authentication

Developer Tool Credentials

Authenticate using cached credentials from Azure development tools.

class AzureCliCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class AzureCliCredentialBuilder extends CredentialBuilderBase<AzureCliCredentialBuilder> {
    AzureCliCredentialBuilder tenantId(String tenantId);
    AzureCliCredentialBuilder processTimeout(Duration processTimeout);
    AzureCliCredentialBuilder subscription(String subscription);
    AzureCliCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
    AzureCliCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
    AzureCliCredential build();
}

class AzurePowerShellCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
}

class AzurePowerShellCredentialBuilder extends CredentialBuilderBase<AzurePowerShellCredentialBuilder> {
    AzurePowerShellCredentialBuilder tenantId(String tenantId);
    AzurePowerShellCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
    AzurePowerShellCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
    AzurePowerShellCredential build();
}

Developer Tool Credentials

Advanced Authentication Flows

Support for specialized authentication scenarios including on-behalf-of flow and workload identity.

class OnBehalfOfCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class OnBehalfOfCredentialBuilder extends AadCredentialBuilderBase<OnBehalfOfCredentialBuilder> {
    OnBehalfOfCredentialBuilder clientSecret(String clientSecret);
    OnBehalfOfCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
    OnBehalfOfCredentialBuilder pemCertificate(String pemCertificatePath);
    OnBehalfOfCredentialBuilder pfxCertificate(String pfxCertificatePath);
    OnBehalfOfCredentialBuilder clientCertificatePassword(String clientCertificatePassword);
    OnBehalfOfCredentialBuilder sendCertificateChain(boolean sendCertificateChain);
    OnBehalfOfCredentialBuilder userAssertion(String userAssertion);
    OnBehalfOfCredentialBuilder clientAssertion(Supplier<String> clientAssertionSupplier);
    OnBehalfOfCredential build();
}

class WorkloadIdentityCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class WorkloadIdentityCredentialBuilder extends AadCredentialBuilderBase<WorkloadIdentityCredentialBuilder> {
    WorkloadIdentityCredentialBuilder tokenFilePath(String tokenFilePath);
    WorkloadIdentityCredential build();
}

Advanced Authentication Flows

Credential Chaining and Customization

Chain multiple credentials together and customize authentication behavior.

class ChainedTokenCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class ChainedTokenCredentialBuilder {
    ChainedTokenCredentialBuilder addLast(TokenCredential credential);
    ChainedTokenCredential build();
}

Credential Chaining

Environment Variable Authentication

Authenticate using environment variables for service principal credentials. Supports both client secret and client certificate authentication.

class EnvironmentCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class EnvironmentCredentialBuilder extends CredentialBuilderBase<EnvironmentCredentialBuilder> {
    EnvironmentCredentialBuilder authorityHost(String authorityHost);
    EnvironmentCredentialBuilder executorService(ExecutorService executorService);
    EnvironmentCredential build();
}

Environment Credential

Username Password Authentication

Authenticate using username and password credentials. Deprecated due to lack of multifactor authentication support.

@Deprecated
class UsernamePasswordCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
    Mono<AuthenticationRecord> authenticate(TokenRequestContext request);
    Mono<AuthenticationRecord> authenticate();
}

@Deprecated
class UsernamePasswordCredentialBuilder extends AadCredentialBuilderBase<UsernamePasswordCredentialBuilder> {
    UsernamePasswordCredentialBuilder username(String username);
    UsernamePasswordCredentialBuilder password(String password);
    UsernamePasswordCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
    UsernamePasswordCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
    UsernamePasswordCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
    UsernamePasswordCredential build();
}

Username Password Authentication

Client Assertion Authentication

Authenticate using client assertions (JWT bearer tokens) for service principal authentication.

class ClientAssertionCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class ClientAssertionCredentialBuilder extends AadCredentialBuilderBase<ClientAssertionCredentialBuilder> {
    ClientAssertionCredentialBuilder clientAssertion(Supplier<String> clientAssertionSupplier);
    ClientAssertionCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
    ClientAssertionCredential build();
}

Client Assertion Authentication

Authorization Code Authentication

Authenticate using OAuth 2.0 authorization code flow for web applications.

class AuthorizationCodeCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
}

class AuthorizationCodeCredentialBuilder extends AadCredentialBuilderBase<AuthorizationCodeCredentialBuilder> {
    AuthorizationCodeCredentialBuilder authorizationCode(String authCode);
    AuthorizationCodeCredentialBuilder redirectUrl(String redirectUrl);
    AuthorizationCodeCredentialBuilder clientSecret(String clientSecret);
    AuthorizationCodeCredential build();
}

Authorization Code Authentication

Azure Developer CLI Authentication

Authenticate using Azure Developer CLI (azd) cached credentials from development environments.

class AzureDeveloperCliCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class AzureDeveloperCliCredentialBuilder extends CredentialBuilderBase<AzureDeveloperCliCredentialBuilder> {
    AzureDeveloperCliCredentialBuilder tenantId(String tenantId);
    AzureDeveloperCliCredentialBuilder processTimeout(Duration processTimeout);
    AzureDeveloperCliCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
    AzureDeveloperCliCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
    AzureDeveloperCliCredential build();
}

Azure Developer CLI Authentication

Azure Pipelines Authentication

Authenticate using Azure Pipelines service connections for CI/CD scenarios.

class AzurePipelinesCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    AccessToken getTokenSync(TokenRequestContext request);
}

class AzurePipelinesCredentialBuilder extends AadCredentialBuilderBase<AzurePipelinesCredentialBuilder> {
    AzurePipelinesCredentialBuilder serviceConnectionId(String serviceConnectionId);
    AzurePipelinesCredentialBuilder systemAccessToken(String systemAccessToken);
    AzurePipelinesCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
    AzurePipelinesCredential build();
}

Azure Pipelines Authentication

Shared Token Cache Authentication

Legacy mechanism for authenticating using MSAL shared token cache (formerly Visual Studio integration).

class SharedTokenCacheCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
}

class SharedTokenCacheCredentialBuilder extends AadCredentialBuilderBase<SharedTokenCacheCredentialBuilder> {
    SharedTokenCacheCredentialBuilder username(String username);
    SharedTokenCacheCredentialBuilder tokenCachePersistenceOptions(TokenCachePersistenceOptions tokenCachePersistenceOptions);
    SharedTokenCacheCredentialBuilder authenticationRecord(AuthenticationRecord authenticationRecord);
    SharedTokenCacheCredential build();
}

Shared Token Cache Authentication

Visual Studio Code Authentication

Deprecated authentication using Visual Studio Code Azure Account extension credentials.

@Deprecated
class VisualStudioCodeCredential implements TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
}

@Deprecated
class VisualStudioCodeCredentialBuilder extends CredentialBuilderBase<VisualStudioCodeCredentialBuilder> {
    VisualStudioCodeCredentialBuilder tenantId(String tenantId);
    VisualStudioCodeCredentialBuilder additionallyAllowedTenants(String... additionallyAllowedTenants);
    VisualStudioCodeCredentialBuilder additionallyAllowedTenants(List<String> additionallyAllowedTenants);
    VisualStudioCodeCredential build();
}

Visual Studio Code Authentication

Configuration and Utilities

Configuration classes and utility functions for customizing authentication behavior.

class AzureAuthorityHosts {
    static final String AZURE_PUBLIC_CLOUD = "https://login.microsoftonline.com/";
    static final String AZURE_CHINA = "https://login.chinacloudapi.cn/";
    static final String AZURE_GOVERNMENT = "https://login.microsoftonline.us/";
}

class AuthenticationRecord {
    String getAuthority();
    String getHomeAccountId();
    String getTenantId();
    String getClientId();
    String getUsername();
    void serialize(OutputStream outputStream);
    static AuthenticationRecord deserialize(InputStream inputStream);
}

class DeviceCodeInfo {
    DeviceCodeInfo(String userCode, String deviceCode, String verificationUrl, OffsetDateTime expiresOn, String message);
    String getUserCode();
    String getDeviceCode();
    String getVerificationUrl();
    OffsetDateTime getExpiresOn();
    String getMessage();
}

class BrowserCustomizationOptions {
    BrowserCustomizationOptions();
    BrowserCustomizationOptions setSuccessMessage(String successMessage);
    BrowserCustomizationOptions setErrorMessage(String errorMessage);
    String getSuccessMessage();
    String getErrorMessage();
}

class TokenCachePersistenceOptions {
    TokenCachePersistenceOptions();
    TokenCachePersistenceOptions setUnencryptedStorageAllowed(boolean unencryptedStorageAllowed);
    boolean isUnencryptedStorageAllowed();
    TokenCachePersistenceOptions setName(String name);
    String getName();
}

class AuthenticationUtil {
    static Supplier<String> getBearerTokenSupplier(TokenCredential credential, String... scopes);
}

abstract class CredentialBuilderBase<T extends CredentialBuilderBase<T>> {
    T maxRetry(int maxRetry);
    T retryTimeout(Function<Duration, Duration> retryTimeout);
    T httpClient(HttpClient client);
    T configuration(Configuration configuration);
    T clientOptions(ClientOptions clientOptions);
    T httpLogOptions(HttpLogOptions logOptions);
    T retryPolicy(RetryPolicy retryPolicy);
    T retryOptions(RetryOptions retryOptions);
    T addPolicy(HttpPipelinePolicy policy);
    T pipeline(HttpPipeline pipeline);
    T enableAccountIdentifierLogging();
}

abstract class AadCredentialBuilderBase<T extends AadCredentialBuilderBase<T>> extends CredentialBuilderBase<T> {
    T authorityHost(String authorityHost);
    T clientId(String clientId);
    T tenantId(String tenantId);
    T executorService(ExecutorService executorService);
    T additionallyAllowedTenants(String... additionallyAllowedTenants);
    T additionallyAllowedTenants(List<String> additionallyAllowedTenants);
    T disableInstanceDiscovery();
    T enableUnsafeSupportLogging();
}

Configuration and Utilities

Exception Handling

class CredentialUnavailableException extends ClientAuthenticationException {
    CredentialUnavailableException(String message);
    CredentialUnavailableException(String message, Throwable cause);
}

class AuthenticationRequiredException extends CredentialUnavailableException {
    AuthenticationRequiredException(String message, TokenRequestContext request);
    AuthenticationRequiredException(String message, TokenRequestContext request, Throwable cause);
    TokenRequestContext getTokenRequestContext();
}

Types

// From azure-core - key interface implemented by all credentials
interface TokenCredential {
    Mono<AccessToken> getToken(TokenRequestContext request);
    default AccessToken getTokenSync(TokenRequestContext request);
}

// Token request context specifying the scopes and tenant
class TokenRequestContext {
    List<String> getScopes();
    String getTenantId();
    String getClaims();
}

// Access token with expiration information
class AccessToken {
    String getToken();
    OffsetDateTime getExpiresAt();
    boolean isExpired();
}