How do I use the AWS CLI to assume an IAM role?

Resolution

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

Note:

• If you receive errors when you run AWS CLI commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.
• In the following example commands, replace Bob with your IAM username.

Create an IAM user and policy

Complete the following steps:

1. Run the create-user AWS CLI command to create an IAM user:

   aws iam create-user --user-name Bob

2. Use your preferred text editor to create a IAM JSON policy that grants permission to the user to assume the IAM role.
   Example JSON policy:

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

   Note: For more information about how to create IAM policies, see Create IAM policies (AWS CLI) and Example IAM identity-based policies.

3. Run the following create-policy AWS CLI command:

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

   Note: In the output of the command, note the Amazon Resource Name (ARN), for example arn:aws:iam::123456789012:policy/example-policy.

4. Run the attach-user-policy command to attach the policy to the IAM user:

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

   Note: Replace 123456789012 with your AWS account ID.

5. Run the list-attached-user-policies command to confirm that the policy is attached to the user:

   aws iam list-attached-user-policies --user-name Bob

Create a trust policy

Use your preferred text editor to create a trust policy that defines the trust relationship between the IAM user and the IAM role that the user is assuming.

Example JSON trust policy:

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

The preceding trust policy uses the sts:AssumeRole action to allow users and roles of account 123456789012 to assume the IAM role. To allow only specific IAM users to assume the IAM role, use a Principal element, such as arn:aws:iam::123456789012:user/example-username, in the trust policy.

Create the IAM role and attach the policy

Create an IAM role for the user to assume that has read-only access to Amazon RDS DB instances. You must specify a Principal that allows IAM users to assume the role. For example, arn:aws:iam::123456789012:root allows all IAM identities of account 123456789012 to assume the role. 

Complete the following steps:

1. Run the create-role command to create the IAM role that has read-only access to RDS DB instances:

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

2. Run the attach-role-policy to attach the IAM policy to the role:

   aws iam attach-role-policy --role-name example-role --policy-arn "arn:aws:iam::aws:policy/AmazonRDSReadOnlyAccess"

3. Run the list-attached-role-policies command to confirm that the policy is attached to the role:

   aws iam list-attached-role-policies --role-name example-role

   Note: Verify that the user has read-only access to RDS DB instances and can assume the example-role.

Create and configure the access keys

1. Run the create-access-key command to create access keys for the user:

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

   Note: In preceding command's output, note the AccessKeyId and SecretAccessKey.

2. Run the following configure command to configure the default profile with your access keys:

   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. To create and use a specific profile instead of the default profile, run aws configure --profile example_profile-name.

Confirm that the user can invoke the AWS CLI commands and check instance access

Complete the following steps:

1. Run the get-caller-identity command:

   aws sts get-caller-identity

    Note: Confirm that the command's output includes the IAM role's ARN, arn:aws:iam::123456789012:user/username.

2. Run the following describe-db-instances command to confirm that the IAM user doesn't have access to RDS DB instances:

   aws rds describe-db-instances --query "DBInstances[*].[DBInstanceIdentifier, DBName, DBInstanceStatus, AvailabilityZone, DBInstanceClass]"

   Note: The preceding command returns an "Access denied" error message because Bob doesn't have access to the RDS DB instances.

Assume the IAM role

To assume the IAM role, create a profile in the ~/.aws/config file. Or, run the following commands.

To get the role's ARN, run the list-roles command:

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

To assume the IAM role, run the assume-role command and include the role's ARN:

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

In the preceding command's output, note the AccessKeyId, SecretAccessKey, and SessionToken. The timestamp in the expiration field is in the UTC time zone and shows when the IAM role's temporary credentials expire. After the temporary credentials expire, the user must assume the role again.

Note: For temporary credentials, you can use the DurationSeconds parameter to increase the maximum session duration for IAM roles.

Create environment variables to assume the IAM role and verify read-only access

Complete the following steps:

1. Run the following commands to set the environment variables to assume the IAM role:

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

   Note: Replace the example values with the values that you noted when you assumed the IAM role. For Windows operating system (OS), replace export with set.

2. Run the get-caller-identity command to verify that the user assumed the IAM role:

   aws sts get-caller-identity

   Note: In the preceding command's output, confirm that the ARN is arn:aws:sts::123456789012:assumed-role/example-role/AWSCLI-Session instead of arn:aws:iam::123456789012:user/username.

3. Run the following describe-db-instances command to verify that you created an IAM role with read-only access to RDS DB instances:

   aws rds describe-db-instances --query "DBInstances[*].[DBInstanceIdentifier, DBName, DBInstanceStatus, AvailabilityZone, DBInstanceClass]"

   Note: The preceding command returns the RDS DB instances that confirms that the IAM role has read-only access.

Return to the IAM user

Complete the following steps:

1. Run the unset command to remove the environment variables:

   unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

2. Run the get-caller-identity command to confirm that you removed the user from the assumed role:

   aws sts get-caller-identity

   Note: For Windows, set the environmental variables to empty strings:

   SET AWS_ACCESS_KEY_ID=
   SET AWS_SECRET_ACCESS_KEY=
   SET AWS_SESSION_TOKEN=