5.4.3 Using an IAM Role in the AWS CLI

https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html

An AWS Identity and Access Management (IAM) role is an authorization tool that lets an IAM user gain additional (or different) permissions, or get permissions to perform actions in a different AWS account.

You can configure the AWS Command Line Interface (AWS CLI) to use an IAM role by defining a profile for the role in the ~/.aws/credentials 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 CLI uses the credentials defined in the profile ‘user1’ to assume the role with the Amazon Resource Name (ARN) ‘arn:aws:iam::123456789012:role/marketingadminrole’. You can run any operations that are allowed by the permissions assigned to that role.

[marketingadmin]
role_arn = arn:aws:iam::123456789012:role/marketingadminrole
source_profile = user1

You can then specify a ‘source_profile’ that points to a separate named profile that contains IAM 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 AWS CLI command is to use the profile ‘marketingadmin’, the 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 CLI command. The specified role must have attached IAM permission policies that allow the requested CLI command to run.

To run a 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: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 AWS CloudTrail logs.