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

I want to assume an AWS Identity and Access Management (IAM) role using the AWS Command Line Interface (AWS CLI).

ResolutionTo assume an IAM role using the AWS CLI and have read-only access to Amazon Elastic Compute Cloud (Amazon EC2) instances, do the following:Note: If you receive errors when running AWS CLI commands, then confirm that you're running a recent version of the AWS CLI.Important: Running the commands the following steps shows your credentials, such as passwords, in plaintext. After you assume the IAM role, it’s a best practice to change your passwords.Create an IAM user with permissions to assume roles1.    Create an IAM user using the AWS CLI using the following command:Note: Replace Bob with your IAM user name.aws iam create-user --user-name Bob2.    Create the IAM policy that grants the permissions to Bob using the AWS CLI. Create the JSON file that defines the IAM policy using your favorite text editor. For example, you can use vim, a text editor that's commonly used in Linux, as follows:Note: Replace example with your own policy name, user name, role, JSON file name, profile name, and keys.vim example-policy.json3.    The contents of the example-policy.json file are similar to the following:{  "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 policy1.    Use the following aws iam create-policy command:aws iam create-policy --policy-name example-policy --policy-document file://example-policy.jsonThe 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-policyNote: Replace 123456789012 with your own account.2.    Note the IAM policy ARN from the output and attach the policy to Bob using the attach-user-policy command. Then, check to make sure that the attachment is in place using 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 BobCreate the JSON file that defines the trust relationship of the IAM role1.    Create the JSON file that defines the trust relationship as follows:vim example-role-trust-policy.json2.    The contents of the example-role-trust-policy.json file are similar to the following:{  "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. You can do this by specifying 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 policyCreate an IAM role that can be assumed by Bob that has read-only access to Amazon Relational Database Service (Amazon RDS) instances. Because of the IAM role being assumed by an IAM user, 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 the account 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 according to the JSON file that you created in the prior section. 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. See the following command examples:aws iam create-role --role-name example-role --assume-role-policy-document file://example-role-trust-policy.jsonaws 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-roleNote: 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 BobThe AWS CLI command outputs an access key ID and a secret access key. Be sure to note these keys.Configure the access keys1.    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 configureAWS Access Key ID [None]: ExampleAccessKeyID1AWS Secret Access Key [None]: ExampleSecretKey1Default region name [None]: eu-west-1Default output format [None]: jsonNote: For Default region name, specify your AWS Region.Verify that the AWS CLI commands are invoked and then verify IAM user access1.    Run the aws sts get-caller-identity command as follows:aws sts get-caller-identityThe aws sts get-caller-identity command outputs three pieces of information including the ARN. The output shows something similar to arn:aws:iam::123456789012:user/Bob to verify that the AWS CLI commands are invoked as Bob.2.    Confirm that the IAM user has read-only access to EC2 instances and no access to Amazon RDS DB instances by running the following commands: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 should show you all the EC2 instances that are in the eu-west-1 Region. The aws rds describe-db-instances command must generate an access denied error message, because Bob doesn't have access to Amazon RDS.Assume the IAM roleDo one of the following:Use an IAM role by creating a profile in the ~/.aws/config file. For more information, see Using an IAM role in the AWS CLI.-or-Assume the IAM role by doing the following:1.    Get the ARN of the role by running 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-SessionThe AWS CLI command outputs 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 using the DurationSeconds parameter.Create environment variables to assume the IAM role and verify access1.    Create three environment variables to assume the IAM role. These environment variables are filled out with the following output:export AWS_ACCESS_KEY_ID=RoleAccessKeyIDexport AWS_SECRET_ACCESS_KEY=RoleSecretKeyexport AWS_SESSION_TOKEN=RoleSessionToken        Note: For Windows systems, replace export with set in this command.2.    Verify that you assumed the IAM role by running the following command:aws sts get-caller-identityThe AWS CLI command should output the ARN as arn:aws:sts::123456789012:assumed-role/example-role/AWSCLI-Session instead of arn:aws:iam::123456789012:user/Bob to verify that you assumed the example-role.3.    Verify you created an IAM role with read-only access to Amazon RDS DB instances and no access to EC2 instances using the following commands: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 should generate an access denied error message. The aws rds describe-db-instances command should return the Amazon RDS DB instances. This verifies that the permissions assigned to the IAM role are working 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_TOKENaws sts get-caller-identityThe 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 informationRoles terms and conceptscreate-roleCreating a role to delegate permissions to an AWS service