Policy Document Structure & Conditions

An IAM policy is a JSON document, and every useful policy beyond a toy example needs Condition blocks to be precise.

This page covers the document's anatomy, the condition operators you'll actually use, and how context keys let one policy adapt to who's calling and from where.

Summary

A policy document is a Version plus one or more Statement blocks.

Each statement has an Effect (Allow or Deny), an Action list, a Resource list, and an optional Condition block.

Condition is where most of the precision lives: it tests values from the request itself, like the caller's IP, a tag on the principal, or the current time.

Getting the operator right (StringEquals vs StringLike, exact match vs wildcard) is the difference between a condition that quietly never matches and one that actually constrains access.

boto3 and the AWS SDK for JavaScript v3 both just serialize this same JSON shape into a string for PutRolePolicy or CreatePolicy - the document itself is language-neutral.

Recipe

Quick-reference recipe card - copy-paste ready.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadFromCorpNetworkOnly",
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::acme-reports/*",
      "Condition": {
        "IpAddress": { "aws:SourceIp": "203.0.113.0/24" },
        "DateGreaterThan": { "aws:CurrentTime": "2026-01-01T00:00:00Z" },
        "Bool": { "aws:MultiFactorAuthPresent": "true" }
      }
    }
  ]
}

When to reach for this:

• Restricting an already-scoped Allow to a specific network range, time window, or MFA state.
• Making one policy adapt per caller using tags instead of writing one statement per user.
• Requiring encryption or a specific region on an otherwise permitted action.
• Passing a security review that flags an unconditioned broad Allow.

Working Example

Attach a conditioned inline policy, then verify the condition actually narrows the decision.

# --- Python (boto3) ---
import json, boto3
 
iam = boto3.client("iam")
ROLE = "reports-reader-role"
 
policy = {
    "Version": "2012-10-17",
    "Statement": [{
        "Sid": "TaggedTenantAccess",
        "Effect": "Allow",
        "Action": ["s3:GetObject"],
        "Resource": "arn:aws:s3:::acme-reports/*",
        "Condition": {
            "StringEquals": {
                "aws:PrincipalTag/team": "billing",
                "aws:RequestedRegion": "us-east-1"
            }
        }
    }]
}
 
iam.put_role_policy(
    RoleName=ROLE,
    PolicyName="tagged-tenant-access",
    PolicyDocument=json.dumps(policy),
)
 
# Confirm the condition holds for a matching context.
res = iam.simulate_principal_policy(
    PolicySourceArn=f"arn:aws:iam::111122223333:role/{ROLE}",
    ActionNames=["s3:GetObject"],
    ResourceArns=["arn:aws:s3:::acme-reports/q3.csv"],
    ContextEntries=[{
        "ContextKeyName": "aws:PrincipalTag/team",
        "ContextKeyValues": ["billing"],
        "ContextKeyType": "string",
    }],
)
print(res["EvaluationResults"][0]["EvalDecision"])  # -> allowed

// --- TypeScript (AWS SDK v3) ---
import {
  IAMClient, PutRolePolicyCommand, SimulatePrincipalPolicyCommand,
} from "@aws-sdk/client-iam";
 
const iam = new IAMClient({});
const ROLE = "reports-reader-role";
 
const policy = {
  Version: "2012-10-17",
  Statement: [{
    Sid: "TaggedTenantAccess",
    Effect: "Allow",
    Action: ["s3:GetObject"],
    Resource: "arn:aws:s3:::acme-reports/*",
    Condition: {
      StringEquals: {
        "aws:PrincipalTag/team": "billing",
        "aws:RequestedRegion": "us-east-1",
      },
    },
  }],
};
 
await iam.send(new PutRolePolicyCommand({
  RoleName: ROLE, PolicyName: "tagged-tenant-access",
  PolicyDocument: JSON.stringify(policy),
}));
 
const res = await iam.send(new SimulatePrincipalPolicyCommand({
  PolicySourceArn: `arn:aws:iam::111122223333:role/${ROLE}`,
  ActionNames: ["s3:GetObject"],
  ResourceArns: ["arn:aws:s3:::acme-reports/q3.csv"],
  ContextEntries: [{
    ContextKeyName: "aws:PrincipalTag/team",
    ContextKeyValues: ["billing"],
    ContextKeyType: "string",
  }],
}));
console.log(res.EvaluationResults?.[0]?.EvalDecision); // -> allowed

What this demonstrates:

• aws:PrincipalTag/team reads a tag on the calling principal, letting one policy serve every "billing" tagged role without duplicating statements.
• aws:RequestedRegion constrains which region the call must target, independent of where the client happens to run.
• ContextEntries in the simulator lets you supply a tag value that wouldn't otherwise be present on a test principal.
• StringEquals requires an exact match - a caller tagged Billing (capitalized) would not match this condition.

Deep Dive

How It Works

• Each Statement is evaluated independently; a Condition only applies to its own statement, never leaking into others.
• IAM evaluates every key inside a Condition block with implicit AND - all keys must be satisfied for the condition to match.
• Within one condition key, an array of values is implicit OR - matching any one value satisfies that key.
• A Condition can only ever narrow what Action/Resource already scoped - it cannot grant access to something outside them.
• If a context key referenced in a condition is absent from the request (for example, a tag that doesn't exist on the caller), most operators simply fail to match rather than erroring.

Condition Operators at a Glance

Common Global Context Keys

• aws:PrincipalTag/<key> - a tag on the IAM principal making the call, useful for team- or environment-scoped conditions.
• aws:RequestedRegion - the region the API call targets, independent of client location.
• aws:SourceIp - the caller's IP address, commonly paired with IpAddress.
• aws:MultiFactorAuthPresent - whether the session used MFA, paired with Bool.
• aws:CurrentTime - the request timestamp, paired with DateGreaterThan/DateLessThan for time-boxed access.

Python & TypeScript Notes

# boto3 accepts PolicyDocument as a JSON string - always json.dumps() the dict.
# A common mistake is passing the dict directly, which raises a botocore
# serialization error rather than a clear "must be a string" message.
policy_str = json.dumps(policy)

// SDK v3 has the identical requirement - JSON.stringify() before sending.
// TypeScript won't catch a missing stringify at compile time since PolicyDocument is typed `string`,
// but passing an object literal instead fails type-checking, which is the safety net here.
const policyStr = JSON.stringify(policy);

Gotchas

• Using StringEquals when the value has variable casing - StringEquals is case-sensitive, so Billing will not match billing. Fix: normalize tag values at creation time, or use StringEqualsIgnoreCase.
• Forgetting Condition keys are ANDed together - stacking IpAddress and DateGreaterThan in one block requires both to hold, not either. Fix: split into separate statements if you actually want OR semantics across conditions.
• Referencing a tag key that doesn't exist on some principals - the condition silently fails to match for those principals rather than erroring. Fix: use ...IfExists operator variants (e.g. StringEqualsIfExists) when a key may be legitimately absent.
• Confusing aws:CurrentTime with a one-time expiration - a DateLessThan condition doesn't "expire" the policy; it just re-evaluates against the current time on every request. Fix: treat it as a standing time window, not a TTL.
• Passing PolicyDocument as an object instead of a string - both boto3 and SDK v3 require a JSON string. Fix: always call json.dumps() / JSON.stringify() before sending.
• Assuming a Condition can grant broader access - a Condition can only restrict; it never adds permissions beyond what Action/Resource already allow. Fix: widen Action/Resource directly if more access is actually needed.

Alternatives

FAQs

Related

• IAM's Policy Evaluation Logic - how a Condition fits into the larger allow/deny decision.
• IAM Advanced Basics - attaching the policies these documents describe.
• Permission Boundaries for Delegated Admin - a ceiling that conditions cannot override.
• Cross-Account Roles & Resource-Based Policies - conditions on the resource side of a policy.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).