AWS SDK for Java 2.x 中的默认凭证提供程序链 - AWS SDK for Java 2.x
凭证设置检索顺序在代码中使用 DefaultCredentialsProvider

AWS SDK for Java 2.x 中的默认凭证提供程序链

AWS SDK for Java 2.x 中的默认凭证提供程序链会自动在预定义的位置序列中搜索 AWS 凭证，从而让应用程序可以在不明确指定凭证来源的情况下向 AWS 服务进行身份验证。

默认凭证提供程序链通过 DefaultCredentialsProvider 类实现。它会按顺序将凭证获取任务委托给其他凭证提供程序实现，这些实现会依次检查不同位置的配置。出现第一个可以找到所有必要配置元素的凭证提供程序后，链就会终止。

要使用默认凭证提供程序链来提供临时凭证，请创建服务客户端生成器，但不要指定凭证提供程序。以下代码段创建一个 DynamoDbClient，使用默认凭证提供程序链来查找和检索配置设置。

// Any external Region configuration is overridden.
// The SDK uses the default credentials provider chain because no specific credentials provider is specified.
Region region = Region.US_WEST_2;
DynamoDbClient ddb = 
    DynamoDbClient.builder()
                  .region(region)
                  .build();

凭证设置检索顺序

适用于 Java 的 SDK 2.x 的默认凭证提供程序链使用预定义的顺序在您的环境中搜索配置。

  1. Java 系统属性

    • SDK 使用 SystemPropertyCredentialsProvider 类从 aws.accessKeyId、aws.secretAccessKey 和 aws.sessionToken Java 系统属性加载临时凭证。

      注意

      有关如何设置 Java 系统属性的信息，请参阅官方 Java Tutorials 网站中的 System Properties 教程。

  2. 环境变量

  3. Web 身份令牌和 IAM 角色 ARN

    • SDK 使用 WebIdentityTokenFileCredentialsProvider 类，通过使用 Web 身份令牌代入角色来加载凭证。

    • 凭证提供程序会查找以下环境变量或 JVM 系统属性：

      • AWS_WEB_IDENTITY_TOKEN_FILE or aws.webIdentityTokenFile

      • AWS_ROLE_ARN 或 aws.roleArn

      • AWS_ROLE_SESSION_NAME 或 aws.roleSessionName（可选）

    • SDK 获取值后，它会调用 AWS Security Token Service（STS）并使用返回的临时凭证来对请求进行签名。

    • 诸如 Amazon Elastic Kubernetes Service（EKS）之类的运行时环境会自动向 AWS SDK 提供 Web 身份令牌，从而使应用程序能够获取临时 AWS 凭证。

  4. 共享 credentials 和 config 文件

    • SDK 使用 ProfileCredentialsProvider 从共享 credentials 和 config 文件中的 [default] 配置文件加载 IAM Identity Center 单点登录设置或临时凭证。

      《AWS SDKs and Tools Reference Guide》详细介绍了适用于 Java 的 SDK 如何与 IAM Identity Center 单点登录令牌结合使用，以获取 SDK 用来调用 AWS 服务 的临时凭证。

      注意

      credentials 和 config 文件由各种 AWS SDK 和工具共享。有关更多信息，请参阅《AWS SDKs and Tools Reference Guide》中的 .aws/credentials 和 .aws/config 文件。

    • 由于共享 credentials 和 config 文件中的配置文件包含许多不同的设置集，因此 ProfileCredentialsProvider 会委托给一系列其他提供程序，以便在 [default] 配置文件下查找设置：

      • 基本凭证（类 StaticCredentialsProvider）：当配置文件包含 aws_access_key_id 和 aws_secret_access_key 时。

      • 会话凭证（类 StaticSessionCredentialsProvider）：当配置文件包含 aws_access_key_id、aws_secret_access_key 和 aws_session_token 时。

      • 进程凭证（类 ProcessCredentialsProvider）：当配置文件包含 credential_process 时。

      • SSO 凭证（类 SsoCredentialsProvider）：当配置文件包含与 SSO 相关的属性（例如 sso_role_name、sso_account_id）时。

      • Web 身份令牌凭证（类 WebIdentityTokenCredentialsProvider）：当配置文件包含 role_arn 和 web_identity_token_file 时。

      • 带有来源配置文件且基于角色的凭证（类 StsAssumeRoleCredentialsProvider）：当配置文件包含 role_arn 和 source_profile 时。

      • 带有凭证来源且基于角色的凭证（类 StsAssumeRoleWithSourceCredentialsProvider）：当配置文件包含 role_arn 和 credential_source 时。

        • 当 credential_source = Environment 时：使用 SystemPropertyCredentialsProvider 和 EnvironmentVariableCredentialsProvider 组成的链。

        • 当 credential_source = Ec2InstanceMetadata 时：使用 InstanceProfileCredentialsProvider

        • 当 credential_source = EcsContainer 时：使用 ContainerCredentialsProvider

  5. Amazon ECS 容器凭证

    • SDK 使用 ContainerCredentialsProvider 类，使用以下环境变量来加载临时凭证。

      1. AWS_CONTAINER_CREDENTIALS_RELATIVE_URI 或 AWS_CONTAINER_CREDENTIALS_FULL_URI

      2. AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE 或 AWS_CONTAINER_AUTHORIZATION_TOKEN

    ECS 容器代理会自动设置指向 ECS 凭证端点的 AWS_CONTAINER_CREDENTIALS_RELATIVE_URI 环境变量。在不使用标准 ECS 凭证端点的特定场景中通常会设置其他环境变量。

  6. Amazon EC2 实例 IAM 角色提供的凭证

  7. 如果 SDK 无法通过上面列出的所有步骤找到必要的配置设置，则会抛出异常，输出类似于以下内容：

    software.amazon.awssdk.core.exception.SdkClientException: Unable to load credentials from any of the providers 
in the chain AwsCredentialsProviderChain(credentialsProviders=[SystemPropertyCredentialsProvider(), 
EnvironmentVariableCredentialsProvider(), WebIdentityTokenCredentialsProvider(), ProfileCredentialsProvider(), 
ContainerCredentialsProvider(), InstanceProfileCredentialsProvider()])

在代码中使用 DefaultCredentialsProvider

您可以在代码中显式使用默认凭证提供程序链。因为 SDK 默认使用 DefaultCredentialsProvider，这在功能上等同于您根本不指定凭证提供程序。但显式使用默认凭证提供程序链可以使代码更具可读性，并且能够自我说明。这清楚地表明了您打算使用默认凭证链。

import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;

public class ExplicitDefaultCredentialsExample {
    public static void main(String[] args) {
        // Explicitly create the DefaultCredentialsProvider.
        DefaultCredentialsProvider defaultCredentialsProvider = DefaultCredentialsProvider
                                                                    .builder().build();

        // Use it with any service client.
        S3Client s3Client = S3Client.builder()
            .region(Region.US_WEST_2)
            .credentialsProvider(defaultCredentialsProvider)
            .build();

        // Now you can use the client with the default credentials chain.
        s3Client.listBuckets();
    }
}

在构建默认凭证提供程序时，您可以提供更多配置：

DefaultCredentialsProvider customizedProvider = DefaultCredentialsProvider.builder()
    .profileName("custom-profile")  // Use a specific profile if the chain gets to the `ProfileCredentialsProvider` stage.
    .asyncCredentialUpdateEnabled(true)  // Enable async credential updates.
    .build();

这种方法为您提供了更多控制，同时仍然保留默认凭证链的便利性。