This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.
Using an IAM role in the Amazon CLI
An Amazon Identity and Access Management (IAM) role 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
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, updating, and uninstalling the Amazon CLI.
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_PROFILE environment variable), 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::
.
You can run any operations that are allowed by the permissions assigned to that role.123456789012
:role/marketingadminrole
[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 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 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.
{ "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 in the IAM User Guide.
{ "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 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) and IAM roles 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.
{ "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. Optionally, select Require MFA. Require MFA configures the appropriate condition in the trust relationship, as described in Using multi-factor authentication.
If you use an external ID 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). 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_arn
-
Specifies the ARN of the role to assume.
- web_identity_token_file
-
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 theAssumeRoleWithWebIdentity
operation. - 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.
- AWS_ROLE_ARN
-
The ARN of the role to assume.
- AWS_WEB_IDENTITY_TOKEN_FILE
-
The path to the web identity token file.
- AWS_ROLE_SESSION_NAME
-
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, 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