azure-identity-java

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure Identity (Java)

Azure Identity（Java版）

Authenticate Java applications with Azure services using Microsoft Entra ID (Azure AD).

使用Microsoft Entra ID（Azure AD）对Java应用程序进行Azure服务身份验证。

Installation

安装

xml

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.0</version>
</dependency>

xml

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.15.0</version>
</dependency>

Key Concepts

核心概念

Credential	Use Case
`DefaultAzureCredential`	Recommended - Works in dev and production
`ManagedIdentityCredential`	Azure-hosted apps (App Service, Functions, VMs)
`EnvironmentCredential`	CI/CD pipelines with env vars
`ClientSecretCredential`	Service principals with secret
`ClientCertificateCredential`	Service principals with certificate
`AzureCliCredential`	Local dev using `az login`
`InteractiveBrowserCredential`	Interactive login flow
`DeviceCodeCredential`	Headless device authentication

凭据	使用场景
`DefaultAzureCredential`	推荐使用 - 适用于开发和生产环境
`ManagedIdentityCredential`	Azure托管应用（App Service、Functions、VM）
`EnvironmentCredential`	使用环境变量的CI/CD流水线
`ClientSecretCredential`	带密钥的服务主体
`ClientCertificateCredential`	带证书的服务主体
`AzureCliCredential`	使用 `az login` 的本地开发场景
`InteractiveBrowserCredential`	交互式登录流程
`DeviceCodeCredential`	无头设备身份验证

DefaultAzureCredential (Recommended)

DefaultAzureCredential（推荐使用）

The

DefaultAzureCredential

tries multiple authentication methods in order:

Environment variables
Workload Identity
Managed Identity
Azure CLI
Azure PowerShell
Azure Developer CLI

java

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

// Simple usage
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Use with any Azure client
BlobServiceClient blobClient = new BlobServiceClientBuilder()
    .endpoint("https://<storage-account>.blob.core.windows.net")
    .credential(credential)
    .buildClient();

KeyClient keyClient = new KeyClientBuilder()
    .vaultUrl("https://<vault-name>.vault.azure.net")
    .credential(credential)
    .buildClient();

DefaultAzureCredential

会按以下顺序尝试多种身份验证方法：

环境变量
工作负载标识
托管标识
Azure CLI
Azure PowerShell
Azure Developer CLI

java

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

// 简单用法
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// 与任意Azure客户端结合使用
BlobServiceClient blobClient = new BlobServiceClientBuilder()
    .endpoint("https://<storage-account>.blob.core.windows.net")
    .credential(credential)
    .buildClient();

KeyClient keyClient = new KeyClientBuilder()
    .vaultUrl("https://<vault-name>.vault.azure.net")
    .credential(credential)
    .buildClient();

Configure DefaultAzureCredential

配置DefaultAzureCredential

java

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .managedIdentityClientId("<user-assigned-identity-client-id>")  // For user-assigned MI
    .tenantId("<tenant-id>")                                        // Limit to specific tenant
    .excludeEnvironmentCredential()                                 // Skip env vars
    .excludeAzureCliCredential()                                    // Skip Azure CLI
    .build();

java

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .managedIdentityClientId("<user-assigned-identity-client-id>")  // 用于用户分配的托管标识
    .tenantId("<tenant-id>")                                        // 限制到特定租户
    .excludeEnvironmentCredential()                                 // 跳过环境变量
    .excludeAzureCliCredential()                                    // 跳过Azure CLI
    .build();

Managed Identity

托管标识

For Azure-hosted applications (App Service, Functions, AKS, VMs).

java

import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// System-assigned managed identity
ManagedIdentityCredential credential = new ManagedIdentityCredentialBuilder()
    .build();

// User-assigned managed identity (by client ID)
ManagedIdentityCredential credential = new ManagedIdentityCredentialBuilder()
    .clientId("<user-assigned-client-id>")
    .build();

// User-assigned managed identity (by resource ID)
ManagedIdentityCredential credential = new ManagedIdentityCredentialBuilder()
    .resourceId("/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>")
    .build();

适用于Azure托管的应用程序（App Service、Functions、AKS、VM）。

java

import com.azure.identity.ManagedIdentityCredential;
import com.azure.identity.ManagedIdentityCredentialBuilder;

// 系统分配的托管标识
ManagedIdentityCredential credential = new ManagedIdentityCredentialBuilder()
    .build();

// 用户分配的托管标识（通过客户端ID）
ManagedIdentityCredential credential = new ManagedIdentityCredentialBuilder()
    .clientId("<user-assigned-client-id>")
    .build();

