CloudConsole

iam:PassRole: policy example and why it matters

Updated 17 November 2026 · How we write and check guides

Short answer

iam:PassRole is checked when you hand a role to a service, for example creating a Lambda function or launching an EC2 instance with an instance profile. Allow it only on the specific role ARNs, with iam:PassedToService naming the service, never on Resource "*".

Policy diagram: 2 statement(s); first Allow iam:PassRole on iam: role/orders-api-lambda
The policy on this page drawn statement by statement: who it applies to, the actions, the resources and any condition.

The policy

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PassOrdersRoleToLambdaOnly",
      "Effect": "Allow",
      "Action": "iam:PassRole",
      "Resource": "arn:aws:iam::123456789012:role/orders-api-lambda",
      "Condition": {
        "StringEquals": {
          "iam:PassedToService": "lambda.amazonaws.com"
        }
      }
    },
    {
      "Sid": "DeployOrdersFunction",
      "Effect": "Allow",
      "Action": [
        "lambda:CreateFunction",
        "lambda:UpdateFunctionCode",
        "lambda:UpdateFunctionConfiguration",
        "lambda:GetFunction"
      ],
      "Resource": "arn:aws:lambda:eu-west-2:123456789012:function:orders-api"
    }
  ]
}

What PassRole actually is

There is no PassRole API. It is a permission IAM checks when another API accepts a role ARN: lambda:CreateFunction --role, ec2:RunInstances with an instance profile, ecs:RegisterTaskDefinition with task roles, CloudFormation with a service role, and many more.

The point is to stop privilege escalation. If you could create a function with any role, you could pick an admin role, have the function do whatever you like, and bypass your own restrictions. So you need permission both to create the function and to pass that particular role.

  • PassOrdersRoleToLambdaOnly: only this role, and only to Lambda. The same role can't be passed to EC2 or Glue.
  • DeployOrdersFunction: the deploy actions on the one function.

Service principals to use in the condition

Passing a role toiam:PassedToService
Lambda functionlambda.amazonaws.com
EC2 instance profileec2.amazonaws.com
ECS task role / execution roleecs-tasks.amazonaws.com
CodeBuild projectcodebuild.amazonaws.com
CloudFormation service rolecloudformation.amazonaws.com
Step Functions state machinestates.amazonaws.com
aws iam put-user-policy --user-name deployer \
  --policy-name deploy-orders --policy-document file://passrole.json

Variations

  • A family of roles: use a path, arn:aws:iam::123456789012:role/app/*, and create workload roles under /app/. Combine with permissions boundaries for delegated teams.
  • Only to a specific resource: the iam:AssociatedResourceArn condition key can name the resource the role is passed to, for services that support it.
  • CI pipelines: deploy roles used by GitHub Actions or CDK need PassRole on the roles they create or update; scope those the same way.

Find who can pass powerful roles

Search your policies for iam:PassRole with a wildcard resource; each hit is a potential escalation path. The policy simulator can then confirm whether a given user may pass an admin role:

aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::123456789012:user/deployer \
  --action-names iam:PassRole \
  --resource-arns arn:aws:iam::123456789012:role/Admin

Common mistakes

  • iam:PassRole on "*": anyone with it plus a compute service can act as any role in the account. Treat it like admin.
  • Misreading the error: not authorized to perform: iam:PassRole on resource names the role you tried to pass, not your own.
  • Granting PassRole to the service role itself. The role being passed doesn't need PassRole; the person or pipeline passing it does.
  • Wildcards in iam:PassedToService: use exact service principals.

Questions

Why do I need iam:PassRole?

Any API that hands a role to a service checks it, so you can't give a service more power than you are allowed to delegate.

Is iam:PassRole on * dangerous?

Yes. Combined with the ability to create compute (Lambda, EC2, ECS), it lets a user run code as any role in the account, including admin roles.

When this happens away from your desk

PassRole errors usually stop a deploy halfway. The CloudTrail event for the failed call, which you can read from a phone, names both the caller and the role it tried to pass.

About the app → · Download on the App Store

Sources