0%
AWS in Practice: Services, Limits, and Failure Modes
Compute
Storage
Databases
Networking
Delivery and Visibility
Limits, Cost and Recovery
How IAM Evaluates a Request
Every call to an AWS API, whether it comes from the console, the command line, an SDK inside a Lambda function or a service acting on your behalf, arrives at an authorisation engine as a request. Before you can reason about why a request was allowed or denied, you have to know what the engine sees. It does not see your intent, your ticket number or the name of the team that owns the role. It sees a principal, an action, a resource and a bag of context keys, and it evaluates every policy that applies to that combination.
This lesson builds the evaluation model from those parts, because almost every confusing IAM behaviour is explained by one of them being different from what the engineer assumed.
The principal
The principal is the identity making the request after authentication. In practice it is almost always one of three things. An IAM role session, which is what you get when anything assumes a role: an EC2 instance through its instance profile, a Lambda function through its execution role, a pod through EKS Pod Identity, a human through IAM Identity Center, or a pipeline through OIDC federation. An IAM user, which is the older pattern of long lived credentials that most organisations now forbid outside a few edge cases. Or an AWS service principal, such as lambda.amazonaws.com or events.amazonaws.com, which appears when a service acts as itself rather than through one of your roles.
The distinction between a role and a role session matters more than it first appears. A role is a definition, with a trust policy saying who may assume it and permission policies saying what it may do. A role session is one instance of that role being used, with its own temporary credentials, its own session name and possibly its own session policy and session tags. The ARN that shows up in CloudTrail and in the request context is the session ARN, of the form arn:aws:sts::111122223333:assumed-role/deploy/pipeline-run-4821, while a policy that names the principal usually names the role ARN. AWS translates between them, but conditions that compare aws:PrincipalArn see the role ARN, and conditions that compare aws:userid see the role's unique ID joined to the session name. Mixing those up is a classic cause of a condition that never matches.
The root user of an account is also a principal, and a peculiar one. Identity policies cannot be attached to it and it is not limited by them, but service control policies and resource control policies do apply to it in member accounts.
The action
An action is a service prefix and an operation name, such as s3:GetObject, dynamodb:Query or kms:Decrypt. Actions are case insensitive in policies, support wildcards, and do not always map one to one onto API calls. A single console page can make a dozen API calls, each with its own action. Some API calls require several permissions: launching an EC2 instance with an instance profile requires ec2:RunInstances and iam:PassRole on the role being attached, and launching it with an encrypted volume under a customer managed key requires permissions on the key as well.
iam:PassRole deserves special attention because it is the permission that most often turns a narrow policy into a privilege escalation path. Whenever a principal hands a role to a service, by creating a Lambda function with an execution role, starting a Glue job, registering an ECS task definition or launching an instance with a profile, the service will later act with that role's permissions. If a developer can pass any role to Lambda, they can create a function that runs as the most privileged role in the account. Policies granting iam:PassRole should always name specific role ARNs and, where possible, use the iam:PassedToService condition key to restrict which service may receive the role.
The resource
The resource is the ARN of the thing being acted on, such as arn:aws:s3:::invoices-prod/2026/11/inv-881.pdf or arn:aws:dynamodb:eu-west-1:111122223333:table/orders. Each action defines which resource types it applies to, and the Service Authorization Reference lists them. Some actions apply to no resource at all, such as s3:ListAllMyBuckets or ec2:DescribeInstances, and for those the policy must use "Resource": "*" or the statement simply never matches. A policy that tries to scope ec2:DescribeInstances to a single instance ARN is not wrong in syntax, it is silently ineffective, because the action is evaluated against *.
S3 is the most common source of resource confusion. A bucket and an object are different resources. s3:ListBucket applies to the bucket ARN arn:aws:s3:::invoices-prod, while s3:GetObject applies to object ARNs arn:aws:s3:::invoices-prod/*. A policy that grants both actions on only one of those ARNs grants half of what the author intended, and the resulting error message rarely makes that obvious.
Reading an ARN carefully
An Amazon Resource Name has six colon separated fields: the literal arn, the partition, the service, the region, the account and the resource. The partition is aws for the commercial regions, aws-cn for China and aws-us-gov for GovCloud, and a policy written with a hard coded arn:aws: prefix silently fails to match in the other partitions. The region and account fields are empty for global resources, which is why an S3 bucket ARN reads arn:aws:s3:::invoices-prod with three colons in a row, and an IAM role ARN reads arn:aws:iam::111122223333:role/deploy with an empty region.
The resource field has a service specific shape. Some services use a slash, as in table/orders, some a colon, as in function:resize-images, and some carry qualifiers such as a Lambda version or alias. Wildcards in that field behave as plain string globbing, so table/orders* matches orders, orders-archive and orders_backup_2019, which may not be what the author meant. DynamoDB indexes are sub resources with their own ARN, table/orders/index/by-customer, so a policy that grants dynamodb:Query on the table alone does not allow querying an index.
Paths in IAM ARNs are another quiet source of mismatch. A role created with the path /app/ has the ARN arn:aws:iam::111122223333:role/app/resize-worker, and a policy that names role/resize-worker does not match it. Paths are useful for grouping delegated roles, as a later section shows, but every policy that names those roles must include the path.
The principal ARN in CloudTrail and the principal ARN in a policy can also look different for the same identity, as discussed above, so when a match fails, compare the two strings character by character rather than by eye.
The request context
The context is the part most engineers never look at and the part that makes conditions work. AWS populates a set of global condition keys on every request and a set of service specific keys for many actions. The global keys include aws:PrincipalArn, aws:PrincipalAccount, aws:PrincipalOrgID, aws:PrincipalTag/<key> for tags on the role, aws:RequestedRegion, aws:SourceIp, aws:SourceVpc and aws:SourceVpce for requests arriving through a VPC endpoint, aws:SecureTransport, aws:CurrentTime, aws:MultiFactorAuthPresent, aws:ViaAWSService for calls a service makes on your behalf, aws:CalledVia, and aws:ResourceTag/<key> for tags on the target resource. Service keys include things like s3:prefix on a list request, dynamodb:LeadingKeys on a query, and kms:EncryptionContext:<key> on a decrypt.
Two properties of the context cause real bugs. The first is that a key may be absent. aws:SourceIp is not set on calls a service makes on your behalf, and aws:SourceVpc is only set when the request arrives through a gateway or interface endpoint. A condition operator applied to an absent key evaluates to false unless you use the IfExists variant, which means a Deny with StringNotEquals on aws:SourceVpc will deny every call that did not come through an endpoint, including the ones Athena or CloudFormation make for you. The second is that some keys are set by the caller and some by AWS. aws:PrincipalTag comes from the role, which an administrator controls. aws:RequestTag comes from the request, which the caller controls. Writing an authorisation rule on a key the caller sets is writing a rule the caller can satisfy.
When a request is denied unexpectedly, write down the four things the engine saw: the session ARN from CloudTrail, the exact action name, the exact resource ARN, and the context keys present on the call. Most mysteries dissolve at this step, because the action was a different one than expected, the resource was the bucket rather than the object, or the condition key the policy relied on was simply not on the request.