How do I assume an IAM role using the AWS CLI?

Resolution

Note: If you receive errors when you run AWS CLI commands, then see Troubleshoot AWS CLI errors. Also, make sure that you're using the most recent AWS CLI version.

To use the AWS CLI to assume an IAM role with read-only access to Amazon Elastic Compute Cloud (Amazon EC2) instances, complete the following actions.

Important: Your credentials, such as passwords, are visible in plaintext when you run the commands in the following steps. It's a best practice to change your passwords after you assume the IAM role.

Create an IAM user with permissions to assume roles

1. Create an IAM user from the AWS CLI with the following command:
   Note: Replace Bob with your IAM user name
2. Create the IAM policy that grants the permissions to user Bob. To do so, use a text editor of your choice to create the JSON file that defines the IAM policy. You can use the following JSON example, example-policy.json, as a template:

   { 
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "ec2:Describe*",
           "iam:ListRoles",
           "sts:AssumeRole"
         ],
         "Resource": "*"
       }
     ]
   }

For more information about creating IAM policies, see Creating IAM policies, Example IAM identity-based policies, and IAM JSON policy reference.

Create the IAM policy

To create your IAM policy, complete the following steps:

1. Run the following aws iam create-policy command:

   aws iam create-policy --policy-name example-policy --policy-document file://example-policy.json

   The aws iam create-policy command outputs several pieces of information, including the ARN (Amazon Resource Name) of the IAM policy as follows:

   arn:aws:iam::123456789012:policy/example-policy

   Note: Replace 123456789012 with your own account ID.
2. Note the IAM policy ARN from the output and attach the policy to Bob with the attach-user-policy command. Then, check to make sure that the attachment is in place with the list-attached-user-policies command as follows:

   aws iam attach-user-policy --user-name Bob --policy-arn "arn:aws:iam::123456789012:policy/example-policy"
   aws iam list-attached-user-policies --user-name Bob

Create the JSON file that defines the trust relationship of the IAM role

Use a text editor to create a JSON file that defines the trust relationship. You can use the following trust policy as an example:

{ 
  "Version": "2012-10-17",
  "Statement": {
    "Effect": "Allow",
    "Principal": {
      "AWS": "123456789012"
    },
    "Action": "sts:AssumeRole"
  }
}

This trust policy allows users and roles of account 123456789012 to assume this role if they allow the sts:AssumeRole action in their permissions policy. You can also restrict the trust relationship so that the IAM role can be assumed only by specific IAM users. To do this, specify principals similar to arn:aws:iam::123456789012:user/example-username. For more information, see AWS JSON policy elements: Principal.

Create the IAM role and attach the policy

Create an IAM role that can be assumed by Bob that has read-only access to Amazon Relational Database Service (Amazon RDS) instances. To allow an IAM user to assume an IAM role, you must specify a principal that allows IAM users to assume that role. For example, a principal similar to arn:aws:iam::123456789012:root allows all IAM identities of account 123456789012 to assume that role. For more information, see Creating a role to delegate permissions to an IAM user.

1. Create the IAM role that has read-only access to Amazon RDS DB instances. Attach the IAM policies to your IAM role according to your security requirements.

   The aws iam create-role command creates the IAM role and defines the trust relationship that you defined in the JSON file that you already created. The aws iam attach-role-policy command attaches the AWS Managed Policy AmazonRDSReadOnlyAccess to the role. You can attach different policies (Managed Policies and Custom Policies) according to your security requirements. The aws iam list-attached-role-policies command shows the IAM policies that are attached to the IAM role example-role. For example, run the following commands:

   aws iam create-role --role-name example-role --assume-role-policy-document file://example-role-trust-policy.json
   aws iam attach-role-policy --role-name example-role --policy-arn "arn:aws:iam::aws:policy/AmazonRDSReadOnlyAccess"
   aws iam list-attached-role-policies --role-name example-role

   Note: Verify that Bob has read-only access to EC2 instances and can assume the example-role.

2. Create access keys for Bob with the following command:

   aws iam create-access-key --user-name Bob

   Important: This AWS CLI command outputs an access key ID and a secret access key. Be sure to note these keys.

Configure the access keys

To configure the access keys, use either the default profile or a specific profile. To configure the default profile, run aws configure. To create a new specific profile, run aws configure --profile example_-_profile-name. In this example, the default profile is configured as follows:

