**本文档仅适用于 AWS CLI 版本 1。**
我们已宣布即将终止对 AWS CLI 版本 1 的支持。建议您迁移到 AWS CLI 版本 2。有关日期、其它详细信息以及如何迁移的信息，请参阅[公告](https://aws.amazon.com/blogs/developer/cli-v1-maintenance-mode-announcement/)。有关 AWS CLI 版本 2 的相关文档，请参阅[版本 2 用户指南](https://docs.aws.amazon.com/cli/latest/userguide/)。
# 在 AWS CLI 中使用 IAM 角色
[AWS Identity and Access Management（IAM）角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html)是一种授权工具，可让用户获得额外（或不同）的权限或者获取使用其他 AWS 账户执行操作的权限。
**Topics**
+ [先决条件](#cli-role-prereqs)
+ [IAM 角色的用法概览](#cli-role-overview)
+ [配置和使用角色](#cli-role-prepare)
+ [使用多重验证](#cli-configure-role-mfa)
+ [跨账户角色和外部 ID](#cli-configure-role-xaccount)
+ [指定角色会话名称以便于审核](#cli-configure-role-session-name)
+ [通过 Web 身份代入角色](#cli-configure-role-oidc)
+ [清除缓存的凭证](#cli-configure-role-cache)
## 先决条件
要运行 `iam` 命令，您需要安装和配置 AWS CLI。这包括设置已配置的配置文件，因为假设一个角色与其他凭证方法配对。有关更多信息，请参阅[安装、更新和卸载 AWS CLI](cli-chap-install.md)。
## IAM 角色的用法概览
通过在 `~/.aws/config` 文件中为某个 IAM 角色定义配置文件，您可以配置 AWS Command Line Interface (AWS CLI) 以使用该 IAM 角色。
以下示例显示了一个名为 `marketingadmin` 的角色配置文件。如果使用 `--profile marketingadmin`（或使用 [AWS\$1PROFILE 环境变量](cli-configure-envvars.md)指定它）运行命令，则 AWS CLI 使用在单独的配置文件 `user1` 中定义的凭证代入 Amazon Resource Name (ARN) 为 `arn:aws:iam::123456789012:role/marketingadminrole` 的角色。您可以运行分配给该角色的权限所允许的任何操作。
```
[profile marketingadmin]
role_arn = arn:aws:iam::123456789012:role/marketingadminrole
source_profile = user1
```
然后，您可以指定一个指向单独的命名配置文件的 `source_profile`，此配置文件包含用户凭证及使用该角色的权限。在上一个示例中，`marketingadmin` 配置文件使用 `user1` 配置文件中的凭证。当您指定某个 AWS CLI 命令将使用配置文件 `marketingadmin` 时，AWS CLI 会自动查找链接的 `user1` 配置文件的凭证，并使用它们为指定的 IAM 角色请求临时凭证。CLI 在后台使用 [sts:AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) 操作来完成该操作。然后，使用这些临时凭证来运行请求的 AWS CLI 命令。指定的角色必须附加有允许运行请求的 AWS CLI 命令的 IAM 权限策略。
要从 Amazon Elastic Compute Cloud (Amazon EC2) 实例或 Amazon Elastic Container Service (Amazon ECS) 容器中运行 AWS CLI 命令，您可以使用附加到实例配置文件或容器的 IAM 角色。如果未指定配置文件或未设置环境变量，则将直接使用该角色。这让您能够避免在实例上存储长时间生存的访问密钥。您也可以使用这些实例或容器角色仅获取其他角色的凭证。为此，请使用 `credential_source`（而不是 `source_profile`）指定如何查找凭证。`credential_source` 属性支持以下值：
+ `Environment` – 从环境变量检索源凭证。
+ `Ec2InstanceMetadata` – 使用附加到 Amazon EC2 实例配置文件的 IAM 角色。
+ `EcsContainer` – 使用附加到 Amazon ECS 容器的 IAM 角色。
以下示例显示通过引用 Amazon EC2 实例配置文件来使用同一个 `marketingadminrole` 角色。
```
[profile marketingadmin]
role_arn = arn:aws:iam::123456789012:role/marketingadminrole
credential_source = Ec2InstanceMetadata
```
当您调用角色时，您可以要求使用其他选项，例如，使用多重身份验证和外部 ID（供第三方公司用于访问其客户的资源）。也可以指定更易于在 AWS CloudTrail 日志中进行审核的唯一角色会话名称。
## 配置和使用角色
在使用指定 IAM 角色的配置文件运行命令时，AWS CLI 将使用源配置文件的凭证调用 AWS Security Token Service (AWS STS) 并为指定角色请求临时凭证。源配置文件中的用户必须具有为指定配置文件中的角色调用 `sts:assume-role` 的权限。该角色必须具有允许源配置文件中的用户使用角色的信任关系。检索角色的临时凭证然后使用临时凭证的过程通常称为*代入角色*。
您可以通过执行《AWS Identity and Access Management 用户指南》**中的[创建向 IAM 用户委派权限的角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)下的过程，在 IAM 中创建一个您希望用户代入的具有该权限的角色。如果该角色和源配置文件的 用户在同一个账户中，在配置角色的信任关系时，您可以输入自己的账户 ID。
在创建角色后，请修改信任关系以允许 用户担任该角色。
以下示例显示了一个可附加到角色的信任策略。该策略允许账户 123456789012 中的任何用户代入该角色，***前提***是该账户的管理员向该用户显式授予了 `sts:AssumeRole` 权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:root"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
信任策略不会实际授予权限。账户管理员必须通过附加具有适当权限的策略才能将代入角色的权限委派给各个用户。以下示例显示了一个可附加到用户的策略，该策略仅允许用户代入 `marketingadminrole` 角色。有关授予用户代入角色的访问权限的更多信息，请参阅 *IAM 用户指南*中的[向用户授予切换角色的权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html)。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::123456789012:role/marketingadminrole"
}
]
}
```
------
用户无需拥有附加权限，即可使用角色配置文件运行 AWS CLI 命令。相反，运行命令的权限来自附加到*角色* 的权限。您可以将权限策略附加到角色，以指定可以针对哪些 AWS 资源执行哪些操作。有关向角色附加权限（与向用户附加权限的操作相同）的更多信息，请参阅《IAM 用户指南》**中的[更改 IAM 用户的权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html)。
既然您已正确地配置角色配置文件、角色权限、角色信任关系和用户权限，那么就可以通过调用 `--profile` 选项在命令行中使用该角色了。例如，下面的内容使用附加到 `ls` 角色（由本主题开头的示例定义）的权限调用 Amazon S3 `marketingadmin` 命令。
```
$ aws s3 ls --profile marketingadmin
```
要对多个调用使用角色，您可以从命令行设置当前会话的 `AWS_PROFILE` 环境变量。定义该环境变量后，就不必对每个命令都指定 `--profile` 选项。
**Linux 或 macOS**
```
$ export AWS_PROFILE=marketingadmin
```
**Windows**
```
C:\> setx AWS_PROFILE marketingadmin
```
有关配置用户和角色的更多信息，请参阅《IAM 用户指南》**中的 [IAM 身份（用户、用户组和角色）](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html)和 [IAM 角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id-roles.html)。
## 使用多重验证
为了提高安全性，当用户尝试使用角色配置文件进行调用时，您可以要求用户提供从多重验证 (MFA) 设备（一种 U2F 设备）或移动应用程序生成的一次性密钥。
首先，您可以选择将与 IAM 角色有关的信任关系修改为需要 MFA。这可以防止任何人在未首先使用 MFA 进行身份验证的情况下使用该角色。有关示例，请参阅下面示例中的 `Condition` 行。此策略允许名为 `anika` 的用户代入策略所附加的角色，但前提是用户使用 MFA 进行身份验证。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": { "AWS": "arn:aws:iam::123456789012:user/anika" },
"Action": "sts:AssumeRole",
"Condition": { "Bool": { "aws:multifactorAuthPresent": true } }
}
]
}
```
------
其次，为角色配置文件添加一行，用来指定用户的 MFA 设备的 ARN。以下示例 `config` 文件条目显示两个角色配置文件，它们都使用用户 `anika` 的访问密钥来请求角色 `cli-role` 的临时凭证。用户 `anika` 有权代入角色，这是由角色的信任策略授予的。
```
[profile role-without-mfa]
region = us-west-2
role_arn= arn:aws:iam::128716708097:role/cli-role
source_profile=cli-user
[profile role-with-mfa]
region = us-west-2
role_arn= arn:aws:iam::128716708097:role/cli-role
source_profile = cli-user
mfa_serial = arn:aws:iam::128716708097:mfa/cli-user
[profile cli-user]
region = us-west-2
output = json
```
该 `mfa_serial` 设置可以采取如图所示的 ARN 或硬件 MFA 令牌的序列号。
第一个配置文件 `role-without-mfa` 不需要 MFA。但是，由于附加到角色的先前示例信任策略需要 MFA，因此使用此配置文件运行命令的任何尝试都将失败。
```
$ aws iam list-users --profile role-without-mfa
An error occurred (AccessDenied) when calling the AssumeRole operation: Access denied
```
第二个配置文件条目 `role-with-mfa` 标识要使用的 MFA 设备。当此用户尝试使用此配置文件运行 AWS CLI 命令时，AWS CLI 会提示用户输入 MFA 设备提供的一次性密码 (OTP)。如果 MFA 身份验证成功，此命令将执行所请求的操作。OTP 未显示在屏幕上。
```
$ aws iam list-users --profile role-with-mfa
Enter MFA code for arn:aws:iam::123456789012:mfa/cli-user:
{
"Users": [
{
...
```
## 跨账户角色和外部 ID
通过将角色配置为跨账户角色，您可以让 用户使用属于不同账户的角色。在创建角色期间，将角色类型设置为**其他AWS账户**（[如创建向 IAM 用户委派权限的角色中所述](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user.html)）。（可选）选择 **Require MFA (需要 MFA)**。**Require MFA (需要 MFA)** 将按照 [使用多重验证](#cli-configure-role-mfa) 中所述在信任关系中配置相应条件。
如果使用[外部 ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) 来加强控制可跨账户使用角色的人员，则还必须将 `external_id` 参数添加到角色配置文件。通常情况下，仅应在其他账户由公司或组织外部的人员控制时才使用该功能。
```
[profile crossaccountrole]
role_arn = arn:aws:iam::234567890123:role/SomeRole
source_profile = default
mfa_serial = arn:aws:iam::123456789012:mfa/saanvi
external_id = 123456
```
## 指定角色会话名称以便于审核
当许多人共享一个角色时，审核会变得比较困难。您希望将调用的每个操作与调用该操作的个人关联。但是，当个人使用角色时，个人代入角色是一项独立于调用操作的行为，您必须手动将这两者关联起来。
通过在用户代入角色时指定唯一的角色会话名称，您可以简化此过程。只需向指定某一角色的 `role_session_name` 文件中的每个命名配置文件添加 `config` 参数，即可实现这一点。`role_session_name` 值将传递给 `AssumeRole` 操作，并成为角色会话 ARN 的一部分。该值也包含在所有已记录操作的 AWS CloudTrail 日志中。
例如，您可以创建基于角色的配置文件，如下所示。
```
[profile namedsessionrole]
role_arn = arn:aws:iam::234567890123:role/SomeRole
source_profile = default
role_session_name = Session_Maria_Garcia
```
这会导致角色会话具有以下 ARN。
```
arn:aws:iam::234567890123:assumed-role/SomeRole/Session_Maria_Garcia
```
此外，所有 AWS CloudTrail 日志都在为每个操作捕获的信息中包含角色会话名称。
## 通过 Web 身份代入角色
您可以配置一个配置文件，以指示 AWS CLI 应使用 [Web 联合身份验证和 Open ID Connect (OIDC)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html) 代入角色。当您在配置文件中指定此选项时，AWS CLI 会自动为您发出相应的 AWS STS `AssumeRoleWithWebIdentity` 调用。
**注意**
当您指定使用 IAM 角色的配置文件时，AWS CLI 会发出相应的调用来检索临时凭证。这些凭证存储在 `~/.aws/cli/cache` 中。指定同一个配置文件的后续 AWS CLI 命令将使用缓存的临时凭证，直到它们过期。这时，AWS CLI 将自动刷新这些凭证。
要通过 Web 联合身份验证检索和使用临时凭证，您可以在共享配置文件中指定以下配置值。
[role\$1arn](#cli-configure-role)
指定要代入的角色的 ARN。
web\$1identity\$1token\$1file
指定一个文件的路径，该文件包含由身份提供者提供的 OAuth 2.0 访问令牌或 OpenID Connect ID 令牌。AWS CLI 加载此文件，并将其内容作为 `WebIdentityToken` 操作的 `AssumeRoleWithWebIdentity` 参数传递。
[role\$1session\$1name](#cli-configure-role-session-name)
指定应用于此代入角色会话的可选名称。
以下是使用 Web 身份配置文件配置代入角色所需的最少量配置的示例。
```
# In ~/.aws/config
[profile web-identity]
role_arn=arn:aws:iam:123456789012:role/RoleNameToAssume
web_identity_token_file=/path/to/a/token
```
您也可以使用[环境变量](cli-configure-envvars.md)提供此配置。
AWS\$1ROLE\$1ARN
要代入的角色的 ARN。
AWS\$1WEB\$1IDENTITY\$1TOKEN\$1FILE
Web 身份令牌文件的路径。
AWS\$1ROLE\$1SESSION\$1NAME
应用于此代入角色会话的名称。
**注意**
这些环境变量当前仅适用于通过 Web 身份提供程序代入角色。它们不适用于常规的代入角色提供程序配置。
## 清除缓存的凭证
当您使用一个角色时，AWS CLI 会在本地缓存临时凭证，直到这些凭证过期。当您下次尝试使用它们时，AWS CLI 会尝试代表您续订这些凭证。
如果您的角色的临时凭证[已吊销](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html)，它们不会自动续订，并且使用它们的尝试将失败。但是，您可以删除缓存以强制 AWS CLI 检索新凭证。
**Linux 或 macOS**
```
$ rm -r ~/.aws/cli/cache
```
**Windows**
```
C:\> del /s /q %UserProfile%\.aws\cli\cache
```