AWS has a dozen policies. They're all one shape.
AWS keeps inventing policies. S3 bucket policy, SQS queue policy, SNS topic policy, Lambda function policy, KMS key policy, API Gateway resource policy, IAM role trust policy. It looks like a dozen things to learn.
It's one JSON shape, and two questions sort most of them.
The basic shape
Every one of them is this JSON (the comments are for reading; real policy JSON has none):
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow", // or Deny
"Principal": { }, // who
"Action": ["s3:GetObject"], // what they may do
"Resource": "arn:...", // on which thing
"Condition": { } // when (optional)
}]
}The field names are the same in every service. Each service defines these two:
- the service prefix on the action:
s3:,sqs:,kms: - the format of the ARN (Amazon Resource Name, the full ID of an AWS resource) in
Resource
Principal is sometimes there and sometimes not.
Sorting a dozen policies, roughly
The IAM policy types page lists 9 policy types: identity-based, resource-based, VPC endpoint policy, permissions boundary, SCP, RCP, ACL, RAM (Resource Access Manager) resource share, session policy.
- Identity or resource: is the policy attached to an identity or to a resource?
- Grant or cap: does the policy grant access, or only cap it?
| Grants access | Only caps access | |
|---|---|---|
Attached to an identity (no Principal) | identity-based policy (including a role's permission policy) | permissions boundary, session policy, SCP |
Attached to a resource (needs Principal) | resource-based policy (bucket policy, a role's trust policy, KMS key policy, ..., and the policy a RAM resource share generates) | RCP, VPC endpoint policy |
SCP and RCP actually attach to an AWS Organizations organization root, OU (organizational unit) or account; the table places them by what they govern:
- An SCP limits what every user and role in the account it's attached to can do. Its targets are those identities, so an SCP has no
Principal; the SCP syntax page lists it as unsupported. - An RCP limits who can access the resources in the account. A rule written against resources has to say who is accessing them, so an RCP has a
Principal. It can only be*, though; narrowing it takes aCondition, for example to deny only accounts outside the organization.
Two exceptions sit outside the table:
- An ACL (access control list) is S3's access system from before policies. It's attached to buckets and objects and grants access, so by the two questions it belongs with "attached to a resource, grants". It isn't in the table because it isn't this JSON: it's XML grants that say which account or group may read or write.
- A CloudFormation stack policy uses the same JSON but has nothing to do with access, so it isn't one of AWS's 9.
Identity or resource
Say you created a role called Reader, and it should be able to read files in the bucket reports. There are two places to write that.
Identity-based policy: on the role
The first place is the role Reader. A policy attached to an identity is an identity-based policy (shortened to "identity policy" in the boolean expressions later, and sometimes called an "IAM policy"; all three mean the same thing):
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::reports/*"
}Save it as read-reports.json (wrapped in the "Version" and "Statement" from the skeleton at the top) and attach it to the role:
aws iam put-role-policy \
--role-name Reader \
--policy-name read-reports \
--policy-document file://read-reports.json
Resource-based policy: on the bucket
The second place is the bucket reports. A policy attached to a resource is a resource-based policy, here a bucket policy. This one needs a Principal naming who may read:
{
"Effect": "Allow",
+ "Principal": { "AWS": "arn:aws:iam::111122223333:role/Reader" },
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::reports/*"
}Why only the bucket policy needs a Principal
A bucket policy says who may read the bucket, so Principal names them. The one on Reader doesn't need it, because the one reading is Reader itself. The IAM Principal element page states both rules. Checked in November 2026 with aws accessanalyzer validate-policy: the second policy, checked as an identity-based policy, returns UNSUPPORTED_PRINCIPAL; the first, checked as a bucket policy, returns MISSING_PRINCIPAL.
Every policy listed at the top of the article sits on a resource like this. The "Resource-based policies" column in the IAM services table has the full list.
Which kind is an IAM role's policy?
What people call an "IAM role policy" is really one of two: the permission policy or the trust policy. The first is identity-based, the second resource-based.
Say a Lambda function uses Reader to read reports.
Trust policy: who may assume Reader
A trust policy's Action depends on how whoever assumes the role signed in (see the IAM OIDC role page):
- An AWS user, role or service:
sts:AssumeRole - Signed in through OIDC (OpenID Connect), such as GitHub Actions:
sts:AssumeRoleWithWebIdentity - Signed in through SAML (Security Assertion Markup Language):
sts:AssumeRoleWithSAML
This JSON defines who may assume Reader:
{
"Effect": "Allow",
"Principal": { "Service": "lambda.amazonaws.com" },
"Action": "sts:AssumeRole"
}The permission policy is the one from "Identity or resource", attached to Reader and allowing reads of reports. When the Lambda reads a file, AWS checks the two in order:
- The Lambda asks to assume
Reader. - AWS checks the trust policy:
lambda.amazonaws.comis inPrincipal, so this is allowed. - The Lambda gets
Reader's temporary credentials. - The Lambda calls
s3:GetObjectwith them. - AWS checks the permission policy:
reports/*is allowed, so this is allowed.
The trust policy needs a Principal and the permission policy doesn't, for the same reason as the bucket policy. A trust policy has no Resource, because the resource is the role itself. validate-policy rejects a trust policy that includes one with ROLE_TRUST_POLICY_SYNTAX_ERROR_RESOURCE.
How trust policies work is covered in assumeRole and trust policy.
Grant or cap
Every policy so far grants access. A few others use the same shape but only set a ceiling and grant nothing themselves.
Permissions boundary
A permissions boundary attaches to an IAM user or role and has no Principal. Say Reader's identity-based policy allows every S3 action:
{
"Effect": "Allow",
"Action": "s3:*",
"Resource": "*"
}Reader also has a permissions boundary, s3-read-only, that allows only s3:GetObject:
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "*"
}Both are the same kind of JSON, attached with different commands:
- Attached with
put-role-policy, it's an identity-based policy. Several of them combine with||: one allow is enough. - Attached with
put-role-permissions-boundarybelow, it's a permissions boundary, and it combines with the identity-based policy by&&, which the IAM evaluation page calls an intersection.
So Reader can do only s3:GetObject, which both allow; an s3:PutObject call is denied.
A boundary has to exist as a managed policy first, then gets attached by its ARN:
aws iam create-policy \
--policy-name s3-read-only \
--policy-document file://s3-read-only.json
aws iam put-role-permissions-boundary \
--role-name Reader \
--permissions-boundary arn:aws:iam::111122223333:policy/s3-read-only
Session policy
A session policy also only caps. Say the IAM user ops wants Reader's permissions, but only to read reports/q3.pdf this time. They write that limit as only-q3.json:
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::reports/q3.pdf"
}Then they assume Reader with this command, passing only-q3.json with --policy:
aws sts assume-role \
--role-arn arn:aws:iam::111122223333:role/Reader \
--role-session-name read-q3 \
--policy file://only-q3.json
AWS checks Reader's trust policy first. The trust policy above lists only lambda.amazonaws.com as Principal, so for ops to assume the role, the trust policy needs another statement with arn:aws:iam::111122223333:user/ops as Principal.
Once that passes, AWS gives ops temporary credentials whose permissions are permission policy && session policy. The permission policy allows all of reports/*, only-q3.json only reports/q3.pdf, so they can read only q3.pdf. Even if only-q3.json were s3:*, a call to s3:PutObject would still be denied, because the permission policy allows only s3:GetObject. The IAM policy types page says permissions boundaries and session policies both "do not grant permissions."
Trust policies and session policies both show up when a role is assumed, but they're stored and set at different times:
| Trust policy | Session policy | |
|---|---|---|
| Stored where | On the Reader role | Not saved by AWS; it lives only with this session |
| Set how | create-role --assume-role-policy-document, later update-assume-role-policy | --policy on each assume-role call |
| Checked when | Every time someone assumes Reader | On every request made with these temporary credentials, until they expire (1 hour by default) |
| Decides | Who may assume Reader | What these credentials may do at most after the assume |
SCP
An SCP (service control policy) limits every IAM user and role below where it's attached. An organization looks roughly like this:
organization root
├── management account ← created the organization, pays the whole organization's bill
├── OU: prod
│ ├── account A
│ └── account B
└── OU: dev
└── account C
Say this SCP is attached to the organization root:
{
"Effect": "Deny",
"Action": "s3:DeleteBucket",
"Resource": "*"
}- A user in account A, B or C who calls
s3:DeleteBucketis denied, even if their identity-based policy allowss3:*. - Users and roles in the management account aren't affected when they call
s3:DeleteBucket. The SCP page says SCPs don't affect users or roles in the management account, or service-linked roles.
Attach the same SCP to OU: prod instead, and only accounts A and B are limited.
Because SCPs can't limit the management account, the Organizations best practices for the management account recommend keeping resources in other accounts.
RCP
An RCP (Resource Control Policy), added in November 2024, attaches to the account that owns the bucket and also limits accounts outside the organization. This one, from the RCP syntax page, denies any S3 request not made over HTTPS:
{
"Effect": "Deny",
"Principal": "*",
"Action": "s3:*",
"Resource": "*",
"Condition": { "BoolIfExists": { "aws:SecureTransport": "false" } }
}An RCP you write can only use Deny; Allow appears only in RCPFullAWSAccess, which AWS attaches automatically and which lets every request through. Like SCPs, RCPs don't affect resources in the management account (see the RCP page).
VPC endpoint policy
An S3 gateway endpoint lets EC2 instances in a VPC reach S3 without an internet gateway or NAT. The VPC endpoint policy on it limits what requests through it can reach. If the endpoint is created without a policy, AWS attaches a default one that allows everything. The VPC endpoint policy page says an endpoint policy must have a Principal, and for a gateway endpoint it can only be *. Say the endpoint policy on an S3 gateway endpoint is this:
{
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::reports/*"
}Code in the VPC going through that endpoint can read only reports. The endpoint policy only caps; whether Reader can read reports still comes down to its identity-based policy and the bucket policy.
What about "deny everyone except X"?
Principal has a negated form, NotPrincipal. This bucket policy denies everyone except Admin access to reports:
{
"Effect": "Deny",
"NotPrincipal": { "AWS": [
"arn:aws:iam::111122223333:root",
"arn:aws:iam::111122223333:role/Admin"
]},
"Action": "s3:*",
"Resource": ["arn:aws:s3:::reports", "arn:aws:s3:::reports/*"]
}The IAM NotPrincipal page allows NotPrincipal only with Deny, and never in an identity-based policy or a trust policy. It also recommends against NotPrincipal in new policies, in favour of "Principal": "*" with an ArnNotEquals condition on aws:PrincipalArn.
Which policies have rules of their own?
KMS key policy
Usually, if Reader's identity-based policy allows s3:GetObject and kms:Decrypt, it can read KMS-encrypted files (see the S3 SSE-KMS page).
That's because the default key policy has a statement whose Principal is the account itself (:root). Once the key policy allows the account, KMS looks at the account's identity-based policies (see the KMS default key policy page). If a hand-written key policy leaves this statement out, Reader is denied even with kms:Decrypt in its identity-based policy.
The + lines below are that statement:
{
"Statement": [
{
"Sid": "Allow access for Key Administrators",
...
},
+ {
+ "Sid": "Enable IAM User Permissions",
+ "Effect": "Allow",
+ "Principal": { "AWS": "arn:aws:iam::111122223333:root" },
+ "Action": "kms:*",
+ "Resource": "*"
+ }
]
}S3: identity policy || bucket policy || ACL
KMS: key policy names Reader || (key policy names :root && identity policy)
CloudFormation stack policy
A CloudFormation stack policy controls which resources a stack update may change. This one allows every update except deletes (example from the CloudFormation stack policy page):
{
"Effect": "Allow",
"NotAction": "Update:Delete",
"Principal": "*",
"Resource": "*"
}Principal is required but accepts only *, since there is no "who" to pick. The actions aren't a service's API either; there are three, Update:Modify, Update:Replace and Update:Delete.
What does Reader need to read reports/q3.pdf?
For Reader reading q3.pdf in the same account, the rules on the IAM policy evaluation page come out as a boolean expression, where any layer that isn't attached counts as true:
no Deny matches
&& (identity policy 1 || identity policy 2 || bucket policy || ACL)
&& permissions boundary
&& session policy
&& SCP && RCP && VPC endpoint policy
&& kms:Decrypt (if q3.pdf is encrypted with a KMS key)
Every Deny counts on the first line, whether it sits in the bucket policy, an identity policy or an SCP. The other lines look only at whether that policy has an Allow: the bucket policy in the parentheses, for example, asks whether the bucket policy has an Allow statement that permits this request.
The bucket policy in "Identity or resource" names Reader's role ARN (role/Reader) as Principal. Principal can also name an IAM user's ARN, or the ARN of one session after the assume (assumed-role/Reader/<session name>). A November 2026 test tried all three. An IAM user and a role were created in the test bucket's account with no identity policy attached, so only the bucket policy could let them read. The role ARN and the session ARN were each tested twice, once with a permissions boundary and once with a session policy. The IAM user calls with an access key and has no session, so it was tested with the boundary only. Both the boundary and the session policy allow only s3:ListBucket, not s3:GetObject, so by the expression above every case should be denied:
bucket policy Principal | with a permissions boundary | with a session policy |
|---|---|---|
IAM user ARN (user/...) | reads | n/a, a user calling directly has no session |
role ARN (role/Reader) | denied | denied |
role session ARN (assumed-role/Reader/<session name>) | reads | reads |
In the first and third rows the expression predicts a denial, but the read succeeds. When the bucket policy names an IAM user or role session ARN, the boundary and session policy only limit what identity policies grant, and lines two to four of the expression become:
&& ((identity policy 1 || identity policy 2) && permissions boundary && session policy
|| bucket policy || ACL)
The IAM permissions boundaries page lists the same three cases but doesn't say why a role ARN and a session ARN behave differently.
The IAM policy types page says "ACLs cannot grant permissions to entities within the same account". An ACL grant can go to a group (such as AllUsers or AuthenticatedUsers) or directly to an account, and the sentence doesn't say which it means. A November 2026 test tried the two group grants. The test IAM user was in the bucket's account with no policies attached; its ListObjectsV2 call was denied, so it had no other permission to use. It made signed reads of two objects, one whose ACL had only AllUsers: READ and one with only AuthenticatedUsers: READ, and got the content of both. So group grants count for same-account identities too, and the ACL term belongs in the parentheses. If the IAM sentence holds, it may mean grants made directly to an account; that kind wasn't tested.
Across accounts, the expression changes. Say Reader is in account A and reports in account B:
same account: identity policy 1 || identity policy 2 || bucket policy || ACL
cross-account: (identity policy 1 || identity policy 2) && (bucket policy || ACL)
Account A has to let Reader out, and account B has to let it in (see the IAM cross-account evaluation page).
With ACLs on, an Allow-only bucket policy is undone however precise it is
Say the bucket policy on reports lets in only Reader, and ACLs are still enabled. Someone uploads q3.pdf with --acl public-read:
aws s3 cp q3.pdf s3://reports/ --acl public-read
q3.pdf's ACL gains a grant:AllUsersmayREAD.- The bucket policy still names only
Reader. - Anyone can GET the file's URL, unsigned, and read it.
The grant looks like this. No Effect, no Action, no Condition:
<Grant>
<Grantee xsi:type="Group">
<URI>http://acs.amazonaws.com/groups/global/AllUsers</URI>
</Grantee>
<Permission>READ</Permission>
</Grant>The S3 ACL page says AllUsers means anyone, anonymous included. An anonymous request has no identity policy, so in the expression for Reader reading q3.pdf, the second line comes down to bucket policy || ACL. The bucket policy doesn't name the anonymous request, but ACL is true, so that line holds and the anonymous request can read. To stop it, add the Deny below to the bucket policy. The first line, "no Deny matches", then fails, the whole expression is false, and the anonymous request is denied. The IAM policy variables page says an anonymous request's aws:PrincipalType is Anonymous, so this denies only anonymous requests and leaves Reader alone:
{
"Effect": "Deny",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::reports/*",
"Condition": { "StringEquals": { "aws:PrincipalType": "Anonymous" } }
}Block Public Access: do public ACLs and bucket policies count?
Block Public Access is four switches, each on or off on its own (see the S3 Block Public Access page). All four deal only with public ACLs and bucket policies. The page says an ACL is public if it grants anything to AllUsers or AuthenticatedUsers. A November 2026 check with get-bucket-policy-status showed which bucket policies S3 counts as public. All of them allow s3:GetObject and differ only in Principal and Condition:
Principal | Condition | IsPublic |
|---|---|---|
"*" | none | True |
"*" | "aws:SecureTransport": "true" | True |
"*" | StringLike "aws:SourceVpc": "vpc-*" | True |
"*" | StringEquals "aws:SourceVpc": "vpc-91237329" | False |
"*" | StringEquals "aws:SourceAccount": "<account ID>" | False |
| an account ARN | none | False |
S3 treats a bucket policy as public by default and only calls it non-public when every Allow names a fixed party (no wildcard, no policy variable in the value). The party can be an ARN in Principal. With Principal: "*", a condition key from the page's list (such as aws:SourceAccount, aws:SourceVpc or aws:SourceIp) has to name it in Condition. vpc-* has a wildcard, so that policy is still public. aws:SecureTransport isn't on the list, so that one is public too. In the console's wording, two act on new ones and two on any:
BlockPublicAcls,BlockPublicPolicy(new): S3 rejects any attempt to write a public ACL or bucket policy. Existing ones are untouched.IgnorePublicAcls,RestrictPublicBuckets(any): existing ones aren't deleted, but stop working for outsiders. A public ACL doesn't count; a public bucket policy stops working for other accounts and anonymous requests, while same-account principals and AWS services can still use it (test below the same-account Reader table).
The account and the organization can set these switches too. An access point can as well, but its settings affect only requests through that access point. A switch on at any level counts as on: if the account has IgnorePublicAcls on, public ACLs in reports don't count even though the bucket has it off. At the organization level all four go on or off together.
The embed below runs top to bottom in the order S3 checks a request. Pick who is asking, flip the settings, and the result shows at the top.
Two roles in the embed don't read. With BlockPublicAcls on, the uploader's --acl public-read upload gets 403 AccessDenied. With BlockPublicPolicy on, the admin writing a Principal: "*" bucket policy also gets 403 AccessDenied. Three kinds of caller read: anonymous, a same-account Reader and an other-account Reader, one table each below. The assumptions match the embed: account-level Block Public Access is off, no SCP gets in the way, and the KMS key policy has only the default :root statement (see KMS key policy).
Anonymous, reading q3.pdf
| Condition | |
|---|---|
| At least one of two paths | ACL: ACLs on, the AllUsers grant exists, IgnorePublicAcls offpolicy: an Allow for Principal: "*", RestrictPublicBuckets off |
| and | no Deny matches the anonymous request |
| and | SSE-S3. With SSE-KMS, an anonymous request has no identity and can't get kms:Decrypt |
Same-account Reader, reading q3.pdf
| Condition | |
|---|---|
| At least one of these four holds | the IAM policy's Allow the bucket policy's statement for Reader the public statement the ACL path (ACLs on, the grant exists, IgnorePublicAcls off) |
| and | SSE-S3; or SSE-KMS with :root in the key policy and kms:Decrypt in the IAM policy |
Same-account requests aren't affected by RestrictPublicBuckets. The page says that with it on, S3 still allows "authorized users within the bucket owner's account", but doesn't define authorized. In the November 2026 test, RestrictPublicBuckets was on and the bucket policy had only a Principal: "*" Allow; a same-account IAM user with no policies read the object's content, while an anonymous request got 403. So even with no IAM permissions, a same-account IAM user counts as authorized.
Other-account Reader, reading q3.pdf
| Condition | |
|---|---|
| Reader's own account | the IAM policy has an Allow |
and at least one on the reports side | the statement for Reader the public statement the ACL path |
| and not | a public bucket policy with RestrictPublicBuckets on, which blocks cross-account access entirely |
| and | SSE-S3. The key policy's :root is the account that owns reports, so an other-account Reader can't get kms:Decrypt |
The 2023 defaults
Since April 2023, new buckets have all four on and ACLs disabled ("Bucket owner enforced"). With ACLs disabled:
- the
--acl public-readupload above fails with a 400AccessControlListNotSupported; - existing ACLs no longer take part in access evaluation; the
ACLterm in the expression is never true, and only the policies decide.
The takeaway
Next time AWS hands you a new "X policy," ask two questions:
- Does it name a who, with
PrincipalorNotPrincipal? If yes, it sits on a resource; if no, on an identity. SCP and RCP are the exception. - Does it grant access, or only cap it? If the docs say it does "not grant permissions," it only caps.
Then find its cell in the table at the top.