AWS Builder Center
Understanding AWS IAM Policies: JSON Structure Explained Simply

Understanding AWS IAM Policies: JSON Structure Explained Simply

Break down an IAM policy line by line so JSON permissions finally make sense.

Series: AWS Security 30 Days, 30 Articles Challenge (31 articles)

  1. …
  2. 5
    Understanding AWS IAM Policies: JSON Structure Explained Simply This article
Welcome to Day 4 of the 30 Days AWS Security Challenge. Over the last two days we talked about users, groups, and roles, and kept mentioning that policies are what actually grant permissions. Today we open one up and go through it piece by piece, so that wall of JSON stops looking intimidating.

Why Policies Look Scary at First

The first time most people open an IAM policy, it looks like a block of nested brackets and quotation marks with no obvious starting point. The good news is that almost every policy follows the same handful of fields, repeated in different combinations. Once you know what each field means, you can read any policy AWS throws at you.

The Basic Shape of a Policy

Here is a simple example that allows reading objects from one S3 bucket:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::my-example-bucket/*"
}
]
}
That's it. Four pieces of information are doing all the work here: Version, Effect, Action, and Resource. Let's go through each one.

Version: Just a Format Marker

The Version field is not the version of your policy, it is the version of the policy language AWS uses to parse it. In almost every case you will see "2012-10-17" here. You don't need to think about this field beyond including it, it is boilerplate.

Statement: The List of Rules

Statement holds an array of individual rules, called statements. A policy can have one statement or many. Each statement is its own self contained rule describing what is allowed or denied. Think of Statement as the container, and everything interesting happens inside each item in that array.

Effect: Allow or Deny

Effect is the simplest field and also the most important. It only ever has two values: "Allow" or "Deny." This single word decides whether the rest of the statement grants access or blocks it.
One thing worth knowing early: if a Deny exists anywhere that applies to a request, it always wins, even if another statement or policy says Allow. Deny beats Allow, every time. Keep that in mind once you start layering multiple policies together.

Action: What Can Be Done

Action lists the specific API operations the statement applies to. Each AWS service has its own set of actions, written as  service:ActionName . In our example,  s3:GetObject  means "download an object from S3."
You can list a single action, or an array of several:
"Action": ["s3:GetObject", "s3:ListBucket"]
You will also see wildcards, like  s3:* , meaning every S3 action. Wildcards are convenient but should be used carefully, since they grant more than most tasks actually need.

Resource: What It Applies To

Resource specifies exactly which AWS resource the action can be performed on, using something called an ARN, short for Amazon Resource Name. An ARN is just AWS's standardized way of pointing at a specific object, like one S3 bucket, one EC2 instance, or one DynamoDB table.
In our example,  arn:aws:s3:::my-example-bucket/*  means "every object inside my-example-bucket." Change that trailing  /*  and you can scope things down to a single specific file if needed.

Putting a Full Statement Together

Reading left to right, our example statement says: "Allow the action GetObject in S3, on any object inside my-example-bucket." That is the entire sentence a policy statement is built to say, just structured as JSON instead of English.
Once you can read one statement this way, you can read a policy with ten statements the same way, just one rule at a time.

A Quick Way to Practice

If you want to try building one yourself, open IAM > Policies > Create policy in the console and switch to the JSON tab. AWS will show you a blank template you can edit directly, and it validates the syntax as you type, which is a fast way to catch mistakes before you save anything.

Key Takeaways

  • Every policy is built from a small set of repeating fields: Version, Statement, Effect, Action, and Resource
  • Effect is either Allow or Deny, and Deny always overrides Allow when both apply
  • Action defines which specific API operations the rule covers
  • Resource defines which specific AWS resource, identified by its ARN, the rule applies to
  • Once you can read one statement, you can read any policy, it is just more of the same pattern repeated
Tomorrow we step away from JSON and look at something every single AWS account needs regardless of size: multi factor authentication, and why it is one of the highest value security steps you can take in a few minutes.

Series: AWS Security 30 Days, 30 Articles Challenge (31 articles)

  1. …
  2. 5
    Understanding AWS IAM Policies: JSON Structure Explained Simply This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article