How to Use IAM Policy Simulator in AWS: Step-by-Step Guide

Use the AWS IAM Policy Simulator to test permissions by selecting a user, group, or role and simulating actions on AWS services. It helps verify if policies allow or deny specific actions without affecting live resources.

Syntax

The IAM Policy Simulator uses a simple interface or API calls to test policies. The main parts are:

• Principal: The user, group, or role whose permissions you want to test.
• Actions: AWS service actions you want to simulate (like s3:PutObject).
• Resources: The specific AWS resources to test against (like an S3 bucket ARN).
• Context: Optional key-value pairs that affect policy evaluation.

You can use the AWS Management Console or AWS CLI to run simulations.

bash

aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::123456789012:user/Alice --action-names s3:PutObject --resource-arns arn:aws:s3:::example-bucket/*

Example

This example uses the AWS CLI to simulate if user Alice can upload objects to the S3 bucket named example-bucket. It shows whether the action is allowed or denied.

bash

aws iam simulate-principal-policy \
  --policy-source-arn arn:aws:iam::123456789012:user/Alice \
  --action-names s3:PutObject \
  --resource-arns arn:aws:s3:::example-bucket/*

Output

{
    "EvaluationResults": [
        {
            "EvalActionName": "s3:PutObject",
            "EvalResourceName": "arn:aws:s3:::example-bucket/*",
            "EvalDecision": "allowed",
            "MatchedStatements": [
                {
                    "SourcePolicyId": "Policy",
                    "StartPosition": {
                        "Line": 5,
                        "Column": 3
                    },
                    "EndPosition": {
                        "Line": 10,
                        "Column": 3
                    }
                }
            ],
            "MissingContextValues": []
        }
    ]
}

Common Pitfalls

Common mistakes when using the IAM Policy Simulator include:

• Testing the wrong principal ARN, which leads to incorrect results.
• Not specifying the correct resource ARN, causing the simulation to miss resource-specific restrictions.
• Ignoring context keys that affect policy decisions, such as IP address or MFA status.
• Assuming simulation results apply to all AWS regions without checking regional resource ARNs.

Always double-check ARNs and include all relevant context for accurate simulation.

bash

Wrong:
aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::123456789012:user/Bob --action-names s3:PutObject --resource-arns arn:aws:s3:::example-bucket/*

Right:
aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::123456789012:user/Alice --action-names s3:PutObject --resource-arns arn:aws:s3:::example-bucket/*

Quick Reference

• Principal ARN: The IAM user, group, or role to test.
• Action Names: AWS actions like s3:GetObject, ec2:StartInstances.
• Resource ARNs: Specific resources like S3 buckets or EC2 instances.
• Context Keys: Optional conditions like IP address or MFA.
• Use Console: Navigate to IAM > Policy Simulator for a visual tool.
• Use CLI: Use aws iam simulate-principal-policy for scripting.

Key Takeaways

Use the IAM Policy Simulator to safely test permissions without changing live access.

Always specify the correct principal, actions, and resource ARNs for accurate results.

Include context keys if your policies depend on conditions like IP or MFA.

You can use both AWS Console and CLI to run simulations.

Review simulation results carefully to understand which policies allow or deny actions.