How do I use the IAM policy simulator to test IAM policies and permissions?

Resolution

You can use the IAM policy simulator console or the AWS Command Line Interface (AWS CLI) to test identity-based policies and permissions boundaries.

IAM policy simulator has the following limitations:

• You can only simulate one permissions boundary at a time.
• You can't test service control policies (SCPs) with any conditions or simulate cross-account access.
• Policy simulator results can differ from your live AWS environment

For more information, see How the IAM policy simulator works.

IAM policy simulator permissions

Note: If you receive errors when you run AWS CLI commands, see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

You must provide permission to test policies that are attached to IAM identities in your AWS account. Attach a policy to your IAM user or role to grant permissions to simulate policies similar to the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Action": [
        "iam:GetContextKeysForPrincipalPolicy",
        "iam:SimulatePrincipalPolicy"
      ],
      "Effect": "Allow",
      "Resource": [
        "*"
      ]
    }
  ]
}

For more example policies to allow access to use the IAM policy simulator, see Example policies: AWS Identity and Access Management (IAM).

For more information on IAM policy simulator permissions, see Permissions required for using the IAM policy simulator.

Use the IAM policy simulator with the console

By default, you can test policies that aren't attached to IAM users and groups without additional permissions. To test policies that are attached to IAM users or groups, you must have permissions.

For instructions to use the IAM policy simulator with the console, see Using the IAM policy simulator (console).

Use the IAM policy simulator with the AWS CLI

To simulate a current IAM policy entity, run the simulate-principal-policy AWS CLI command:

aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::444455556666:user/USER --action-names "s3:PutObject" "ec2:DescribeInstances"

Note: Replace USER with your IAM user.

Simulate resource-based policies

IAM policy simulator supports resource-based policies for the following AWS services:

• Amazon Simple Storage Service (Amazon S3)
• Amazon Simple Queue Service (Amazon SQS)
• Amazon Simple Notification Service (Amazon SNS)
• Unlocked Amazon S3 Glacier vaults

1. To define the contents of the resource-based policy, copy and paste the following statement into a text editor and save it as a JSON file:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": "arn:aws:iam::444455556666:user/example-user",
         "Action": "s3:PutObject",
         "Resource": [
           "amzn-s3-demo-bucket",
           "amzn-s3-demo-bucket/*"
         ]
       }
     ]
   }

2. Run the simulate-principal-policy AWS CLI command with the JSON file that you created in the previous step.

   aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::444455556666:user/USER --action-names "s3:PutObject" --resource-policy file://resource-policy.json --resource-arns arn:amzn-s3-demo-bucket

Get a list of additional policy documents to simulate

In addition to the policy documents included for your IAM entities, you can get a list of additional policy documents to simulate.

1. To define the contents of the additional policy, copy and paste the following statement into a text editor and save it as a JSON file:

   {"Version": "2012-10-17", "Statement": [{"Effect": "Allow", "Principal": "arn:aws:iam::444455556666:user/USER", "Action": "s3:", "Resource": ["arn:amzn-s3-demo-bucket", "arn:amzn-s3-demo-bucket/*"], "Condition": {"Bool": {"aws:SecureTransport": "false"}}}]

2. Run the simulate-principal-policy AWS CLI command with the JSON file that you created in the previous step:

   aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::444455556666:user/USER --action-names "s3:PutObject" --resource-policy file://resource-policy.json --resource-arns arn:amzn-s3-demo-bucket

Get a list of permissions boundaries to simulate

You can include a list of permissions boundaries to simulate for your IAM entities.

1. To define the contents of the permissions boundaries, copy and paste the following statement into a text editor and save it as a JSON file:

   ["{\"Version\": \"2012-10-17\", \"Statement\": [{\"Effect\": \"Allow\", \"Action\": [\"ec2:*\", \"iam:*\", \"s3:*\"], \"Resource\": \"*\"}]}"]

2. Run the simulate-principal-policy AWS CLI command with the JSON file that you created in the previous step:

   aws iam simulate-principal-policy --policy-source-arn arn:aws:iam::444455556666:user/USER --action-names "s3:PutObject" "ec2:DescribeInstances" --permissions-boundary-policy-input-list file://resource-policy.json 

Related information

Policy evaluation logic

IAM: Access the policy simulator API

Troubleshooting IAM policies