Granting Permission to Launch EC2 Instances with IAM Roles (PassRole Permission)

When you launch an Amazon EC2 instance, you can associate an AWS IAM role with the instance to give applications or CLI commands that run on the instance permissions that are defined by the role. When a role is associated with an instance, EC2 obtains temporary security credentials for the role you associated with the instance. It then makes those temporary credentials available to applications and CLI commands that run on the instance. Not only is using a role with EC2 in this way more secure than alternative ways of providing credentials to the instance, but it’s more convenient and easier to manage.

If an IAM user wants to launch an EC2 instance, you need to grant the EC2 RunInstances permission to that user. If the EC2 instance should include an instance profile—that is, if applications in the EC2 instance will be able to get temporary security credentials via an IAM role—the user who launches the EC2 instance must also have the IAM PassRole permission. Not only that, but the user might need PassRole permission to associate a specific role with the EC2 instance. If the user doesn’t have PassRole permission, he or she can’t associate a role with the instance during launch. The PassRole permission is a security protection, as we’ll explain in a moment. 

For example, you might attach the following policy to a user. It gives the user full EC2 permissions, which includes the ability to launch instances.

{
   "Version": "2012-10-17",
   "Statement": [{
      "Effect":"Allow",
      "Action":["ec2:*"],
      "Resource":"*"
    },
    {
      "Effect":"Allow",
      "Action":"iam:PassRole",
      "Resource":"arn:aws:iam::123456789012:role/S3Access"
    }]
}

Notice that the second statement is for the PassRole action, and that the Resource element specifies the ARN of a role named S3Access. When the user launches an EC2 instance, that user is allowed to associate only the S3Access role with the instance. When an application is running in the instances that are launched by this user, that application can perform only the actions that are permitted by whatever is defined in the S3Access role.

Why do users need this permission?

The PassRole permission helps you make sure that a user doesn’t pass a role to an EC2 instance where the role has more permissions than you want the user to have. For example, Alice might be allowed to perform only EC2 and S3 actions. If Alice could pass a role to the EC2 instance that allows additional actions, she could log into the instance, get temporary security credentials via the role she passed, and make calls to AWS that you don’t intend.

As with other IAM permissions, you can specify a wildcard (*) as the resource for the PassRole permission. For example, the following policy allows a user to associate any role whose name starts with DevTeam with the instance, such as DevTeam1 or DevTeam2.

{
   "Version": "2012-10-17",
   "Statement": [{
      "Effect":"Allow",
      "Action":["ec2:*"],
      "Resource":"*"
    },
    {
      "Effect":"Allow",
      "Action":"iam:PassRole",
      "Resource":"arn:aws:iam::123456789012:role/DevTeam*"
    }]
}

You can also use a wildcard to indicate that the permission applies to all resources–in this case, that the user is allowed to associate any role with an instance:

"Resource":"arn:aws:iam::123456789012:role/*"

Using a wildcard like this can be appropriate if the user already has administrator-level permissions and if applications running on the instance require full AWS permissions. But if you’re creating a policy that includes the PassRole permission for a user who doesn’t have full AWS permissions, you want to make sure that the roles that a user can pass do not grant more permissions than the user already has.

People sometimes ask why there is no PassRole API in the IAM API documentation. That’s a reasonable question, because IAM permissions generally map one for one with IAM actions. In this case, though, there is no explicit action—you don’t call PassRole as an API. Instead, roles are “passed” to EC2 instances during launch if they are associated with the instance. You can think of PassRole as a check that EC2 makes when an instance is launched: “Is this user allowed to associate this role with the new instance?”

We encourage you to make sure that users in your account who have permission to launch EC2 instances always have a PassRole permission that limits the users to IAM roles that match their own permissions. For more information about using roles with EC2 instances, see Granting Applications that Run on Amazon EC2 Instances Access to AWS Resources in the IAM documentation.

As always, if you have questions, please post them to the AWS IAM forum.

– Mike

Want more AWS Security how-to content, news, and feature announcements? Follow us on Twitter.