// 用户分配的托管标识（通过资源ID）
ManagedIdentityCredential credential = new ManagedIdentityCredentialBuilder()
    .resourceId("/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<name>")
    .build();

Service Principal with Secret

带密钥的服务主体

java

import com.azure.identity.ClientSecretCredential;
import com.azure.identity.ClientSecretCredentialBuilder;

ClientSecretCredential credential = new ClientSecretCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .clientSecret("<client-secret>")
    .build();

java

import com.azure.identity.ClientSecretCredential;
import com.azure.identity.ClientSecretCredentialBuilder;

ClientSecretCredential credential = new ClientSecretCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .clientSecret("<client-secret>")
    .build();

Service Principal with Certificate

带证书的服务主体

java

import com.azure.identity.ClientCertificateCredential;
import com.azure.identity.ClientCertificateCredentialBuilder;

// From PEM file
ClientCertificateCredential credential = new ClientCertificateCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .pemCertificate("<path-to-cert.pem>")
    .build();

// From PFX file with password
ClientCertificateCredential credential = new ClientCertificateCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .pfxCertificate("<path-to-cert.pfx>", "<pfx-password>")
    .build();

// Send certificate chain for SNI
ClientCertificateCredential credential = new ClientCertificateCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .pemCertificate("<path-to-cert.pem>")
    .sendCertificateChain(true)
    .build();

java

import com.azure.identity.ClientCertificateCredential;
import com.azure.identity.ClientCertificateCredentialBuilder;

// 从PEM文件加载
ClientCertificateCredential credential = new ClientCertificateCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .pemCertificate("<path-to-cert.pem>")
    .build();

// 从带密码的PFX文件加载
ClientCertificateCredential credential = new ClientCertificateCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .pfxCertificate("<path-to-cert.pfx>", "<pfx-password>")
    .build();

// 发送证书链用于SNI
ClientCertificateCredential credential = new ClientCertificateCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .pemCertificate("<path-to-cert.pem>")
    .sendCertificateChain(true)
    .build();

Environment Credential

环境凭据

Reads credentials from environment variables.

java

import com.azure.identity.EnvironmentCredential;
import com.azure.identity.EnvironmentCredentialBuilder;

EnvironmentCredential credential = new EnvironmentCredentialBuilder().build();

从环境变量中读取凭据。

java

import com.azure.identity.EnvironmentCredential;
import com.azure.identity.EnvironmentCredentialBuilder;

EnvironmentCredential credential = new EnvironmentCredentialBuilder().build();

Required Environment Variables

所需环境变量

For service principal with secret:

bash

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

For service principal with certificate:

bash

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pem
AZURE_CLIENT_CERTIFICATE_PASSWORD=<optional-password>

For username/password:

bash

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_USERNAME=<username>
AZURE_PASSWORD=<password>

带密钥的服务主体：

bash

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_SECRET=<client-secret>

带证书的服务主体：

bash

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_CLIENT_CERTIFICATE_PATH=/path/to/cert.pem
AZURE_CLIENT_CERTIFICATE_PASSWORD=<optional-password>

用户名/密码：

bash

AZURE_TENANT_ID=<tenant-id>
AZURE_CLIENT_ID=<client-id>
AZURE_USERNAME=<username>
AZURE_PASSWORD=<password>

Azure CLI Credential

Azure CLI凭据

For local development using

az login

java

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;

AzureCliCredential credential = new AzureCliCredentialBuilder()
    .tenantId("<tenant-id>")  // Optional: specific tenant
    .build();

适用于使用

az login

的本地开发场景。

java

import com.azure.identity.AzureCliCredential;
import com.azure.identity.AzureCliCredentialBuilder;

AzureCliCredential credential = new AzureCliCredentialBuilder()
    .tenantId("<tenant-id>")  // 可选：特定租户
    .build();

Interactive Browser

交互式浏览器

For desktop applications requiring user login.

java

import com.azure.identity.InteractiveBrowserCredential;
import com.azure.identity.InteractiveBrowserCredentialBuilder;

InteractiveBrowserCredential credential = new InteractiveBrowserCredentialBuilder()
    .clientId("<client-id>")
    .redirectUrl("http://localhost:8080")  // Must match app registration
    .build();

适用于需要用户登录的桌面应用程序。

java

import com.azure.identity.InteractiveBrowserCredential;
import com.azure.identity.InteractiveBrowserCredentialBuilder;

InteractiveBrowserCredential credential = new InteractiveBrowserCredentialBuilder()
    .clientId("<client-id>")
    .redirectUrl("http://localhost:8080")  // 必须与应用注册的重定向URL匹配
    .build();

Device Code

设备代码

For headless devices (IoT, CLI tools).

java

