本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 在中使用凭证提供程序 AWS SDK for Java 2.x
证书提供商在中的角色 AWS SDK for Java 2.x 是为 SDK 的 AWS 服务 客户端获取和提供凭证。SDK 使用其获取的凭证对每个请求进行加密签名，从而向服务进行身份验证。凭证通常包含访问密钥（一个访问密钥 ID 和一个秘密访问密钥）。
当您使用临时证书（在设置 [SSO 令牌提供商配置或将运行时配置](https://docs.aws.amazon.com/sdkref/latest/guide/feature-sso-credentials.html#sso-token-config)为[担任 IAM (AWS Identity and Access Management) 角色时使用）](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#credOrSourceAssumeRole)时，会话令牌会添加到访问密钥中，从而提供对资源的限时访问权限。 AWS
本主题讨论了使 SDK 能够访问凭证的几种方式。
**Topics**
+ [交互式开发工作](credentials-temporary.md)
+ [默认凭证提供程序链](credentials-chain.md)
+ [凭证缓存](credential-caching.md)
+ [指定特定的凭证提供程序](credentials-providers.md)
+ [使用共享配置文件](credentials-profiles.md)
+ [使用外部进程](credentials-process.md)
+ [在代码中提供凭证](credentials-explicit.md)
+ [在 Amazon EC2 上读取 IAM 角色凭证](ec2-iam-roles.md)
# 使用访问交互式开发工作的凭证 AWS SDK for Java 2.x
为了提高安全性， AWS 建议您将适用于 Java 的 SDK 配置为[使用临时凭证](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-users-federation-idp)而不是长期证书。临时凭证由访问密钥（访问密钥 ID 与秘密访问密钥）和会话令牌组成。
您可以通过几种方法来使用临时凭证。您使用的方法以及您向 SDK 提供的配置都取决于您的使用案例。
当您使用 Java SDK 进行交互式开发工作时，我们建议您使用 AWS 控制台登录凭据。
## 使用控制台登录凭证
您可以使用现有的 AWS 管理控制台登录凭据以编程方式访问 AWS 服务。在基于浏览器的身份验证流程之后， AWS 生成可在本地开发工具（如 AWS CLI 和 SDK for Java 2.x）上使用的临时证书。
通过此流程，您可以使用在初始账户设置期间创建的根证书、IAM 用户或身份提供商提供的联合身份进行身份验证，然后 AWS CLI 自动为您管理临时证书。这种方法无需在本地存储长期凭证，从而增强了安全性。
运行 `aws login` 命令时，您可以从活动控制台会话中进行选择，也可以通过基于浏览器的身份验证流程登录，这将自动生成临时凭证。适用于 Java 的 SDK 2.x 将在最长 12 小时内自动刷新这些凭证。
**重要**
除了您在共享配置文件中设置的适用于所有项目的配置外，每个 Java 项目都需要在 Maven `pom.xml` 文件中具有以下依赖关系：
```
software.amazon.awssdk
signin
```
该`signin`依赖项提供了允许适用于 Java 2.x 的 SDK 访问和使用控制台登录凭据的代码。
有关先决条件、登录和注销的更多信息，请参阅 *AWS SDK 和工具参考*指南中的[使用控制台凭据登录进行 AWS 本地开发](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html)。
## Single-sign-on 方法
使用 Java SDK 进行交互式开发工作时，也可以使用单点登录方法。此方法需要以下设置：
+ [通过 IAM Identity Center 设置](get-started-auth.md#setup-auth)
+ [在 AWS 共享配置文件中配置配置文件](get-started-auth.md#setup-credentials)
+ 使用 AWS CLI 并[运行命令](get-started-auth.md#setup-login-sso)登录并创建活动会话
### IAM Identity Center 配置
当您将 SDK 配置为使用本指南的[设置概述](setup.md#setup-overview)中所述的 IAM Identity Center 单点登录访问时，SDK 会使用临时凭证。
SDK 使用 IAM Identity Center 访问令牌来访问用您的 `config` 文件中的 `sso_role_name` 设置配置的 IAM 角色。SDK 代入此 IAM 角色并检索用于签署 AWS 服务 请求的临时凭证。
有关软件开发工具包如何从配置中获取临时证书的更多详细信息，请参阅 AWS SDKs 和工具参考指南的[了解 IAM Identity Center 身份验证](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html)部分。
**重要**
除了在共享 `config` 文件中设置的适用于所有项目的配置外，每个 Java 项目还需要在 Maven `pom.xml` 文件中具有以下依赖项：
```
software.amazon.awssdk
sso
software.amazon.awssdk
ssooidc
```
`sso` 和 `ssooidc` 依赖项提供的代码使适用于 Java 的 SDK 2.x 能够访问临时凭证。
### 从 AWS 访问门户中检索临时证书
作为 IAM Identity Center 单点登录配置的替代方案，您可以复制和使用 AWS 访问门户中提供的临时证书。您可以在配置文件中使用临时凭证，也可以将其用作系统属性和环境变量的值。
**为临时凭证设置本地凭证文件**
1. [创建共享 credentials 文件](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html)
1. 在 credentials 文件中，粘贴以下占位符文本，直到粘贴有效的临时凭证为止。
```
[default]
aws_access_key_id=
aws_secret_access_key=
aws_session_token=
```
1. 保存该文件。该 `~/.aws/credentials` 文件现在应该存在于您的本地开发系统上。此文件包含 [[默认] 配置文件](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-profile)，如果未指定特定的命名配置文件，则适用于 Java 的 SDK 将使用该配置文件。
1. [登录 AWS 访问门户](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosignin.html)
1. 按照[手动刷新凭证](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html#how-to-get-temp-credentials)标题下的说明从 AWS 访问门户复制 IAM 角色证书。
1. 对于链接的说明中的步骤 2，为可授予访问权限以满足开发需求的 IAM 角色名称选择 `Access keys`。此角色的名称通常类似于**PowerUserAccess**或**开发人员**。
1. 在模态对话框中，选择您的操作系统，然后从**将配置文件添加到您的 AWS 凭证文件**复制内容。
1. 将复制的凭证粘贴到您的本地 `credentials` 文件中，并移除生成的配置文件名称。您的文件应类似于以下内容。
```
[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE
```
1. 保存 `credentials` 文件。
当适用于 Java 的 SDK 创建服务客户端时，它将访问这些临时凭证并将它们用于每个请求。在步骤 5a 中选择的 IAM 角色的设置决定了[临时凭证的有效时间](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtosessionduration.html)。最长持续时间为 12 小时。
在临时凭证过期后，重复步骤 4 到 7。
# 中的默认凭证提供者链 AWS SDK for Java 2.x
中的默认凭证提供程序链 AWS SDK for Java 2.x 会自动在预定义的位置序列中搜索 AWS 凭据，从而允许应用程序在 AWS 服务 不明确指定凭据来源的情况下进行身份验证。
默认凭证提供程序链由该[DefaultCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html)类实现。它会按顺序将凭证获取任务委托给其他凭证提供程序实现，这些实现会依次检查不同位置的配置。出现第一个可以找到所有必要配置元素的凭证提供程序后，链就会终止。
要使用默认凭证提供程序链来提供临时凭证，请创建服务客户端生成器，但不要指定凭证提供程序。以下代码段创建一个 `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 系统属性
+ 软件开发工具包使用[SystemPropertyCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/SystemPropertyCredentialsProvider.html)类从`aws.accessKeyId``aws.secretAccessKey`、和 `aws.sessionToken` Java 系统属性加载临时证书。
**注意**
有关如何设置 Java 系统属性的信息，请参阅官方 *Java Tutorials* 网站中的 [System Properties](https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html) 教程。
1. 环境变量
+ SDK 使用[EnvironmentVariableCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/EnvironmentVariableCredentialsProvider.html)类从`AWS_ACCESS_KEY_ID``AWS_SECRET_ACCESS_KEY`、和`AWS_SESSION_TOKEN`环境变量加载临时证书。
1. Web 身份令牌和 IAM 角色 ARN
+ SDK 使用该[WebIdentityTokenFileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/WebIdentityTokenFileCredentialsProvider.html)类通过使用 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 SDKs向其提供网络身份令牌，从而使应用程序能够获得临时证书。 AWS
1. 共享 `credentials` 和 `config` 文件
+ 软件开发工具包使用从共享`credentials`和文件中的`[default]`配置`config`文件中加载 IAM Identity Center 单点登录设置或临时证书。[ProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html)
《 AWS SDKs 和工具参考指南》[详细介绍了](https://docs.aws.amazon.com/sdkref/latest/guide/understanding-sso.html#idccredres)适用于 Java 的 SDK 如何与 IAM Identity Center 单点登录令牌配合使用，以获取开发工具包用来调用的 AWS 服务临时证书。
**注意**
`credentials`和`config`文件由各种 AWS SDKs 和工具共享。有关更多信息，请参阅[。 aws/credentials and .aws/config AWS SDKs 和《工具参考指南》中的文件](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html)。
+ 由于共享 `credentials` 和 `config` 文件中的配置文件包含许多不同的设置集，因此 `ProfileCredentialsProvider` 会委托给一系列其他提供程序，以便在 `[default]` 配置文件下查找设置：
+ **Web 身份令牌凭证**（类 `WebIdentityTokenCredentialsProvider`）：当配置文件包含 `role_arn` 和 `web_identity_token_file` 时。
+ **SSO 凭证**（类 `SsoCredentialsProvider`）：当配置文件包含与 SSO 相关的属性（例如 `sso_role_name`、`sso_account_id`）时。
+ **带有来源配置文件且基于角色的凭证**（类 `StsAssumeRoleCredentialsProvider`）：当配置文件包含 `role_arn` 和 `source_profile` 时。
+ **带有凭证来源且基于角色的凭证**（类 `StsAssumeRoleWithSourceCredentialsProvider`）：当配置文件包含 `role_arn` 和 `credential_source` 时。
+ 当 `credential_source = Environment` 时：使用 `SystemPropertyCredentialsProvider` 和 `EnvironmentVariableCredentialsProvider` 组成的链
+ 当 `credential_source = Ec2InstanceMetadata` 时：使用 `InstanceProfileCredentialsProvider`
+ 当 `credential_source = EcsContainer` 时：使用 `ContainerCredentialsProvider`
+ **控制台登录凭证**（类别`LoginCredentialsProvider`）：当配置文件包含时 `login_session`
+ **进程凭证**（类 `ProcessCredentialsProvider`）：当配置文件包含 `credential_process` 时。
+ **会话凭证**（类 `StaticSessionCredentialsProvider`）：当配置文件包含 `aws_access_key_id`、`aws_secret_access_key` 和 `aws_session_token` 时。
+ **基本凭证**（类 `StaticCredentialsProvider`）：当配置文件包含 `aws_access_key_id` 和 `aws_secret_access_key` 时。
1. Amazon ECS 容器凭证
+ SDK 使用[ContainerCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ContainerCredentialsProvider.html)类通过以下环境变量加载临时证书：
1. `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` 或 `AWS_CONTAINER_CREDENTIALS_FULL_URI`
1. `AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE` 或 `AWS_CONTAINER_AUTHORIZATION_TOKEN`
ECS 容器代理会自动设置指向 ECS 凭证端点的 `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` 环境变量。在不使用标准 ECS 凭证端点的特定场景中通常会设置其他环境变量。
1. Amazon EC2 实例 IAM 角色提供的证书
+ SDK 使用[InstanceProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/InstanceProfileCredentialsProvider.html)类从 Amazon EC2 元数据服务加载临时证书。
1. 如果 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();
```
这种方法为您提供了更多控制，同时仍然保留默认凭证链的便利性。
# 证书缓存在 AWS SDK for Java 2.x
AWS SDK for Java 2.x 实现凭据缓存以提高性能并减少对凭证源的调用。本节说明凭证缓存的工作原理以及如何为应用程序配置凭证缓存。
## 了解凭证提供程序缓存
适用于 Java 的 SDK 2.x 中的凭证提供程序使用不同的缓存策略：
+ **内部凭证缓存**：许多提供程序会缓存其检索到的凭证。
+ **自动刷新**：具有缓存凭证的提供程序会实施刷新机制。
### 具有内部凭证缓存的提供程序
即使创建了新实例，以下凭证提供程序也会在内部缓存凭证：
+ **实例配置文件凭证提供程序**：缓存来自 Amazon EC2 元数据服务的凭证。
+ **容器凭证提供程序**：缓存来自容器元数据端点的凭证。
+ **基于 STS 的提供商**：缓存来自 AWS Security Token Service (STS) 的临时证书。
+ **Web 身份令牌提供程序**：缓存从 Web 身份令牌获取的凭证。
+ **进程凭证提供程序**：缓存来自外部进程的凭证。
### 没有内部缓存的提供程序
以下提供程序不实施内部缓存：
+ **环境变量凭证提供程序**
+ **系统属性凭证提供程序**
+ **静态凭证提供程序**
## 配置凭证缓存
在构建凭证提供程序时，您可以自定义缓存行为：
### 过时时间
控制凭证何时被视为过时且需要刷新：
```
.staleTime(Duration.ofMinutes(2)) // Consider stale 2 minutes before expiration.
```
### 预取时间
确定在凭证过期之前何时开始刷新：
```
.prefetchTime(Duration.ofMinutes(10)) // Start refresh 10 minutes before expiration.
```
### 异步更新
启用后台凭证刷新：
```
.asyncCredentialUpdateEnabled(true) // Refresh credentials in background thread.
```
### 会话持续时间
对于基于 STS 的提供程序，控制临时凭证的有效时长：
```
.refreshRequest(r -> r.durationSeconds(3600)) // 1 hour session.
```
## 缓存凭证配置示例
举例来说，为凭证提供程序实现配置缓存时，您可能希望让 SDK 使用后台线程在凭证过期之前预取（提前检索）凭证。这样，您就可以避免因检索新凭证而导致调用阻塞。
以下示例创建了一个 `[StsAssumeRoleCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsAssumeRoleCredentialsProvider.html)`，通过在生成器上将 `[asyncCredentialUpdateEnabled](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#asyncCredentialUpdateEnabled(java.lang.Boolean))` 属性设置为 `true`，使用后台线程来预取凭证：
```
StsAssumeRoleCredentialsProvider provider = StsAssumeRoleCredentialsProvider.builder()
.refreshRequest(r -> r
.roleArn("arn:aws:iam::111122223333:role/example-role")
.roleSessionName("example-session")
.durationSeconds(3600)) // 1 hour session
.staleTime(Duration.ofMinutes(5)) // Consider stale 5 minutes before expiration
.prefetchTime(Duration.ofMinutes(10)) // Start refresh 10 minutes before expiration
.asyncCredentialUpdateEnabled(true) // Refresh in background
.build();
S3Client s3 = S3Client.builder()
.credentialsProvider(provider)
.build();
```
首次在上`s3Client`调用操作时，会向 AWS Security Token Service (STS) 发送一个`[AssumeRoleRequest](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/model/AssumeRoleRequest.html)`。STS 返回有效期为 15 分钟（900 秒）的临时凭证。`s3Client` 实例使用缓存的凭证，直到在 15 分钟到期之前需要刷新凭证为止。默认情况下，SDK 会在当前会话到期前 5 分钟到 1 分钟之间尝试为新会话检索新凭证。预取窗口可使用 `[prefetchTime](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#prefetchTime(java.time.Duration))` 和 `[staleTime](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/sts/auth/StsCredentialsProvider.BaseBuilder.html#staleTime(java.time.Duration))` 属性进行配置。
您可以用类似的方式配置以下基于会话的凭证提供程序：
+ `StsWebIdentityTokenFileCredentialsProvider`
+ `StsGetSessionTokenCredentialsProvider`
+ `StsGetFederationTokenCredentialsProvider`
+ `StsAssumeRoleWithWebIdentityCredentialsProvider`
+ `StsAssumeRoleWithSamlCredentialsProvider`
+ `StsAssumeRoleCredentialsProvider`
+ `DefaultCredentialsProvider`（当委托给使用会话的凭证提供程序时）
+ `ProcessCredentialsProvider`
+ `WebIdentityTokenFileCredentialsProvider`
+ `ContainerCredentialsProvider`
+ `InstanceProfileCredentialsProvider`
了解凭据缓存有助于您在使用时优化应用程序的性能和可靠性。 AWS 服务
# 在中指定特定的凭证提供商 AWS SDK for Java 2.x
虽然默认凭证提供程序链在许多情况下都很方便，但明确指定凭证提供程序可以让您更好地控制身份验证行为、性能和安全性。
您可能想要指定凭证提供程序的原因可能包括：
+ 默认提供程序链按顺序检查多个来源，这样会增加延迟：
```
// The default provider chain checks might check multiple sources until it finds
// sufficient configuration.
S3Client s3Client = S3Client.builder().build();
// You can specify exactly where to look.
S3Client optimizedClient = S3Client.builder()
.credentialsProvider(InstanceProfileCredentialsProvider.create())
.build();
```
+ 您需要使用非标准位置来访问凭证配置：
```
// Use configuration from a custom file location.
S3Client s3Client = S3Client.builder()
.credentialsProvider(ProfileCredentialsProvider.builder()
.profileFile(ProfileFile.builder()
.content(Paths.get("/custom/path/to/configuration/file"))
.type(ProfileFile.Type.CONFIGURATION) // Expects all non-default profiles to be prefixed with "profile".
.build())
.profileName("custom")
.build())
.build();
```
+ 为不同服务客户端使用不同的凭证。例如，如果您的应用程序需要访问多个 AWS 账户或对不同的服务使用不同的权限：
```
// S3 client using one set of credentials.
S3Client s3Client = S3Client.builder()
.credentialsProvider(ProfileCredentialsProvider.create("s3-readonly"))
.build();
// DynamoDB client using different credentials.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.credentialsProvider(ProfileCredentialsProvider.create("dynamodb-admin"))
.build();
```
+ 控制凭证刷新行为：
```
// Create a provider with custom refresh behavior.
StsAssumeRoleCredentialsProvider customRefreshProvider =
StsAssumeRoleCredentialsProvider.builder()
.refreshRequest(AssumeRoleRequest.builder()
.roleArn("arn:aws:iam::123456789012:role/my-role")
.roleSessionName("custom-session")
.build())
.stsClient(StsClient.create())
.asyncCredentialUpdateEnabled(true) // Use a background thread to prefetch credentials.
.build();
S3Client s3Client = S3Client.builder()
.credentialsProvider(customRefreshProvider)
.build();
```
# 在中使用 AWS 共享配置文件 AWS SDK for Java 2.x
使用共享 `config` 和 `credentials` 文件，您可以设置多个配置文件。这使您的应用程序能够使用多组凭证配置。前面提到的 `[default]` 配置文件。SDK 使用该[ProfileCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProfileCredentialsProvider.html)类从共享`credentials`文件中定义的配置文件加载设置。
以下代码片演示如何使用名为 `my_profile` 的配置文件中定义的设置来生成服务客户端。
```
Region region = Region.US_WEST_2;
DynamoDbClient ddb = DynamoDbClient.builder()
.region(region)
.credentialsProvider(ProfileCredentialsProvider.create("my_profile"))
.build();
```
## 将另一个配置文件设置为默认配置文件
要将 `[default]` 配置文件以外的另一个配置文件设置为应用程序的默认配置文件，请将 `AWS_PROFILE` 环境变量设置为自定义配置文件的名称。
要在 Linux、macOS 或 Unix 上设置这些变量，请使用 `export`：
```
export AWS_PROFILE="other_profile"
```
要在 Windows 上设置这些变量，请使用 `set`：
```
set AWS_PROFILE="other_profile"
```
或者，将 `aws.profile` Java 系统属性设置为配置文件的名称。
## 重新加载配置文件凭证
对于其生成器上具有 `profileFile()` 方法的任何凭证提供程序，您都可以将其配置为能够重新加载配置文件凭证。这些凭证配置文件类是：`ProfileCredentialsProvider`、`DefaultCredentialsProvider`、`InstanceProfileCredentialsProvider` 和 `ProfileTokenProvider.`
**注意**
配置文件凭证的重新加载仅适用于配置文件中的以下设置：`aws_access_key_id`、`aws_secret_access_key` 和 `aws_session_token`。
诸如 `region`、`sso_session`、`sso_account_id` 和 `source_profile` 之类的设置将被忽略。
要将支持的凭证提供程序配置为重新加载配置文件设置，请为 `profileFile()` 生成器方法提供一个 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html) 实例。以下代码示例演示的 `ProfileCredentialsProvider` 将从 `[default]` 配置文件重新加载凭证设置。
```
ProfileCredentialsProvider provider = ProfileCredentialsProvider
.builder()
.profileFile(ProfileFileSupplier.defaultSupplier())
.build();
// Set up a service client with the provider instance.
DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
.region(Region.US_EAST_1)
.credentialsProvider(provider)
.build();
/*
Before dynamoDbClient makes a request, it reloads the credentials settings
by calling provider.resolveCredentials().
*/
```
调用 `ProfileCredentialsProvider.resolveCredentials()` 时，适用于 Java 的 SDK 会重新加载设置。`ProfileFileSupplier.defaultSupplier()` 是 SDK 提供的 `ProfileFileSupplier` 的[几种便捷实现](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/profiles/ProfileFileSupplier.html)之一。如果您的用例需要，您可以提供自己的实现。
以下示例演示 `ProfileFileSupplier.reloadWhenModified()` 便利方法的使用。`reloadWhenModified()` 采用一个 `Path` 参数，这使您可以灵活地指定配置的源文件而不是标准 `~/.aws/credentials`（或 `config`）位置。
仅当 SDK 确定文件内容已修改时，才会在调用 `resolveCredentials()` 时重新加载设置。
```
Path credentialsFilePath = ...
ProfileCredentialsProvider provider = ProfileCredentialsProvider
.builder()
.profileFile(ProfileFileSupplier.reloadWhenModified(credentialsFilePath, ProfileFile.Type.CREDENTIALS))
.profileName("my-profile")
.build();
/*
A service client configured with the provider instance calls provider.resolveCredential()
before each request.
*/
```
`ProfileFileSupplier.aggregate()` 方法合并多个配置文件的内容。您可以决定是在每次调用 `resolveCredentials()` 时重新加载文件，还是在首次读取文件时固定其设置。
以下示例演示的 `DefaultCredentialsProvider` 将合并两个包含配置文件设置的文件的设置。每次调用 `resolveCredentials()` 并且设置发生更改时，SDK 都会重新加载 `credentialsFilePath` 变量所指向的文件中的设置。`profileFile` 对象的设置保持不变。
```
Path credentialsFilePath = ...;
ProfileFile profileFile = ...;
DefaultCredentialsProvider provider = DefaultCredentialsProvider
.builder()
.profileFile(ProfileFileSupplier.aggregate(
ProfileFileSupplier.reloadWhenModified(credentialsFilePath, ProfileFile.Type.CREDENTIALS),
ProfileFileSupplier.fixedProfileFile(profileFile)))
.profileName("my-profile")
.build();
/*
A service client configured with the provider instance calls provider.resolveCredential()
before each request.
*/
```
# 使用从外部进程加载凭证 AWS SDK for Java 2.x
**警告**
以下内容描述从外部进程获取临时凭证的方法。这可能很危险，因此请谨慎行事。我们建议：只要有可能，就尽量使用其他凭证提供程序。如果使用此选项，我们建议您确保使用操作系统的安全最佳实践，尽可能锁定 `config` 文件。
确保您的自定义凭证工具不会向中写入任何秘密信息`StdErr`。 SDKs 并且 AWS CLI 可以捕获和记录此类信息，从而有可能将其暴露给未经授权的用户。
使用适用于 Java 的 SDK 2.x，您可以从外部流程获取用于自定义用例的临时凭证。可通过两种方式配置此功能。
## 使用 `credential_process` 设置
如果您有提供临时凭证的方法，则可以通过将 `credential_process` 设置作为配置文件定义的一部分添加到 `config` 文件中来进行集成。您指定的值必须使用命令文件的完整路径。如果文件路径包含任何空格，则必须用引号将其括起来。
SDK 将完全按照给定的形式调用命令，然后从 `stdout` 中读取 JSON 数据。
以下示例演示如何对不带空格的文件路径和带空格的文件路径使用此设置。
------
#### [ Linux/macOS ]
**文件路径中没有空格**
```
[profile process-credential-profile]
credential_process = /path/to/credential/file/credential_file.sh --custom-command custom_parameter
```
**文件路径中有空格**
```
[profile process-credential-profile]
credential_process = "/path/with/space to/credential/file/credential_file.sh" --custom-command custom_parameter
```
------
#### [ Windows ]
**文件路径中没有空格**
```
[profile process-credential-profile]
credential_process = C:\Path\To\credentials.cmd --custom_command custom_parameter
```
**文件路径中有空格**
```
[profile process-credential-profile]
credential_process = "C:\Path\With Space To\credentials.cmd" --custom_command custom_parameter
```
------
以下代码段演示如何生成一个使用名为 `process-credential-profile` 的配置文件中定义的临时凭证的服务客户端。
```
Region region = Region.US_WEST_2;
S3Client s3Client = S3Client.builder()
.region(region)
.credentialsProvider(ProfileCredentialsProvider.create("process-credential-profile"))
.build();
```
有关使用外部进程作为临时证书来源的详细信息，请参阅《 AWS SDKs 和工具参考指南》中的 “[流程凭证” 部分](https://docs.aws.amazon.com/sdkref/latest/guide/feature-process-credentials.html)。
## 使用 `ProcessCredentialsProvider`
除了使用 `config` 文件中的设置之外，您还可以使用 SDK 的 `[ProcessCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/ProcessCredentialsProvider.html)` 通过 Java 加载临时凭证。
以下示例演示如何通过使用 `ProcessCredentialsProvider` 和配置使用临时凭证的服务客户端来指定外部流程的各种版本。
------
#### [ Linux/macOS ]
**文件路径中没有空格**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("/path/to/credentials.sh optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
**文件路径中有空格**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("/path\\ with\\ spaces\\ to/credentials.sh optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
------
#### [ Windows ]
**文件路径中没有空格**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("C:\\Path\\To\\credentials.exe optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
**文件路径中有空格**
```
ProcessCredentialsProvider credentials =
ProcessCredentialsProvider
.builder()
.command("\"C:\\Path\\With Spaces To\\credentials.exe\" optional_param1 optional_param2")
.build();
S3Client s3 = S3Client.builder()
.region(Region.US_WEST_2)
.credentialsProvider(credentials)
.build();
```
------
## 使用 IAM Roles Anywhere 进行身份验证
[IAM Roles An AWS 服务 ywher](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html) e 允许您获取在外部运行的工作负载的临时 AWS 证书 AWS。借助该服务，您可以从本地或其他云环境安全访问 AWS 资源。
在使用 IAM Roles Anywhere 对请求进行身份验证之前，您首先需要收集所需的信息并下载[凭证助手工具](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/credential-helper.html)。按照《IAM Roles Anywhere 用户指南》中的[入门](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html)说明进行操作，您可以创建必要的构件。
适用于 Java 的 SDK 没有专门的凭证提供程序来从 IAM Roles Anywhere 检索临时凭证，但您可以使用凭证助手工具以及其中一个选项[从外部进程检索凭证](#credentials-process)。
### 在配置文件中使用 `credential_process` 设置
共享 AWS 配置文件中的以下片段显示了使用该`credential_process`设置的名为`roles_anywhere`的配置文件：
```
[profile roles_anywhere]
credential_process = ./aws_signing_helper credential-process \
--certificate /path/to/certificate \
--private-key /path/to/private-key \
--trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \
--profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \
--role-arn arn:aws:iam::account:role/role-name-with-path
```
组装完所有构件后，您需要用您的值替换以红色显示的文本。设置中的第一个元素 `aws_signing_helper` 是凭证助手工具的可执行文件，`credential-process` 是命令。
当您将服务客户端配置为使用 `roles_anywhere` 配置文件时（如以下代码所示），SDK 会缓存临时凭证并在临时凭证到期之前更新凭证：
```
S3Client s3Client = S3Client.builder()
.credentialsProvider(ProfileCredentialsProvider.builder()
.profileName("roles_anywhere").build())
.build();
```
### 配置 `ProcessCredentialsProvider`
如下所示，您可以使用仅代码方法，使用 `ProcessCredentialsProvider`，而不是使用配置文件设置：
```
ProcessCredentialsProvider processCredentialsProvider = ProcessCredentialsProvider.builder()
.command("""
./aws_signing_helper credential-process \
--certificate /path/to/certificate \
--private-key /path/to/private-key \
--trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \
--profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \
--role-arn arn:aws:iam::account:role/role-name-with-path
""").build();
S3Client s3Client = S3Client.builder()
.credentialsProvider(processCredentialsProvider)
.build();
```
组装完所有构件后，用您的值替换以红色显示的文本。
# 在代码中使用提供凭据 AWS SDK for Java 2.x
如果默认凭证链、特定的或自定义的提供程序或提供程序链都不适用于您的应用程序，您可直接在代码中提供所需的临时凭证。这些证书可以是[上面描述](credentials-temporary.md#credentials-temporary-from-portal)[的 IAM 角色证书](https://docs.aws.amazon.com/singlesignon/latest/userguide/howtogetcredentials.html)，也可以是从 AWS Security Token Service (AWS STS) 中检索的临时证书。如果您使用检索临时证书 AWS STS，请将其提供给 AWS 服务 客户端，如以下代码示例所示。
1. 通过调用 `StsClient.assumeRole()` 来代入角色。
1. 创建一个[StaticCredentialsProvider](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/auth/credentials/StaticCredentialsProvider.html)对象并为其提供该`AwsSessionCredentials`对象。
1. 使用 `StaticCredentialsProvider` 配置服务客户端生成器并生成客户端。
以下示例使用返回的 IAM 代入角色的临时证书创建 Amazon S3 服务客户端。 AWS STS
```
// The AWS IAM Identity Center identity (user) who executes this method does not have permission to list buckets.
// The identity is configured in the [default] profile.
public static void assumeRole(String roleArn, String roleSessionName) {
// The IAM role represented by the 'roleArn' parameter can be assumed by identities in two different accounts
// and the role permits the user to only list buckets.
// The SDK's default credentials provider chain will find the single sign-on settings in the [default] profile.
// The identity configured with the [default] profile needs permission to call AssumeRole on the STS service.
try {
Credentials tempRoleCredentials;
try (StsClient stsClient = StsClient.create()) {
AssumeRoleRequest roleRequest = AssumeRoleRequest.builder()
.roleArn(roleArn)
.roleSessionName(roleSessionName)
.build();
AssumeRoleResponse roleResponse = stsClient.assumeRole(roleRequest);
tempRoleCredentials = roleResponse.credentials();
}
// Use the following temporary credential items for the S3 client.
String key = tempRoleCredentials.accessKeyId();
String secKey = tempRoleCredentials.secretAccessKey();
String secToken = tempRoleCredentials.sessionToken();
// List all buckets in the account associated with the assumed role
// by using the temporary credentials retrieved by invoking stsClient.assumeRole().
StaticCredentialsProvider staticCredentialsProvider = StaticCredentialsProvider.create(
AwsSessionCredentials.create(key, secKey, secToken));
try (S3Client s3 = S3Client.builder()
.credentialsProvider(staticCredentialsProvider)
.build()) {
List buckets = s3.listBuckets().buckets();
for (Bucket bucket : buckets) {
System.out.println("bucket name: " + bucket.name());
}
}
} catch (StsException | S3Exception e) {
logger.error(e.getMessage());
System.exit(1);
}
}
```
## 权限集
中定义的以下权限集 AWS IAM Identity Center 允许身份（用户）执行以下两个操作
1. Amazon Simple Storage Service 的 `GetObject` 操作。
1. AWS Security Token Service的 `AssumeRole` 操作。
如果不代入角色，则示例中显示的 `s3.listBuckets()` 方法将失败。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:GetObject",
"sts:AssumeRole"
],
"Resource": [
"*"
]
}
]
}
```
------
## 代入的角色
### 代入的角色权限策略
以下权限策略附加到上一个示例中代入的角色。该权限策略允许列出该角色所在账户中的所有存储桶。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:ListAllMyBuckets"
],
"Resource": [
"*"
]
}
]
}
```
------
### 代入的角色信任策略
以下信任策略附加到上一示例中代入的角色。该策略允许两个账户中的身份（用户）代入该角色。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:root",
"arn:aws:iam::555555555555:root"
]
},
"Action": "sts:AssumeRole",
"Condition": {}
}
]
}
```
------
# 使用适用于 Java 的 SDK 2.x 在 Amazon EC2 上读取 IAM 角色凭证
您可以使用 IAM 角色管理在 EC2 实例上运行并发出 AWS CLI 或 AWS API 请求的应用程序的临时证书。这优先于在 EC2 实例中存储访问密钥。要向 EC2 实例分配 AWS 角色并使其可供其所有应用程序使用，您需要创建附加到该实例的实例配置文件。实例配置文件包含角色，并使 EC2 实例上运行的程序能够获得临时凭证。有关更多信息，请参阅《IAM 用户指南》**中的[使用 IAM 角色向在 Amazon EC2 实例上运行的应用程序授予权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2.html)。
本主题提供有关如何将 Java 应用程序设置为在 EC2 实例上运行以及 AWS SDK for Java 2.x 如何允许获取 IAM 角色证书的信息。
## 从环境中获取 IAM 角色凭证
如果您的应用程序使用`create`方法（或`builder().build()`方法）创建 AWS 服务客户端，则 SDK for Java 将使用*默认凭证提供程序链*。默认凭证提供程序链会在执行环境中搜索配置元素，SDK 可以用其换取临时凭证。[中的默认凭证提供者链 AWS SDK for Java 2.x](credentials-chain.md)部分描述了完整的搜索流程。
只有当您的应用程序在 Amazon EC2 实例上运行时，默认提供程序链中的最后一步才可用。在此步骤中，SDK 使用 `InstanceProfileCredentialsProvider` 来读取 EC2 实例配置文件中定义的 IAM 角色。然后，SDK 会获取该 IAM 角色的临时凭证。
尽管这些凭证是临时凭证，而且最终会过期，但 `InstanceProfileCredentialsProvider` 会定期为您刷新它们，保证这些凭证可允许您继续访问 AWS。
## 以编程方式获取 IAM 角色凭证
作为最终会在 EC2 上使用 `InstanceProfileCredentialsProvider` 的默认凭证提供程序链的一种替代方案，您可以显式地将服务客户端配置为直接使用 `InstanceProfileCredentialsProvider`。以下代码段演示了这种方法。
```
S3Client s3 = S3Client.builder()
.credentialsProvider(InstanceProfileCredentialsProvider.create())
.build();
```
## 安全获取 IAM 角色凭证
默认情况下，EC2 实例运行 [IMDS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)（实例元数据服务），让 SDK 的 `InstanceProfileCredentialsProvider` 可以访问已配置的 IAM 角色等信息。默认情况下，EC2 实例运行 IMDS 的两个版本：
+ 实例元数据服务版本 1 (IMDSv1)-一种 request/response 方法
+ 实例元数据服务版本 2 (IMDSv2)-一种面向会话的方法
[IMDSv2 是一种比。更安全的方法](https://aws.amazon.com/blogs/security/defense-in-depth-open-firewalls-reverse-proxies-ssrf-vulnerabilities-ec2-instance-metadata-service/) IMDSv1。
默认情况下，Java SDK 首先 IMDSv2 尝试获取 IAM 角色，但如果失败，则会尝试 IMDSv1。但是，由于 IMDSv1 不太安全，因此 AWS 建议 IMDSv2 仅使用并禁用 SDK 进行尝试 IMDSv1。
要使用更安全的方法，请提供以下设置之一，禁用 SDK 的使用 IMDSv1 ，其值为`true`。
+ 环境变量：`AWS_EC2_METADATA_V1_DISABLED`
+ JVM 系统属性：aws.`disableEc2MetadataV1`
+ 共享配置文件设置：`ec2_metadata_v1_disabled`
IMDSv1 如果其中一个设置设置为`true`，则在初始 IMDSv2 调用失败时，SDK 不会通过使用来加载 IMDS 角色凭证。