# Using an IAM role in the Amazon CLI
An [Amazon Identity and Access Management (IAM) role](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles.html) is an authorization tool that lets a user gain additional (or different) permissions, or get permissions to perform actions in a different Amazon account.
**Topics**
+ [
## Prerequisites
](#cli-role-prereqs)
+ [
## Overview of using IAM roles
](#cli-role-overview)
+ [
## Configuring and using a role
](#cli-role-prepare)
+ [
## Using multi-factor authentication
](#cli-configure-role-mfa)
+ [
## Cross-account roles and external ID
](#cli-configure-role-xaccount)
+ [
## Specifying a role session name for easier auditing
](#cli-configure-role-session-name)
+ [
## Assume role with web identity
](#cli-configure-role-oidc)
+ [
## Clearing cached credentials
](#cli-configure-role-cache)
## Prerequisites
To run the `iam` commands, you need to install and configure the Amazon CLI. This includes setting up a configured profile, as assuming a role is paired with another credential method. For more information, see [Installing or updating to the latest version of the Amazon CLI](getting-started-install.md).
## Overview of using IAM roles
You can configure the Amazon Command Line Interface (Amazon CLI) to use an IAM role by defining a profile for the role in the `~/.aws/config` file.
The following example shows a role profile named `marketingadmin`. If you run commands with `--profile marketingadmin` (or specify it with the [AWS\$1PROFILE environment variable](cli-configure-envvars.md)), the Amazon CLI uses the credentials defined in a separate profile `user1` to assume the role with the Amazon Resource Name (ARN) `arn:aws-cn:iam::123456789012:role/marketingadminrole`. You can run any operations that are allowed by the permissions assigned to that role.
```
[profile marketingadmin]
role_arn = arn:aws-cn:iam::123456789012:role/marketingadminrole
source_profile = user1
```
You can then specify a `source_profile` that points to a separate named profile that contains user credentials with permission to use the role. In the previous example, the `marketingadmin` profile uses the credentials in the `user1` profile. When you specify that an Amazon CLI command is to use the profile `marketingadmin`, the Amazon CLI automatically looks up the credentials for the linked `user1` profile and uses them to request temporary credentials for the specified IAM role. The CLI uses the [sts:AssumeRole](https://docs.amazonaws.cn/STS/latest/APIReference/API_AssumeRole.html) operation in the background to accomplish this. Those temporary credentials are then used to run the requested Amazon CLI command. The specified role must have attached IAM permission policies that allow the requested Amazon CLI command to run.
To run a Amazon CLI command from within an Amazon Elastic Compute Cloud (Amazon EC2) instance or an Amazon Elastic Container Service (Amazon ECS) container, you can use an IAM role attached to the instance profile or the container. If you specify no profile or set no environment variables, that role is used directly. This enables you to avoid storing long-lived access keys on your instances. You can also use those instance or container roles only to get credentials for another role. To do this, you use `credential_source` (instead of `source_profile`) to specify how to find the credentials. The `credential_source` attribute supports the following values:
+ `Environment` – Retrieves the source credentials from environment variables.
+ `Ec2InstanceMetadata` – Uses the IAM role attached to the Amazon EC2 instance profile.
+ `EcsContainer` – Uses the IAM role attached to the Amazon ECS container.
The following example shows the same `marketingadminrole` role used by referencing an Amazon EC2 instance profile.
```
[profile marketingadmin]
role_arn = arn:aws-cn:iam::123456789012:role/marketingadminrole
credential_source = Ec2InstanceMetadata
```
When you invoke a role, you have additional options that you can require, such as the use of multi-factor authentication and an External ID (used by third-party companies to access their clients' resources). You can also specify unique role session names that can be more easily audited in Amazon CloudTrail logs.
## Configuring and using a role
When you run commands using a profile that specifies an IAM role, the Amazon CLI uses the source profile's credentials to call Amazon Security Token Service (Amazon STS) and request temporary credentials for the specified role. The user in the source profile must have permission to call `sts:assume-role` for the role in the specified profile. The role must have a trust relationship that allows the user in the source profile to use the role. The process of retrieving and then using temporary credentials for a role is often referred to as *assuming the role*.
You can create a role in IAM with the permissions that you want users to assume by following the procedure under [Creating a Role to Delegate Permissions to an IAM user](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_create_for-user.html) in the *Amazon Identity and Access Management User Guide*. If the role and the source profile's user are in the same account, you can enter your own account ID when configuring the role's trust relationship.
After creating the role, modify the trust relationship to allow the user to assume it.
The following example shows a trust policy that you could attach to a role. This policy allows the role to be assumed by any user in the account 123456789012, ***if*** the administrator of that account explicitly grants the `sts:AssumeRole` permission to the user.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws-cn:iam::123456789012:root"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
The trust policy doesn't actually grant permissions. The administrator of the account must delegate the permission to assume the role to individual users by attaching a policy with the appropriate permissions. The following example shows a policy that you can attach to a user that allows the user to assume only the `marketingadminrole` role. For more information about granting a user access to assume a role, see [Granting a User Permission to Switch Roles](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_use_permissions-to-switch.html) in the *IAM User Guide*.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws-cn:iam::123456789012:role/marketingadminrole"
}
]
}
```
------
The user doesn't need to have additional permissions to run the Amazon CLI commands using the role profile. Instead, the permissions to run the command come from those attached to the *role*. You attach permission policies to the role to specify which actions can be performed against which Amazon resources. For more information about attaching permissions to a role (which works identically to a user), see [Changing Permissions for an IAM user](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_users_change-permissions.html) in the *IAM User Guide*.
Now that you have the role profile, role permissions, role trust relationship, and user permissions correctly configured, you can use the role at the command line by invoking the `--profile` option. For example, the following calls the Amazon S3 `ls` command using the permissions attached to the `marketingadmin` role as defined by the example at the beginning of this topic.
```
$ aws s3 ls --profile marketingadmin
```
To use the role for several calls, you can set the `AWS_PROFILE` environment variable for the current session from the command line. While that environment variable is defined, you don't have to specify the `--profile` option on each command.
**Linux or macOS**
```
$ export AWS_PROFILE=marketingadmin
```
**Windows**
```
C:\> setx AWS_PROFILE marketingadmin
```
For more information about configuring users and roles, see [IAM Identities (users, user groups, and roles)](https://docs.amazonaws.cn/IAM/latest/UserGuide/id.html) and [IAM roles](https://docs.amazonaws.cn/IAM/latest/UserGuide/id-roles.html) in the *IAM User Guide*.
## Using multi-factor authentication
For additional security, you can require that users provide a one-time key generated from a multi-factor authentication (MFA) device, a U2F device, or mobile app when they attempt to make a call using the role profile.
First, you can choose to modify the trust relationship on the IAM role to require MFA. This prevents anyone from using the role without first authenticating by using MFA. For an example, see the `Condition` line in the following example. This policy allows the user named `anika` to assume the role the policy is attached to, but only if they authenticate by using MFA.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "",
"Effect": "Allow",
"Principal": { "AWS": "arn:aws-cn:iam::123456789012:user/anika" },
"Action": "sts:AssumeRole",
"Condition": { "Bool": { "aws:multifactorAuthPresent": true } }
}
]
}
```
------
Next, add a line to the role profile that specifies the ARN of the user's MFA device. The following sample `config` file entries show two role profiles that both use the access keys for the user `anika` to request temporary credentials for the role `cli-role`. The user `anika` has permissions to assume the role, granted by the role's trust policy.
```
[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
```
The `mfa_serial` setting can take an ARN, as shown, or the serial number of a hardware MFA token.
The first profile, `role-without-mfa`, doesn't require MFA. However, because the previous example trust policy attached to the role requires MFA, any attempt to run a command with this profile fails.
```
$ aws iam list-users --profile role-without-mfa
An error occurred (AccessDenied) when calling the AssumeRole operation: Access denied
```
The second profile entry, `role-with-mfa`, identifies an MFA device to use. When the user attempts to run a Amazon CLI command with this profile, the Amazon CLI prompts the user to enter the one-time password (OTP) that the MFA device provides. If the MFA authentication succeeds, the command performs the requested operation. The OTP is not displayed on the screen.
```
$ aws iam list-users --profile role-with-mfa
Enter MFA code for arn:aws:iam::123456789012:mfa/cli-user:
{
"Users": [
{
...
```
## Cross-account roles and external ID
You can enable users to use roles that belong to different accounts by configuring the role as a cross-account role. During role creation, set the role type to **Another Amazon account**, as described in [Creating a Role to Delegate Permissions to an IAM user](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_create_for-user.html). Optionally, select **Require MFA**. **Require MFA** configures the appropriate condition in the trust relationship, as described in [Using multi-factor authentication](#cli-configure-role-mfa).
If you use an [external ID](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html) to provide additional control over who can use a role across accounts, you must also add the `external_id` parameter to the role profile. You typically use this only when the other account is controlled by someone outside your company or organization.
```
[profile crossaccountrole]
role_arn = arn:aws-cn:iam::234567890123:role/SomeRole
source_profile = default
mfa_serial = arn:aws-cn:iam::123456789012:mfa/saanvi
external_id = 123456
```
## Specifying a role session name for easier auditing
When many individuals share a role, auditing becomes more of a challenge. You want to associate each operation invoked with the individual who invoked the action. However, when the individual uses a role, the assumption of the role by the individual is a separate action from the invoking of an operation, and you must manually correlate the two.
You can simplify this by specifying unique role session names when users assume a role. You do this by adding a `role_session_name` parameter to each named profile in the `config` file that specifies a role. The `role_session_name` value is passed to the `AssumeRole` operation and becomes part of the ARN for the role session. It is also included in the Amazon CloudTrail logs for all logged operations.
For example, you could create a role-based profile as follows.
```
[profile namedsessionrole]
role_arn = arn:aws-cn:iam::234567890123:role/SomeRole
source_profile = default
role_session_name = Session_Maria_Garcia
```
This results in the role session having the following ARN.
```
arn:aws-cn:iam::234567890123:assumed-role/SomeRole/Session_Maria_Garcia
```
Also, all Amazon CloudTrail logs include the role session name in the information captured for each operation.
## Assume role with web identity
You can configure a profile to indicate that the Amazon CLI should assume a role using [web identity federation and Open ID Connect (OIDC)](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_providers_oidc.html). When you specify this in a profile, the Amazon CLI automatically makes the corresponding Amazon STS `AssumeRoleWithWebIdentity` call for you.
**Note**
When you specify a profile that uses an IAM role, the Amazon CLI makes the appropriate calls to retrieve temporary credentials. These credentials are stored in `~/.aws/cli/cache`. Subsequent Amazon CLI commands that specify the same profile use the cached temporary credentials until they expire. At that point, the Amazon CLI automatically refreshes the credentials.
To retrieve and use temporary credentials using web identity federation, you can specify the following configuration values in a shared profile.
[role\$1arn](#cli-configure-role)
Specifies the ARN of the role to assume.
web\$1identity\$1token\$1file
Specifies the path to a file which contains an OAuth 2.0 access token or OpenID Connect ID token that is provided by the identity provider. The Amazon CLI loads this file and passes its content as the `WebIdentityToken` argument of the `AssumeRoleWithWebIdentity` operation.
[role\$1session\$1name](#cli-configure-role-session-name)
Specifies an optional name applied to this assume-role session.
The following is an example of the minimal amount of configuration needed to configure an assume role with web identity profile.
```
# In ~/.aws/config
[profile web-identity]
role_arn=arn:aws:iam:123456789012:role/RoleNameToAssume
web_identity_token_file=/path/to/a/token
```
You can also provide this configuration by using [environment variables](cli-configure-envvars.md).
AWS\$1ROLE\$1ARN
The ARN of the role to assume.
AWS\$1WEB\$1IDENTITY\$1TOKEN\$1FILE
The path to the web identity token file.
AWS\$1ROLE\$1SESSION\$1NAME
The name applied to this assume-role session.
**Note**
These environment variables currently apply only to the assume role with web identity provider. They don't apply to the general assume role provider configuration.
## Clearing cached credentials
When you use a role, the Amazon CLI caches the temporary credentials locally until they expire. The next time you try to use them, the Amazon CLI attempts to renew them on your behalf.
If your role's temporary credentials are [revoked](https://docs.amazonaws.cn/IAM/latest/UserGuide/id_roles_use_revoke-sessions.html), they are not renewed automatically, and attempts to use them fail. However, you can delete the cache to force the Amazon CLI to retrieve new credentials.
**Linux or macOS**
```
$ rm -r ~/.aws/cli/cache
```
**Windows**
```
C:\> del /s /q %UserProfile%\.aws\cli\cache
```