import com.azure.identity.DeviceCodeCredential;
import com.azure.identity.DeviceCodeCredentialBuilder;

DeviceCodeCredential credential = new DeviceCodeCredentialBuilder()
    .clientId("<client-id>")
    .challengeConsumer(challenge -> {
        // Display to user
        System.out.println(challenge.getMessage());
    })
    .build();

适用于无头设备（IoT、CLI工具）。

java

import com.azure.identity.DeviceCodeCredential;
import com.azure.identity.DeviceCodeCredentialBuilder;

DeviceCodeCredential credential = new DeviceCodeCredentialBuilder()
    .clientId("<client-id>")
    .challengeConsumer(challenge -> {
        // 显示给用户
        System.out.println(challenge.getMessage());
    })
    .build();

Chained Credential

链式凭据

Create custom authentication chains.

java

import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addFirst(new ManagedIdentityCredentialBuilder().build())
    .addLast(new AzureCliCredentialBuilder().build())
    .build();

创建自定义身份验证链。

java

import com.azure.identity.ChainedTokenCredential;
import com.azure.identity.ChainedTokenCredentialBuilder;

ChainedTokenCredential credential = new ChainedTokenCredentialBuilder()
    .addFirst(new ManagedIdentityCredentialBuilder().build())
    .addLast(new AzureCliCredentialBuilder().build())
    .build();

Workload Identity (AKS)

工作负载标识（AKS）

For Azure Kubernetes Service with workload identity.

java

import com.azure.identity.WorkloadIdentityCredential;
import com.azure.identity.WorkloadIdentityCredentialBuilder;

// Reads from AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_FEDERATED_TOKEN_FILE
WorkloadIdentityCredential credential = new WorkloadIdentityCredentialBuilder().build();

// Or explicit configuration
WorkloadIdentityCredential credential = new WorkloadIdentityCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .tokenFilePath("/var/run/secrets/azure/tokens/azure-identity-token")
    .build();

适用于启用工作负载标识的Azure Kubernetes Service。

java

import com.azure.identity.WorkloadIdentityCredential;
import com.azure.identity.WorkloadIdentityCredentialBuilder;

// 从AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_FEDERATED_TOKEN_FILE读取配置
WorkloadIdentityCredential credential = new WorkloadIdentityCredentialBuilder().build();

// 或显式配置
WorkloadIdentityCredential credential = new WorkloadIdentityCredentialBuilder()
    .tenantId("<tenant-id>")
    .clientId("<client-id>")
    .tokenFilePath("/var/run/secrets/azure/tokens/azure-identity-token")
    .build();

Token Caching

令牌缓存

Enable persistent token caching for better performance.

java

// Enable token caching (in-memory by default)
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .enableAccountIdentifierLogging()
    .build();

// With shared token cache (for multi-credential scenarios)
SharedTokenCacheCredential credential = new SharedTokenCacheCredentialBuilder()
    .clientId("<client-id>")
    .build();

启用持久令牌缓存以提升性能。

java

// 启用令牌缓存（默认是内存缓存）
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .enableAccountIdentifierLogging()
    .build();

// 共享令牌缓存（适用于多凭据场景）
SharedTokenCacheCredential credential = new SharedTokenCacheCredentialBuilder()
    .clientId("<client-id>")
    .build();

Sovereign Clouds

主权云

java

import com.azure.identity.AzureAuthorityHosts;

// Azure Government
DefaultAzureCredential govCredential = new DefaultAzureCredentialBuilder()
    .authorityHost(AzureAuthorityHosts.AZURE_GOVERNMENT)
    .build();

// Azure China
DefaultAzureCredential chinaCredential = new DefaultAzureCredentialBuilder()
    .authorityHost(AzureAuthorityHosts.AZURE_CHINA)
    .build();

java

import com.azure.identity.AzureAuthorityHosts;

// Azure政府云
DefaultAzureCredential govCredential = new DefaultAzureCredentialBuilder()
    .authorityHost(AzureAuthorityHosts.AZURE_GOVERNMENT)
    .build();

// Azure中国云
DefaultAzureCredential chinaCredential = new DefaultAzureCredentialBuilder()
    .authorityHost(AzureAuthorityHosts.AZURE_CHINA)
    .build();

Error Handling

错误处理

java

import com.azure.identity.CredentialUnavailableException;
import com.azure.core.exception.ClientAuthenticationException;

try {
    DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
    AccessToken token = credential.getToken(new TokenRequestContext()
        .addScopes("https://management.azure.com/.default"));
} catch (CredentialUnavailableException e) {
    // No credential could authenticate
    System.out.println("Authentication failed: " + e.getMessage());
} catch (ClientAuthenticationException e) {
    // Authentication error (wrong credentials, expired, etc.)
    System.out.println("Auth error: " + e.getMessage());
}

