你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
适用于 Java 的 Azure 标识客户端库 - 版本 1.10.4
Azure 标识库跨 Azure SDK 提供 Azure Active Directory (Azure AD) 令牌身份验证支持。 它提供一组 TokenCredential 实现，可用于构造支持 Azure AD 令牌身份验证的 Azure SDK 客户端。
源代码 | API 参考文档 | Azure AD 文档
入门
添加包
包括 BOM 文件
azure-sdk-bom在项目中包括 ，以依赖于库的稳定版本。 在以下代码片段中，将 {bom_version_to_target} 占位符替换为版本号。 若要了解有关 BOM 的详细信息，请参阅 Azure SDK BOM 自述文件。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-sdk-bom</artifactId>
<version>{bom_version_to_target}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
然后，在不带版本标记的 dependencies 节中包含直接依赖项：
<dependencies>
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
</dependency>
</dependencies>
包括直接依赖项
若要依赖于 BOM 中不存在的特定版本的库，请将直接依赖项添加到项目，如下所示：
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.10.1</version>
</dependency>
先决条件
- Java 开发工具包 (JDK) 8 或更高版本。
- 一个 Azure 订阅。
- Azure CLI 还可用于在开发环境中进行身份验证、创建帐户和管理帐户角色。
验证客户端
在本地调试和执行代码时，开发人员通常使用自己的帐户对 Azure 服务的调用进行身份验证。 有几个开发人员工具可用于在开发环境中执行此身份验证：
- Azure Toolkit for IntelliJ
- Visual Studio Code Azure 帐户扩展
- 这是一个已知问题，
VisualStudioCodeCredential不适用于低于 0.9.11 的 Azure 帐户扩展版本。 正在对此问题进行长期修复。 同时，请考虑通过 Azure CLI (以下) 进行身份验证。
- 这是一个已知问题，
- Azure CLI
选择上述每个项，了解如何为 Azure 标识身份验证配置它们。
关键概念
凭证
凭据是一种类，包含或可以获取服务客户端对请求进行身份验证所需的数据。 Azure SDK 中的服务客户端在构造时接受凭据。 服务客户端使用这些凭据对服务的请求进行身份验证。
Azure 标识库侧重于使用 Azure AD 进行 OAuth 身份验证，并提供各种凭据类，这些凭据类能够获取 Azure AD 令牌来对服务请求进行身份验证。 此库中的所有凭据类都是 azure-core 中抽象类的TokenCredential实现，其中任何凭据类都可以用于构造能够使用 TokenCredential进行身份验证的服务客户端。
有关可用 凭据类 的完整列表，请参阅凭据类。
DefaultAzureCredential
适用于 DefaultAzureCredential 应用程序最终在 Azure 中运行的大多数方案。 这是因为 DefaultAzureCredential 会将部署期间常用于进行身份验证的凭据与开发环境中用于进行身份验证的凭据组合在一起。
注意：
DefaultAzureCredential旨在通过处理具有合理默认行为的常见方案来简化 SDK 入门。 对于想要拥有更多控制或其方案缺少默认设置的开发人员，应使用其他凭据类型。
DefaultAzureCredential 将按顺序尝试通过以下机制进行身份验证。
- 环境 -
DefaultAzureCredential将读取通过 环境变量 指定的帐户信息，并使用它来进行身份验证。 - 工作负载标识 - 如果使用工作负载标识 Webhook 设置的环境变量在 Kubernetes 上部署应用，
DefaultAzureCredential则会对配置的标识进行身份验证。 - 托管标识 - 如果应用程序部署到启用了托管标识的 Azure 主机，
DefaultAzureCredential将使用该帐户进行身份验证。 - Azure Developer CLI - 如果开发人员已通过 Azure Developer CLI
azd auth login命令对帐户进行身份验证，DefaultAzureCredential将使用该帐户进行身份验证。 - IntelliJ - 如果开发人员已通过 Azure Toolkit for IntelliJ 进行身份验证，
DefaultAzureCredential将使用该帐户进行身份验证。 - Azure CLI - 如果开发人员已通过 Azure CLI
az login命令对帐户进行身份验证，DefaultAzureCredential则 将使用该帐户进行身份验证。 - Azure PowerShell - 如果开发人员已通过 Azure PowerShell
Connect-AzAccount命令对帐户进行身份验证，DefaultAzureCredential将使用该帐户进行身份验证。
延续策略
从 v1.10.0 开始， DefaultAzureCredential 将尝试使用所有开发人员凭据进行身份验证，直到一个凭据成功为止，而不管以前的开发人员凭据是否遇到任何错误。 例如，开发人员凭据可能会尝试获取令牌但失败，因此 DefaultAzureCredential 将继续访问流中的下一个凭据。 如果已部署的服务凭据能够尝试检索令牌，但未收到令牌检索，则会停止流并引发异常。
这允许尝试计算机上的所有开发人员凭据，同时具有可预测的部署行为。
关于 的注意事项 VisualStudioCodeCredential
由于 已知问题， VisualStudioCodeCredential 已从令牌链中删除 DefaultAzureCredential 。 在将来的版本中解决问题后，将还原此更改。
示例
可以在 Azure 标识示例 Wiki 页中找到有关使用各种凭据的更多示例。
使用 DefaultAzureCredential 进行身份验证
该示例演示如何使用 DefaultAzureCredential 对来自 azure-security-keyvault-secrets 客户端库的 SecretClient 进行身份验证。
/**
* 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();
}
若要详细了解如何在工作站或 Azure 上配置 DefaultAzureCredential ，请参阅 配置 DefaultAzureCredential。
使用 对用户分配的托管标识进行身份验证 DefaultAzureCredential
若要使用用户分配的托管标识进行身份验证，请确保 此处 支持的 Azure 资源的配置说明已成功完成。
以下示例演示如何使用 DefaultAzureCredential从 azure-security-keyvault-secrets 客户端库对 进行身份验证SecretClient，这些客户端库部署到配置了用户分配的托管标识的 Azure 资源。
若要详细了解如何为 Azure 资源配置用户分配的托管标识，请参阅 为 Azure 资源启用托管标识。
/**
* The default credential will use the user assigned managed identity with the specified client ID.
*/
public void createDefaultAzureCredentialForUserAssignedManagedIdentity() {
DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
.managedIdentityClientId("<MANAGED_IDENTITY_CLIENT_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(defaultCredential)
.buildClient();
}
除了通过代码配置 managedIdentityClientId 之外，还可以使用 AZURE_CLIENT_ID 环境变量对其进行设置。 使用 时，这两种方法是等效的 DefaultAzureCredential。
使用 对 Azure Toolkit for IntelliJ 中的用户进行身份验证 DefaultAzureCredential
若要使用 IntelliJ 进行身份验证，请确保 此处 的配置说明已成功完成。
以下示例演示如何在DefaultAzureCredential安装了 IntelliJ IDEA 的工作站上使用 从 azure-security-keyvault-secrets 客户端库对 进行身份验证SecretClient，并且用户已使用 Azure 帐户登录到 Azure Toolkit for IntelliJ。
若要详细了解如何配置 IntelliJ IDEA，请参阅 登录 Azure Toolkit for IntelliJ for IntelliJCredential。
/**
* The default credential will use the KeePass database path to find the user account in IntelliJ on Windows.
*/
public void createDefaultAzureCredentialForIntelliJ() {
DefaultAzureCredential defaultCredential = new DefaultAzureCredentialBuilder()
// KeePass configuration required only for Windows. No configuration needed for Linux / Mac
.intelliJKeePassDatabasePath("C:\\Users\\user\\AppData\\Roaming\\JetBrains\\IdeaIC2020.1\\c.kdbx")
.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();
}
托管标识支持
以下 Azure 服务通过 或 ManagedIdentityCredential 直接支持DefaultAzureCredential托管标识身份验证：
- Azure 应用服务和 Azure Functions
- Azure Arc
- Azure Cloud Shell
- Azure Kubernetes 服务
- Azure Service Fabric
- Azure 虚拟机
- Azure 虚拟机规模集
注意： 使用 azure-identity 版本 1.7.0 或更高版本来利用托管标识身份验证的 令牌缓存 支持。
示例
使用托管标识在 Azure 中进行身份验证
此示例演示如何在 Azure 上的虚拟机、应用服务、函数应用、cloud shell 或 AKS 环境中使用 ManagedIdentityCredentialazure-security-keyvault-secrets 客户端库中的 进行身份验证SecretClient，并启用系统分配的或用户分配的托管标识。
若要详细了解如何为托管标识配置 Azure 资源，请参阅 为 Azure 资源启用托管标识
/**
* Authenticate with a User Assigned Managed identity.
*/
public void createManagedIdentityCredential() {
ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
.clientId("<USER ASSIGNED MANAGED IDENTITY CLIENT ID>") // only required for user assigned
.build();
// Azure SDK client builders accept the credential as a parameter
SecretClient client = new SecretClientBuilder()
.vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
.credential(managedIdentityCredential)
.buildClient();
}
/**
* Authenticate with a System Assigned Managed identity.
*/
public void createManagedIdentityCredential() {
ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder()
.build();
// Azure SDK client builders accept the credential as a parameter
SecretClient client = new SecretClientBuilder()
.vaultUrl("https://{YOUR_VAULT_NAME}.vault.azure.net")
.credential(managedIdentityCredential)
.buildClient();
}
使用 ChainedTokenCredential 定义自定义身份验证流
虽然 DefaultAzureCredential 通常是开始为 Azure 开发应用程序的最快方法，但更高级的用户可能希望自定义身份验证时考虑的凭据。 ChainedTokenCredential 使用户能够组合多个凭据实例来定义自定义的凭据链。 此示例演示如何创建一个 ChainedTokenCredential，它将：
- 尝试使用托管标识进行身份验证。
- 如果托管标识在当前环境中不可用，请回退到通过 Azure CLI 进行身份验证。
// Authenticate using managed identity if it is available; otherwise use the Azure CLI to authenticate.
ManagedIdentityCredential managedIdentityCredential = new ManagedIdentityCredentialBuilder().build();
AzureCliCredential cliCredential = new AzureCliCredentialBuilder().build();
ChainedTokenCredential credential = new ChainedTokenCredentialBuilder().addLast(managedIdentityCredential).addLast(cliCredential).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();
云配置
凭据默认为向 Azure 公有云的 Azure AD 终结点进行身份验证。 若要访问其他云中的资源（例如Azure 政府或私有云），请使用 参数配置凭据auhtorityHost。 AzureAuthorityHosts 定义已知云的颁发机构：
DefaultAzureCredential defaultAzureCredential = new DefaultAzureCredentialBuilder()
.authorityHost(AzureAuthorityHosts.AZURE_GOVERNMENT)
.build();
并非所有凭据都需要此配置。 通过开发工具（如 AzureCliCredential）进行身份验证的凭据使用该工具的配置。 同样， VisualStudioCodeCredential 接受 参数， authority 但默认为与 VS Code 的“Azure： Cloud”设置匹配的颁发机构。
凭据类
对 Azure 托管的应用程序进行身份验证
| Credential 类 | 使用情况 | 示例 |
|---|---|---|
DefaultAzureCredential |
提供简化的身份验证体验，可快速开始开发在 Azure 中运行的应用程序 | 示例 |
ChainedTokenCredential |
允许用户定义组合多个凭据的自定义身份验证流 | 示例 |
EnvironmentCredential |
通过环境变量中指定的凭据信息对服务主体或用户进行身份验证 | |
ManagedIdentityCredential |
对 Azure 资源的托管标识进行身份验证 | 示例 |
WorkloadIdentityCredential |
支持 Kubernetes 上的 Azure AD 工作负载标识 | 示例 |
对服务主体进行身份验证
| Credential 类 | 使用情况 | 示例 | 参考 |
|---|---|---|---|
ClientAssertionCredential |
使用签名客户端断言对服务主体进行身份验证 | ||
ClientCertificateCredential |
使用证书对服务主体进行身份验证 | 示例 | 服务主体身份验证 |
ClientSecretCredential |
使用机密对服务主体进行身份验证 | 示例 | 服务主体身份验证 |
对用户进行身份验证
| Credential 类 | 使用情况 | 示例 | 参考 |
|---|---|---|---|
AuthorizationCodeCredential |
使用以前获取的授权代码作为 Oauth 2 流的一部分对用户进行身份验证 | OAuth2 验证码 | |
DeviceCodeCredential |
以交互方式在 UI 受限的设备上对用户进行身份验证 | 示例 | 设备代码身份验证 |
InteractiveBrowserCredential |
使用默认系统浏览器以交互方式对用户进行身份验证 | 示例 | OAuth2 验证码 |
OnBehalfOfCredential |
通过请求链传播委托的用户标识和权限 | 代理身份验证 | |
UsernamePasswordCredential |
使用用户名和密码对用户进行身份验证，而无需多重身份验证 | 示例 | 用户名 + 密码身份验证 |
通过开发工具进行身份验证
| Credential 类 | 使用情况 | 示例 | 参考 |
|---|---|---|---|
AzureCliCredential |
在 Azure CLI 中使用已启用的用户或服务主体在开发环境中进行身份验证 | 示例 | Azure CLI 身份验证 |
AzureDeveloperCliCredential |
使用 Azure Developer CLI 中已启用的用户或服务主体在开发环境中进行身份验证 | Azure Developer CLI参考 | |
AzurePowerShellCredential |
使用 Azure PowerShell 中已启用的用户或服务主体在开发环境中进行身份验证 | 示例 | Azure PowerShell 文档 |
IntelliJCredential |
在开发环境中使用 Azure Toolkit for IntelliJ 中的帐户进行身份验证 | 示例 | IntelliJ 身份验证 |
VisualStudioCodeCredential |
使用 Azure 帐户扩展中的帐户在开发环境中进行身份验证Visual Studio Code。 | 示例 | VS Code Azure 帐户扩展 |
注意： Azure 标识库中的所有凭据实现都是线程安全的，单个凭据实例可用于创建多个服务客户端。
凭据可以链接在一起以依次尝试，直到成功使用 ChainedTokenCredential;有关详细信息，请参阅 链接凭据 。
环境变量
DefaultAzureCredential 和 EnvironmentCredential 可通过环境变量进行配置。 每种类型的身份验证都需要特定变量的值：
具有机密的服务主体
| 变量名称 | 值 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 应用程序的 ID |
AZURE_TENANT_ID |
应用程序的 Azure AD 租户的 ID |
AZURE_CLIENT_SECRET |
应用程序的客户端机密之一 |
具有证书的服务主体
| 变量名称 | 值 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 应用程序的 ID |
AZURE_TENANT_ID |
应用程序的 Azure AD 租户的 ID |
AZURE_CLIENT_CERTIFICATE_PATH |
PFX 或 PEM 编码的证书文件（包括私钥）的路径 |
AZURE_CLIENT_CERTIFICATE_PASSWORD |
(证书的可选) 密码。 除非指定此值，否则证书不能受密码保护。 |
用户名和密码
| 变量名称 | 值 |
|---|---|
AZURE_CLIENT_ID |
Azure AD 应用程序的 ID |
AZURE_TENANT_ID |
(应用程序的 Azure AD 租户的可选) ID |
AZURE_USERNAME |
用户名（通常为电子邮件地址） |
AZURE_PASSWORD |
该用户的密码 |
按上述顺序尝试进行配置。 例如，如果客户端机密和证书的值都存在，则将使用客户端机密。
连续访问评估
从 v1.10.0 开始，可以按请求访问 受持续访问评估 (CAE) 保护的资源。 可以使用 API 启用此功能TokenRequestContext.setCaeEnabled(boolean)。 开发人员凭据不支持 CAE。
令牌缓存
令牌缓存是 Azure 标识库提供的一项功能，它允许应用：
- 将令牌缓存在内存中 (默认) 或磁盘上， (选择加入) 。
- 提高复原能力和性能。
- 减少向 Azure AD 发出的获取访问令牌的请求数。
Azure 标识库提供内存中缓存和永久性磁盘缓存。 有关详细信息，请参阅 令牌缓存文档。
疑难解答
凭据在无法进行身份验证或无法执行身份验证时引发异常。 当凭据无法进行身份验证时，ClientAuthenticationException 将引发 。 异常具有 属性 message ，用于描述身份验证失败的原因。 当 由 ChainedTokenCredential引发此异常时，将停止凭据基础列表的链式执行。
如果凭据由于凭据在计算机上不可用所需的基础资源之一而无法执行身份验证，CredentialUnavailableException 则会引发 。 异常具有一个 message 属性，用于描述凭据无法执行身份验证的原因。 当此异常由 ChainedTokenCredential引发时，消息将从链中的每个凭据收集错误消息。
有关如何诊断各种故障方案的详细信息，请参阅 故障排除指南 。
后续步骤
此处列出的 Java 客户端库支持使用 TokenCredential 和 Azure 标识库进行身份验证。 可以了解有关其用法的详细信息，并 在此处提到的链接中找到有关使用这些客户端库的其他文档以及示例。
microsoft-graph-sdk 还支持使用 TokenCredential 和 Azure 标识库进行身份验证。
贡献
本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。
提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。
此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