本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 代入角色凭证提供者
**注意**
如需了解设置页面布局或解释后面的 Support b **y AWS SDKs 和 tools** 表格的帮助，请参阅[了解本指南的设置页面](settings-reference.md#settingsPages)。
假设角色涉及使用一组临时安全凭证来访问您原本无法访问的 AWS 资源。这些临时凭证由访问密钥 ID、秘密访问密钥和安全令牌组成。
要设置您的 SDK 或工具来代入角色，必须先创建或标识要代入的特定*角色*。IAM 角色由角色 Amazon 资源名称（[ARN](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference-arns.html)）进行唯一标识。角色与另一个实体建立信任关系。使用该角色的可信实体可能是另一个 AWS 服务、Web 身份提供商 AWS 账户、OIDC 或 SAML 联合体。
标识 IAM 角色后，如果您受到该角色的信任，则可以将您的 SDK 或工具配置为使用该角色授予的权限。要执行此操作，请使用以下设置。
有关开始使用这些设置的指导，请参阅本指南中的 [假设一个拥有身份验证 AWS 凭证 AWS SDKs 和工具的角色](access-assume-role.md)。
## 代入角色凭证提供者设置
使用以下方法配置此功能：
**`credential_source`-共享 AWS `config`文件设置**
在 Amazon EC2 实例或 Amazon Elastic Container Service 容器中使用，指定 SDK 或工具在何处可以查找授权用于代入通过 `role_arn` 参数指定的角色的凭证。
**默认值：** 无
**有效值：**
+ **环境** – 指定 SDK 或工具从环境变量 [`AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY`](feature-static-credentials.md) 检索源凭证。
+ Ec@@ **2 InstanceMetadata** — 指定软件开发工具包或工具将使用[附加到 EC2 实例配置文件的 IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html)来获取源证书。
+ **EcsContainer**— 指定软件开发工具包或工具将使用[附加到 Amazon ECS 容器的 IAM 角色或附加到 Ama](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html) [zon EKS 容器](https://docs.aws.amazon.com/eks/latest/userguide/security-iam-service-with-iam.html)的 IAM 角色来获取源证书。
不能在同一配置文件中同时指定 `credential_source` 和 `source_profile`。
在 `config` 文件中设置此项以表明凭证应来自 Amazon EC2 的示例：
```
credential_source = Ec2InstanceMetadata
role_arn = arn:aws:iam::123456789012:role/my-role-name
```
**`duration_seconds`-共享 AWS `config`文件设置**
指定角色会话的最大持续时间（以秒为单位）。
仅当配置文件指定代入角色时，此设置才适用。
**默认值：** 3600 秒 (1 小时)
**有效值：**该值的范围在 900 秒（15 分钟）到角色配置的最大会话持续时间（43200 秒或 12 小时）之间。有关更多信息，请参阅 *IAM 用户指南*中的 [查看角色的最大会话持续时间设置](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use.html#id_roles_use_view-role-max-session)。
在 `config` 文件中设置此项的示例：
```
duration_seconds = 43200
```
**`external_id`-共享 AWS `config`文件设置**
指定第三方用于在其客户账户中代入角色的唯一标识符。
仅当配置文件指定代入角色且该角色的信任策略需要 `ExternalId` 值时，此设置才适用。该值映射到配置文件指定角色时传递给 `AssumeRole` 操作的 `ExternalId` 参数。
**默认值：**无。
**有效值：**请参阅 *IAM 用户指南*中的[如何在向第三方授予对您的 AWS 资源的访问权限时使用外部 ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)。
在 `config` 文件中设置此项的示例：
```
external_id = unique_value_assigned_by_3rd_party
```
**`mfa_serial`-共享 AWS `config`文件设置**
指定用户在代入角色时必须使用的多重身份验证（MFA）设备的标识或序列号。
代入角色时，如果该角色的信任策略包含需要 MFA 身份验证的条件，则此项为必需项。有关 MFA 的更多信息，请参阅《IAM 用户指南》中的 [IAM 中的AWS 多重身份验证](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa.html)**。
**默认值：**无。
**有效值：** 该值可以是硬件设备（例如 `GAHT12345678`）的序列号，也可以是虚拟 MFA 设备的 Amazon 资源名称（ARN）。ARN 的格式为 `arn:aws:iam::account-id:mfa/mfa-device-name`
在 `config` 文件中设置此项的示例：
此示例假设已为该账户创建并为某个用户启用了一个名为 `MyMFADevice` 的虚拟 MFA 设备。
```
mfa_serial = arn:aws:iam::123456789012:mfa/MyMFADevice
```
**`role_arn`-共享 AWS `config`文件设置`AWS_ROLE_ARN` - 环境变量`aws.roleArn`-JVM 系统属性：仅限 Java/Kotlin **
指定要用于执行使用此配置文件请求操作的 IAM 角色的 Amazon 资源名称（ARN）。
**默认值：**无。
**有效值：**该值必须是 IAM 角色的 ARN，格式如下：`arn:aws:iam::account-id:role/role-name`
此外，您还必须指定以下设置**之一**：
+ `source_profile` - 标识另一个配置文件，用于查找具有在此配置文件中代入该角色的权限的凭证。
+ `credential_source` - 使用由当前环境变量标识的凭证或附加到 Amazon EC2 实例配置文件或 Amazon ECS 容器实例的凭证。
+ `web_identity_token_file` - 为已在移动或 Web 应用程序中进行身份验证的用户使用公共身份提供者或任何 OpenID Connect（OIDC）兼容身份提供者。
**`role_session_name`-共享 AWS `config`文件设置`AWS_ROLE_SESSION_NAME` - 环境变量`aws.roleSessionName`-JVM 系统属性：仅限 Java/Kotlin **
指定要附加到角色会话的名称。此名称显示在与此会话关联的条目的 AWS CloudTrail 日志中，该会话可能在审核时有用。有关详细信息，请参阅《[CloudTrail用户指南》中的 “*AWS CloudTrail 用户*身份” 元素](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)。
**默认值：**可选参数。如果未提供此值，只要配置文件代入角色，则将自动生成会话名称。
**有效值：**当 AWS CLI 或 AWS API 代表您调用`AssumeRole`操作（或操作等`AssumeRoleWithWebIdentity`操作）时，为`RoleSessionName`参数提供。该值成为您可以查询的代入角色用户 Amazon 资源名称 (ARN) 的一部分，并作为该配置文件调用的操作的 CloudTrail 日志条目的一部分显示。
`arn:aws:sts::123456789012:assumed-role/my-role-name/my-role_session_name`.
在 `config` 文件中设置此项的示例：
```
role_session_name = my-role-session-name
```
**`source_profile`-共享 AWS `config`文件设置**
指定其他配置文件，其凭证用于代入由原始配置文件中的 `role_arn` 设置指定的角色。要了解如何在共享`credentials`文件 AWS `config`和文件中使用配置文件，请参阅[共享 `config` 文件和 `credentials` 文件](file-format.md)。
如果您指定的配置文件也是代入角色配置文件，则将按顺序代入每个角色以完全解析凭证。当 SDK 遇到带有凭证的配置文件时，此链将会停止。角色链将您的 AWS CLI 或 AWS API 角色会话限制为最长一小时，并且无法延长。有关更多信息，请参阅 *IAM 用户指南*中的[角色术语和概念](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html)。
**默认值：**无。
**有效值：**由 `config` 和 `credentials` 文件中定义的配置文件的名称组成的文本字符串。还必须在当前配置文件中指定 `role_arn` 的值。
不能在同一配置文件中同时指定 `credential_source` 和 `source_profile`。
在配置文件中设置此项的示例：
```
[profile A]
source_profile = B
role_arn = arn:aws:iam::123456789012:role/RoleA
role_session_name = ProfileARoleSession
[profile B]
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_ID
```
在上例中，`A` 配置文件告诉 SDK 或工具自动查找关联的 `B` 配置文件的凭证。在此例中，`B` 配置文件使用 [使用 IAM Anywhere 角色进行身份验证 AWS SDKs 和工具](access-rolesanywhere.md) 提供的凭证助手来获取 AWS SDK 的凭证。然后，代码会使用这些临时凭证来访问 AWS 资源。指定的角色必须附加允许运行所请求代码的 IAM 权限策略，例如命令 AWS 服务、或 API 方法。配置文件执行的每项操作的 CloudTrail 日志中`A`都包含角色会话名称。
对于第二个角色链示例，如果您在 Amazon Elastic Compute Cloud 实例上有一个应用程序，并且想让该应用程序代入其他角色，则可以使用以下配置。
```
[profile A]
source_profile = B
role_arn = arn:aws:iam::123456789012:role/RoleA
role_session_name = ProfileARoleSession
[profile B]
credential_source=Ec2InstanceMetadata
```
配置文件 `A` 将使用来自 Amazon EC2 实例的凭证来代入指定角色，并且会自动续订凭证。
**`web_identity_token_file`-共享 AWS `config`文件设置`AWS_WEB_IDENTITY_TOKEN_FILE` - 环境变量`aws.webIdentityTokenFile`-JVM 系统属性：仅限 Java/Kotlin **
指定文件路径，该文件包含来自[支持的 OAuth 2.0 提供商或 [OpenID Connect ID 身份](https://openid.net/developers/certified/)提供商](https://wikipedia.org/wiki/List_of_OAuth_providers)的访问令牌。
此设置允许使用 Web 身份联合验证提供者（例如 [Google](https://developers.google.com/identity/protocols/OAuth2)、[Facebook](https://developers.facebook.com/docs/facebook-login/overview) 和 [Amazon](https://login.amazon.com/) 等）进行身份验证。SDK 或开发人员工具加载此文件的内容，并在代表您调用 `AssumeRoleWithWebIdentity` 操作时将其作为 `WebIdentityToken` 参数传递。
**默认值：**无。
**有效值：**此值必须是路径和文件名。该文件必须包含身份提供商向您提供的 OAuth 2.0 访问令牌或 OpenID Connect 令牌。相对路径被视为相对于进程工作目录的相对路径。
## Support AWS SDKs by 和工具
以下内容 SDKs 支持本主题中描述的功能和设置。所有部分例外情况均已注明。 适用于 Java 的 AWS SDK 和 适用于 Kotlin 的 AWS SDK 唯一支持任何 JVM 系统属性设置。
| SDK | 支持 | 备注或更多信息 |
| --- | --- | --- |
| [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/) v2 | 是 | |
| [适用于 C\$1\$1 的 SDK](https://docs.aws.amazon.com/sdk-for-cpp/latest/developer-guide/) | 部分 | credential\$1source不支持。duration\$1seconds不支持。mfa\$1serial不支持。 |
| [适用于 Go V2 (1.x) 的 SDK](https://docs.aws.amazon.com/sdk-for-go/v2/developer-guide/) | 是 | |
| [适用于 Go 1.x（V1）的 SDK](https://docs.aws.amazon.com/sdk-for-go/latest/developer-guide/) | 是 | 要使用共享 config 文件设置，必须开启从配置文件加载的功能；请参阅[会话](https://docs.aws.amazon.com/sdk-for-go/api/aws/session/)。 |
| [适用于 Java 2.x 的 SDK](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/) | 部分 | 不支持 mfa\$1serial。不支持 duration\$1seconds。 |
| [适用于 Java 1.x 的 SDK](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/) | 部分 | 不支持 credential\$1source。不支持 mfa\$1serial。不支持 JVM 系统属性。 |
| [适用于 JavaScript 3.x 的软件开发工具包](https://docs.aws.amazon.com/sdk-for-javascript/latest/developer-guide/) | 是 | |
| [适用于 JavaScript 2.x 的 SDK](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/) | 部分 | credential\$1source 不支持。 |
| [适用于 Kotlin 的 SDK](https://docs.aws.amazon.com/sdk-for-kotlin/latest/developer-guide/) | 是 | |
| [适用于.NET 4.x 的 SDK](https://docs.aws.amazon.com/sdk-for-net/latest/developer-guide/) | 是 | |
| [适用于 .NET 3.x 的 SDK](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/) | 是 | |
| [适用于 PHP 3.x 的 SDK](https://docs.aws.amazon.com/sdk-for-php/latest/developer-guide/) | 是 | |
| [适用于 Python (Boto3) 的 SDK](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) | 是 | |
| [适用于 Ruby 3.x 的 SDK](https://docs.aws.amazon.com/sdk-for-ruby/latest/developer-guide/) | 是 | |
| [适用于 Rust 的 SDK](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/) | 是 | |
| [适用于 Swift 的 SDK](https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/) | 是 | |
| [适用于 PowerShell V5 的工具](https://docs.aws.amazon.com/powershell/latest/userguide/) | 是 | |
| [适用于 PowerShell V4 的工具](https://docs.aws.amazon.com/powershell/v4/userguide/) | 是 | |