Configuring and Using a Role

When you run commands using a profile that specifies an IAM role, the AWS CLI uses the source profile’s credentials to call AWS Security Token Service (AWS 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 AWS Identity and Access Management User Guide. If the role and the source profile’s IAM 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 IAM user (or the users in the AWS account) 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 IAM 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: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 an IAM 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:iam::123456789012:role/marketingadminrole"
    }
  ]
}

The IAM user doesn’t need to have additional permissions to run the 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 AWS resources. For more information about attaching permissions to a role (which works identically to an IAM 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_DEFAULT_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.

$ export AWS_PROFILE=marketingadmin