java

import com.azure.identity.CredentialUnavailableException;
import com.azure.core.exception.ClientAuthenticationException;

try {
    DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();
    AccessToken token = credential.getToken(new TokenRequestContext()
        .addScopes("https://management.azure.com/.default"));
} catch (CredentialUnavailableException e) {
    // 没有可用的凭据可以完成身份验证
    System.out.println("身份验证失败：" + e.getMessage());
} catch (ClientAuthenticationException e) {
    // 身份验证错误（凭据错误、过期等）
    System.out.println("身份验证错误：" + e.getMessage());
}

Logging

日志

Enable authentication logging for debugging.

java

// Via environment variable
// AZURE_LOG_LEVEL=verbose

// Or programmatically
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .enableAccountIdentifierLogging()  // Log account info
    .build();

启用身份验证日志以进行调试。

java

// 通过环境变量
// AZURE_LOG_LEVEL=verbose

// 或通过代码配置
DefaultAzureCredential credential = new DefaultAzureCredentialBuilder()
    .enableAccountIdentifierLogging()  // 记录账户信息
    .build();

Environment Variables

环境变量

bash

undefined

bash

undefined

DefaultAzureCredential configuration

DefaultAzureCredential配置

AZURE_TENANT_ID=<tenant-id> AZURE_CLIENT_ID=<client-id> AZURE_CLIENT_SECRET=<client-secret>

Managed Identity

托管标识

AZURE_CLIENT_ID=<user-assigned-mi-client-id>

Workload Identity (AKS)

工作负载标识（AKS）

AZURE_FEDERATED_TOKEN_FILE=/var/run/secrets/azure/tokens/azure-identity-token

Logging

日志

AZURE_LOG_LEVEL=verbose

Authority host

授权主机

AZURE_AUTHORITY_HOST=https://login.microsoftonline.com/

undefined

AZURE_AUTHORITY_HOST=https://login.microsoftonline.com/

undefined

Best Practices

最佳实践

Use DefaultAzureCredential - Works seamlessly from dev to production
Managed Identity in Production - No secrets to manage, automatic rotation
Azure CLI for Local Dev - Run
```
az login
```
before running your app
Least Privilege - Grant only required permissions to service principals
Token Caching - Enabled by default, reduces auth round-trips
Environment Variables - Use for CI/CD, not hardcoded secrets

使用DefaultAzureCredential - 从开发到生产环境无缝适配
生产环境使用托管标识 - 无需管理密钥，自动轮换
本地开发使用Azure CLI - 运行应用前先执行
```
az login
```
最小权限原则 - 只为服务主体授予所需的权限
令牌缓存 - 默认启用，减少身份验证往返次数
环境变量 - 用于CI/CD流程，不要硬编码密钥

Credential Selection Matrix

凭据选择矩阵

Environment	Recommended Credential
Local Development	`DefaultAzureCredential` (uses Azure CLI)
Azure App Service	`DefaultAzureCredential` (uses Managed Identity)
Azure Functions	`DefaultAzureCredential` (uses Managed Identity)
Azure Kubernetes Service	`WorkloadIdentityCredential`
Azure VMs	`DefaultAzureCredential` (uses Managed Identity)
CI/CD Pipeline	`EnvironmentCredential`
Desktop App	`InteractiveBrowserCredential`
CLI Tool	`DeviceCodeCredential`

环境	推荐使用的凭据
本地开发	`DefaultAzureCredential` （使用Azure CLI）
Azure App Service	`DefaultAzureCredential` （使用托管标识）
Azure Functions	`DefaultAzureCredential` （使用托管标识）
Azure Kubernetes Service	`WorkloadIdentityCredential`
Azure VMs	`DefaultAzureCredential` （使用托管标识）
CI/CD流水线	`EnvironmentCredential`
桌面应用	`InteractiveBrowserCredential`
CLI工具	`DeviceCodeCredential`

Trigger Phrases

触发短语

"Azure authentication Java", "DefaultAzureCredential Java"
"managed identity Java", "service principal Java"
"Azure login Java", "Azure credentials Java"
"AZURE_CLIENT_ID", "AZURE_TENANT_ID"

"Azure authentication Java", "DefaultAzureCredential Java"
"managed identity Java", "service principal Java"
"Azure login Java", "Azure credentials Java"
"AZURE_CLIENT_ID", "AZURE_TENANT_ID"

When to Use

使用场景

This skill is applicable to execute the workflow or actions described in the overview.

本技能适用于执行概述中描述的工作流或操作。