IAM::PassRole Explained

Understanding the iam:PassRole permission is key to not only getting your applications working in AWS, but also doing it securely.


by Rowan

Sep 20, 2021


A common point of confusion when getting started with AWS IAM, and when trying to implement "least privileges" on IAM is the message "is not authorized to perform: iam:PassRole on resource". Usually this refers to "User" or "CloudFormation" as the culprit. While the error tells you that iam:PassRole is involved, it doesn't really hint at the how or why of the problem at hand. Hopefully this explanation and diagrams can help you.

There's no doubt AWS IAM is great at its job. Unfortunately you sometime get exposed to some complicated situations right out of the gate when you start using it, which doesn't make it easy to learn. Understanding the iam:PassRole permission is key to not only getting your applications working in AWS, but also doing it securely.

IAM PassRole

Confusion with IAM PassRole is not that unusual, and a quick search on SO will show you many other people suffering the same problem. For better or worse, most of the explanations are copied from the official documentation or this old blog post about EC2, and neither of those do a great job of explaining why you need to jump through the IAM PassRole hoop to get things working

The problem is, IAM PassRole is not an API method. Even though you can see it sitting there in the Action list of your policies, it's a lie it's not an API you can call to do something.

Almost all the other actions you will see in all your policies map nicely to API methods you will take on AWS e.g. `ec2:CreateInstances` to create some instances, `lambda:InvokeFunction` to trigger a function, etc. `iam:PassRole` is not one of those, which causes confusion when the error message demands that you authorise it. At least now the Actions, resources, and conditions page for IAM lists it with [permission only] next to it, but that's a relatively recent improvement and a subtle one at that.

But Why PassRole, Why?

The reason `iam:PassRole` is required is not to get your scenario working, it's to prevent a specific, but very realistic, escalation of privilege attack based on the confused deputy problem. Unfortunately there isn't a lot of reference to this in the starting documentation or many of the AWS blog posts out there, so you're left to figure this one out on your own.

If you're just bashing around AWS with `AdministratorAccess` attached to your role like most people are in their development environment, you won't notice any of this since you've implicit granting of `iam:PassRole` to * resources/roles.

When you go to do this in an environment where you don't have full access is usually when you experience it. The PassRole permission is an important layer of security to protect your AWS environment from unintended and unwanted activities and escalation of privileges.

The Happy Path

Giving AWS services authorisation to do things in your account is a completely normal thing to do. While this might sound a little scary at first, it's actually a good thing! Configuring AWS services to do things for you means less work that you have to do.

In this case, a user who has `AdministratorAccess0` attaches a role to their instance so that it can be used to make calls to the AWS APIs.

The Sad Path

Where this goes wrong, is when the AWS service is told to do something that you probably didn't intend. Without any additional layer of permissions, it can be ordered to do something it can do, but should not do.

In this scenario EC2 has been configured by a user (who only has the made-up `LimitedAccess` policy, which includes the ability to create EC2 instances BUT is not as powerful as `AdministratorAccess`) to give the instance it creates a role higher level of access to your environment than the original requestor had (in this case, the highly desirable `AdministratorAccess`).

The Solution

The PassRole permission (not action, even though it's in the Action block!) is the additional layer of checking required to secure this.

By giving a role or user the iam:PassRole permission, you are is saying "this entity (principal) is allowed to assign AWS roles to resources and services in this account".

You can limit which roles a user or service can pass to others by specifying the role ARN(s) in the Resource field of the policy that grants them iam:PassRole:

2  "Effect": "Allow",
3  "Action": "iam:PassRole",
4  "Resource": "arn:aws:::123456789012:role/LimitedAccess"

This diagram shows the previous scenario, but with the policy statement above included to provide an additional layer of checking with PassRole, and limit it to the role(s) specified the Resource block.

Specific AWS Services

You can also limit roles to be used by specific AWS services as another level of security you can apply, which is always a good idea. This page in the IAM User Guide has an example of the policy you should use to limit `iam:PassRole` to a specific AWS service, but keep in mind it's allowing access to ALL your roles in its current form. Unfortunately at the time of writing, not all services you'd expect are supported e.g. Lambda (for normal functions). Check out the list of services that support service-linked roles in the documentation.

Hopefully this helps you understand the "is not authorized to perform: iam:PassRole on resource" error message. If you're still unsure, get in touch with me and let me know so I can improve on this explanation.

Cover photo by Silvia Brazzoduro on Unsplash


    Join the beta waitlist

    Enter your email to get notified when our product becomes available to try.

    Sign Up for the community

    Create your member profile to get involved with our content, programs, and events.