Menu
AWS Identity and Access Management
User Guide

Granting a User Permissions to Pass a Role to an AWS Service

To configure many AWS services, you must "pass" an IAM role to the service that defines what that service can do on your behalf. For example, to provide applications running on an Amazon EC2 instance with AWS credentials, you pass a role to EC2 to use with the instance that provides those credentials. You define what the credentials allow the applications running on the instance to do by attaching an AWS Identity and Access Management (IAM) policy that grants the required permissions to the role.

To pass a role (and its permissions) to an AWS service, a user must have permissions to "pass the role" to the service. This helps administrators ensure that only approved users can configure a service with a role that grants permissions. To allow a user to pass a role to an AWS service, you must grant the PassRole permission to the user's IAM user, role, or group.

When a user passes a role ARN as a parameter to any API that uses the role to assign permissions to the service, the service checks that the user performing the action has the iam:PassRole permission. To limit the user to passing only approved roles, you can filter the iam:PassRole permission with the Resources element of the IAM policy statement.

Example 1

Imagine that you want to grant a user the ability to pass any of an approved set of roles to the Amazon EC2 service upon launching an instance. You need three elements:

  • An IAM permissions policy attached to the role that determines what the role can do. Scope permissions to only the actions that the role needs to perform, and to only the resources that the role needs for those actions. You can use AWS-managed or customer-created IAM permissions policy.

    Copy to clipboard
    { "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": [ "A list of the permissions the role is allowed to use" ], "Resource": [ "A list of the resources the role is allowed to access" ] } }
  • A trust policy for the role that allows the service to assume the role. For example, you could attach the following trust policy to the role with the UpdateAssumeRolePolicy action. This trust policy allows Amazon EC2 to use the role and the permissions attached to the role.

    Copy to clipboard
    { "Version": "2012-10-17", "Statement": { "Sid": "TrustPolicyStatementThatAllowsEC2ServiceToAssumeTheAttachedRole" "Effect": "Allow", "Principal": { "Service": "ec2.amazonaws.com" }, "Action": "sts:AssumeRole" } }
  • An IAM permissions policy attached to the IAM user that allows the user to pass only those policies that are approved. iam:PassRole usually is accompanied by iam:GetRole so that the user can get the details of the role to be passed. In this example, the user can pass only roles with names that begin with EC2-roles-for-XYZ-:

    Copy to clipboard
    { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "iam:GetRole", "iam:PassRole" ], "Resource": "arn:aws:iam::*:role/EC2-roles-for-XYZ-*" }], }

Now the user can start an Amazon EC2 instance with an assigned role. Applications running on the instance can access temporary credentials for the role through the instance profile metadata. The permission policies attached to the role determine what the instance can do.

Example 2

Amazon Relational Database Service (Amazon RDS) supports a feature called Enhanced Monitoring, which enables Amazon RDS to monitor a DB instance using an agent and report metrics to Amazon CloudWatch logs. To allow a user to enable Enhanced Monitoring for databases in your organization, you must configure Amazon RDS with an IAM role that it assumes, which grants it the permissions to monitor and write metrics to your logs. If the user who is setting up Amazon RDS had permissions to create roles and attach policies to them, the user could use the Enhanced Monitoring feature in the Amazon RDS console to create the role on their behalf. However, in this example the user does not have permissions to create roles, so you must create the role in advance. You can then grant that user permissions "pass" that one role to Amazon RDS when enabling Enhanced Monitoring.

To create a role for Amazon RDS Enhanced Monitoring

  1. Sign in to the IAM console at https://console.aws.amazon.com/iam/.

  2. Choose Roles, and then choose Create new role.

  3. Type a name for the role, such as RDS-Monitoring-Role, and then choose Next step.

  4. On the Select Role Type page, in the AWS Service Roles list, find Amazon RDS Role for Enhanced Monitoring, and then choose Select.

  5. On the Attach Policy page, select AmazonRDSEnhancedMonitoringRole, choose Next Step, and then choose Create Role.

The role automatically gets a trust policy that grants the monitoring.rds.amazonaws.com service permissions to assume the role. After it does, Amazon RDS can perform all of the actions allowed by the AmazonRDSEnhancedMonitoringRole policy.

The user that you want to enable Enhanced Monitoring needs a policy that includes a statement that allows the user to pass the role, like the following. Use your account number and replace the role name with the name you provided in step 3:

Copy to clipboard
{ "SID": "PolicyStatementToAllowUserToPassOneSpecificRole", "Effect": "Allow", "Action": [ "iam:PassRole" ], "Resource": "arn:aws:iam:::role/RDS-Monitoring-Role" }

You can combine this statement with statements in another policy or put it in its own policy. To instead specify that the user can pass any role that begins with RDS-, you can replace the role name in the resource ARN with a wildcard, for example:

Copy to clipboard
"Resource": "arn:aws:iam:::role/RDS-*"