aws configure
AWS Access Key ID [None]: ExampleAccessKeyID1
AWS Secret Access Key [None]: ExampleSecretKey1
Default region name [None]: eu-west-1
Default output format [None]: json

Note: For Default region name, specify your AWS Region.

Verify that the AWS CLI commands are invoked and then verify IAM user access

Complete the following steps:

1. Run the aws sts get-caller-identity command as follows:

   aws sts get-caller-identity

   The output from the aws sts get-caller-identity command includes the ARN. To verify that the AWS CLI commands are invoked as Bob, check that the output includes something similar to arn:aws:iam::123456789012:user/Bob.

2. Run the following commands to confirm that the IAM user has read-only access to EC2 instances and no access to Amazon RDS DB instances:

   aws ec2 describe-instances --query "Reservations[*].Instances[*].[VpcId, InstanceId, ImageId, InstanceType]"
   aws rds describe-db-instances --query "DBInstances[*].[DBInstanceIdentifier, DBName, DBInstanceStatus, AvailabilityZone, DBInstanceClass]"

   The aws ec2 describe-instances command shows you all the EC2 instances that are in the eu-west-1 Region. The aws rds describe-db-instances command generates an access denied error message, because Bob doesn't have access to Amazon RDS.

Assume the IAM role

Do one of the following:

Create a profile in the ~/.aws/config file to use an AIM role. For more information, see Use an IAM role in the AWS CLI.

-or-

Run the following commands to assume the IAM role:

1. Get the ARN of the role with the following command:

   aws iam list-roles --query "Roles[?RoleName == 'example-role'].[RoleName, Arn]"

2. The command lists IAM roles, but filters the output by role name. To assume the IAM role, run the following command:

   aws sts assume-role --role-arn "arn:aws:iam::123456789012:role/example-role" --role-session-name AWSCLI-Session

These commands output several pieces of information. Inside the credentials block, you need the AccessKeyId, SecretAccessKey, and SessionToken. This example uses the environment variables RoleAccessKeyID, RoleSecretKey, and RoleSessionToken. Note that the timestamp of the expiration field is in the UTC time zone. The timestamp indicates when the temporary credentials of the IAM role expire. If the temporary credentials are expired, you must invoke the sts:AssumeRole API call again.

Note: You can increase the maximum session duration expiration for temporary credentials for IAM roles with the DurationSeconds parameter.

Create environment variables to assume the IAM role and verify access

1. Create three environment variables to assume the IAM role. These environment variables contain the following output:

   export AWS_ACCESS_KEY_ID=RoleAccessKeyID
   export AWS_SECRET_ACCESS_KEY=RoleSecretKey
   export AWS_SESSION_TOKEN=RoleSessionToken

   Note: For Windows systems, replace export with set in this command.

2. Run the following command to verify that you assumed the IAM role:

   aws sts get-caller-identity

   If you assume the example-role, then this AWS CLI command will output the ARN as arn:aws:sts::123456789012:assumed-role/example-role/AWSCLI-Session instead of arn:aws:iam::123456789012:user/Bob.

3. Run the following commands to verify that you created an IAM role with read-only access to Amazon RDS DB instances and no access to EC2 instances:

   aws ec2 describe-instances --query "Reservations[*].Instances[*].[VpcId, InstanceId, ImageId, InstanceType]"
   aws rds describe-db-instances --query "DBInstances[*].[DBInstanceIdentifier, DBName, DBInstanceStatus, AvailabilityZone, DBInstanceClass]"

   The aws ec2 describe-instances command generates an access denied error message. The aws rds describe-db-instances command returns the Amazon RDS DB instances. This verifies that the permissions assigned to the IAM role work correctly.

4. To return to the IAM user, remove the environment variables as follows:

   unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
   aws sts get-caller-identity

   The unset command removes the environment variables and the aws sts get-caller-identity command verifies that you returned as the IAM user Bob.

   Note: For Windows systems, set the environmental variables to empty strings to clear their contents as follows:

   SET AWS_ACCESS_KEY_ID=
   SET AWS_SECRET_ACCESS_KEY=
   SET AWS_SESSION_TOKEN=

Related information

Roles terms and concepts

create-role

Creating a role to delegate permissions to an AWS service