Menu
AWS Identity and Access Management
User Guide

Testing IAM Policies with the IAM Policy Simulator

For more information about how and why to use IAM policies, see IAM Policies.

You can access the IAM Policy Simulator Console at: https://policysim.aws.amazon.com/

The following video provides an introduction to using the IAM policy simulator.

With the IAM policy simulator, you can test and troubleshoot IAM and resource-based policies in the following ways:

  • Test policies that are attached to IAM users, groups, or roles in your AWS account. If more than one policy is attached to the user, group, or role, you can test all the policies, or select individual policies to test. You can test which actions are allowed or denied by the selected policies for specific resources.

  • Test policies that are attached to AWS resources, such as Amazon S3 buckets, Amazon SQS queues, Amazon SNS topics, or Amazon Glacier vaults.

  • If your AWS account is a member of an AWS Organization, then you can test the impact of organization control policies on your IAM policies and resource policies.

  • Test new policies that are not yet attached to a user, group, or role by typing or copying them into the simulator. These are used only in the simulation and are not saved. Note: you cannot type or copy a resource-based policy into the simulator. To use a resource-based policy in the simulator, you must include the resource in the simulation and select the check box to include that resource's policy in the simulation.

  • Test the policies with selected services, actions, and resources. For example, you can test to ensure that your policy allows an entity to perform the ListAllMyBuckets, CreateBucket, and DeleteBucket actions in the Amazon S3 service on a specific bucket.

  • Simulate real-world scenarios by providing context keys, such as an IP address or date, that are included in Condition elements in the policies being tested.

  • Identify which specific statement in a policy results in allowing or denying access to a particular resource or action.

How the IAM Policy Simulator Works

The simulator evaluates the policies that you choose and determines the effective permissions for each of the actions that you specify. The simulator uses the same policy evaluation engine that is used during real requests to AWS services. But the simulator differs from the live AWS environment in the following ways:

  • The simulator does not make an actual AWS service request, so you can safely test requests that might make unwanted changes to your live AWS environment.

  • Because the simulator does not simulate running the selected actions it cannot report any response to the simulated request. The only result returned is whether the requested action would be allowed or denied.

  • If you edit a policy inside the simulator, these changes affect only the simulator. The corresponding policy in your AWS account remains unchanged.

Permissions Required for Using the IAM Policy Simulator

You can use the policy simulator console or the policy simulator API to test policies. By default, console users can test policies that are not yet attached to a user, group, or role by typing or copying those policies into the simulator. These policies are used only in the simulation and do not disclose sensitive information. API users must have permissions to test unattached policies. To allow console or API users to test policies that are attached to IAM users, groups, or roles in your AWS account, you must provide users with permissions to retrieve those policies. In order to test resource-based policies, users must have permission to retrieve the resource's policy.

For examples of console and API policies that allow a user to simulate policies, see Example Policies: AWS Identity and Access Management (IAM).

Permissions Required for Using the Policy Simulator Console

To allow users to test policies that are attached to IAM users, groups, or roles in your AWS account, you must provide your users with permissions to retrieve those policies. In order to test resource-based policies, users must have permission to retrieve the resource's policy.

To view an example policy that allows using the policy simulator console for policies that are attached to a user, group, or role, see IAM: Access the Policy Simulator Console.

To view an example policy that allows using the policy simulator console only for those users with a specific path, see IAM: Access the Policy Simulator Console Based on User Path.

To create a policy to allow using the policy simulator console for only one type of entity, use the following procedures.

To allow console users to simulate policies for users

Include the following actions in your policy:

  • iam:GetGroupPolicy

  • iam:GetPolicy

  • iam:GetPolicyVersion

  • iam:GetUser

  • iam:GetUserPolicy

  • iam:ListAttachedUserPolicies

  • iam:ListGroupsForUser

  • iam:ListGroupPolicies

  • iam:ListUserPolicies

  • iam:ListUsers

To allow console users to simulate policies for groups

Include the following actions in your policy:

  • iam:GetGroup

  • iam:GetGroupPolicy

  • iam:GetPolicy

  • iam:GetPolicyVersion

  • iam:ListAttachedGroupPolicies

  • iam:ListGroupPolicies

  • iam:ListGroups

To allow console users to simulate policies for roles

Include the following actions in your policy:

  • iam:GetPolicy

  • iam:GetPolicyVersion

  • iam:GetRole

  • iam:GetRolePolicy

  • iam:ListAttachedRolePolicies

  • iam:ListRolePolicies

  • iam:ListRoles

To test resource-based policies, users must have permission to retrieve the resource's policy.

To allow console users to test resource-based policies in an Amazon S3 bucket

Include the following actions in your policy:

  • s3:GetBucketPolicy

  • s3:GetObjects

For example, the following policy uses these actions to allow console users to simulate a resource-based policy in a specific Amazon S3 bucket.

Copy
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "s3:GetBucketPolicy", "s3:GetObjects" ], "Effect": "Allow", "Resource":"arn:aws:s3:::<BUCKET-NAME>/*" } ] }

To allow console users to test policies for AWS Organizations

Include the following actions in your policy:

  • organizations:DescribePolicy

  • organizations:ListPolicies

  • organizations:ListPoliciesForTarget

  • organizations:ListTargetsForPolicy

Permissions Required for Using the Policy Simulator API

The policy simulator API actions GetContextKeyForCustomPolicy and SimulateCustomPolicy allow users to test policies that are not yet attached to a user, group, or role by passing the policies as strings to the API. These policies are used only in the simulation and do not disclose sensitive information. To allow API users to test policies that are attached to IAM users, groups, or roles in your AWS account, you must provide users with permissions to call GetContextKeyForPrincipalPolicy and SimulatePrincipalPolicy.

To view an example policy that allows using the policy simulator API for unattached policies and policies attached to a user, group, or role in the current AWS account, see IAM: Access the Policy Simulator API.

To create a policy to allow using the policy simulator API for only one type of policy, use the following procedures.

To allow API users to simulate policies passed directly to the API as strings

Include the following actions in your policy:

  • iam:GetContextKeysForCustomPolicy

  • iam:SimulateCustomPolicy

To allow API users to simulate policies attached to IAM users, groups, roles, or resources

Include the following actions in your policy:

  • iam:GetContextKeysForPrincipalPolicy

  • iam:SimulatePrincipalPolicy

For example, to give a user named Bob permission to simulate a policy that is assigned to a user named Alice, give Bob access to the following resource: arn:aws:iam::777788889999:user/alice.

To view an example policy that allows using the policy simulator API only for those users with a specific path, see IAM: Access the Policy Simulator API Based on User Path.

Using the IAM Policy Simulator (AWS Management Console)

By default, users can test policies that are not yet attached to a user, group, or role by typing or copying those policies into the policy simulator console. These policies are used only in the simulation and do not disclose sensitive information.

To test a policy that is not attached to a user, group, or role using the policy simulator console:

  1. Open the IAM policy simulator console at: https://policysim.aws.amazon.com/.

  2. In the Mode: menu at the top of the page, choose New Policy.

  3. In the Policy Sandbox, choose Create New Policy.

  4. Type or copy a policy into the simulator, and use the simulator as described in the following steps.

After you have been given the required permissions for using the IAM Policy Simulator Console, you can use the simulator to test an IAM user, group, role, or resource policy.

To use the policy simulator console:

  1. Open the IAM policy simulator console at https://policysim.aws.amazon.com/.

    Note

    To sign in to the policy simulator as an IAM user, use your unique sign-in URL to sign in to the AWS Management Console. Then go to https://policysim.aws.amazon.com/. For more information about signing in as an IAM user, see How IAM Users Sign In to AWS.

    The simulator opens in Existing Policies mode and lists the IAM users in your account under Users, Groups, and Roles.

  2. Choose the option that is appropriate to your task:

    To test this: Do this:
    A policy attached to a user Choose Users in the Users, Groups, and Roles list. Then choose the user.
    A policy attached to a group Choose Groups in the Users, Groups, and Roles list. Then choose the group.
    A policy attached to a role Choose Roles in the Users, Groups, and Roles list. Then choose the role.
    A policy attached to a resource See Step 8.
    A custom policy Choose New Policy from the mode list at the top. Then, in the Policy Sandbox pane on the left, choose Create New Policy, type or paste a policy, then choose Apply.

    Tip

    To test a policy that is attached to group, you can launch the IAM policy simulator directly from the IAM console: In the navigation pane, choose Groups. Choose the name of the group that you want to test a policy on, and then choose the Permissions tab. In the Inline Policies or Managed Policies section, locate the policy that you want to test. In the Actions column for that policy, choose Simulate Policy.

    To test a customer managed policy that is attached to a user: In the navigation pane, choose Users. Choose the name of the user that you want to test a policy on. Then choose the Permissions tab and expand the policy that you want to test. On the far right, choose Simulate policy. The IAM Policy Simulator opens in a new window and displays the selected policy in the Policies pane.

  3. (Optional) If your account is a member of an AWS Organization, then any organization control policies (OCPs) that affect the simulated user's account appear in the Policies pane along with IAM policies and Resource policies. These policies are essentially filters that restrict what permissions can be used by users, groups, or roles in an affected account. If an OCP blocks a service or action, then no entity in that account can access that service nor perform that action. This is true even if an administrator explicitly grants permissions to that service or action through an IAM or resource policy. To remove an OCP from the simulation, clear the check box next to the OCP name. To view the OCP contents, choose the name of the OCP.

    If your account is not a member of an organization, then there are no OCPs to simulate.

  4. (Optional) To test only a subset of policies attached to a user, group, or role, in the Policies pane clear the check box next to each policy that you want to exclude.

  5. Under Policy Simulator, choose Select service and then choose the service to test. Then choose Select actions and select one or more actions to test. Although the menus show the available selections for only one service at a time, all the services and actions that you have selected appear in Action Settings and Results.

  6. (Optional) If any of the policies that you choose in Step 2 and Step 4 include conditions with AWS global condition keys, then supply values for those keys. You can do this by by expanding the Global Settings section and typing values for the key names displayed there.

    Warning

    If you leave the value for a condition key empty, then that key is ignored during the simulation. In some cases, this results in an error and the simulation fails to run. In other cases the simulation runs, but the results might not be reliable because the simulation does not match the real-world conditions that include a value for the condition key or variable.

  7. (Optional) Each selected action appears in the Action Settings and Results list with Not simulated shown in the Permission column until you actually run the simulation. Before you run the simulation, you can configure each action with a resource. To configure individual actions for a specific scenario, choose the arrow to expand the action's row. If the action supports resource-level permissions, you can type the Amazon Resource Name (ARN) of the specific resource whose access you want to test. By default, each resource is set to a wildcard (*). You can also specify a value for any condition context keys. As noted previously, keys with empty values are ignored, which can cause simulation failures or unreliable results.

    1. Choose the arrow next to the action name to expand each row and configure any additional information required to accurately simulate the action in your scenario. If the action requires any resource-level permissions, you can type the Amazon Resource Name (ARN) of the specific resource that you want to simulate access to. By default, each resource is set to a wildcard (*).

    2. If the action supports resource-level permissions but does not require them, then you can choose Add Resource to select the resource type that you want to add to the simulation.

    3. If any of the selected policies include a Condition element that references a context key for this action's service, then that key name is displayed under the action. You can specify the value to be used during the simulation of that action for the specified resource.

    Actions that require different groups of resource types

    Some actions require different resource types under different circumstances. Each group of resource types is associated with a scenario. If one of these applies to your simulation, select it and the simulator requires the resource types appropriate for that scenario. The following list shows each of the supported scenario options and the resources that you must define to run the simulation.

    Each of the following Amazon EC2 scenarios requires that you specify instance, image, and security-group resources. If your scenario includes an EBS volume, then you must specify that volume as a resource. If the Amazon EC2 scenario includes a virtual private cloud (VPC), then you must supply the network-interface resource. If it includes an IP subnet, then you must specify the subnet resource. For more information on the Amazon EC2 scenario options, see Supported Platforms in the AWS EC2 User Guide.

    • EC2-Classic-InstanceStore

      instance, image, security-group

    • EC2-Classic-EBS

      instance, image, security-group, volume

    • EC2-VPC-InstanceStore

      instance, image, security-group, network-interface

    • EC2-VPC-InstanceStore-Subnet

      instance, image, security-group, network-interface, subnet

    • EC2-VPC-EBS

      instance, image, security-group, network-interface, volume

    • EC2-VPC-EBS-Subnet

      instance, image, security-group, network-interface, subnet, volume

  8. (Optional) If you want to include a resource-based policy in your simulation, then you must first select the actions that you want to simulate on that resource in Step 5. Expand the rows for the selected actions, and type the ARN of the resource with a policy that you want to simulate. Then select Include Resource Policy next to the ARN text box. The IAM policy simulator currently supports resource-based policies from only the following services: Amazon S3 (resource-based policies only; ACLs are not currently supported), Amazon SQS, Amazon SNS, and unlocked Amazon Glacier vaults (locked vaults are not currently supported).

  9. Choose Run Simulation in the upper-right corner.

    The Permission column in each row of Action Settings and Results displays the result of the simulation of that action on the specified resource.

  10. To see which statement in a policy explicitly allowed or denied an action, choose the N matching statement(s) link in the Permissions column to expand the row. Then choose the Show statement link. The Policies pane shows the relevant policy with the statement that affected the simulation result highlighted.

    Note

    If an action is implicitly denied—that is, if the action is denied only because it is not explicitly allowed—the List and Show statement options are not displayed.

Troubleshooting IAM Policy Simulator Console Messages

The following table lists the informational and warning messages you might encounter when using the IAM policy simulator. The table also provides steps you can take to resolve them.

Message Steps to resolve
This policy has been edited. Changes will not be saved to your account.

No action required.

This message is informational. If you edit an existing policy in the IAM policy simulator, your change does not affect your AWS account. The simulator allows you to make changes to policies for testing purposes only.

Cannot get the resource policy. Reason: detailed error message The simulator is not able to access a requested resource-based policy. Ensure that the specified resource ARN is correct and that the user running the simulation has permission to read the resource's policy.
One or more policies require values in the simulation settings. The simulation might fail without these values.

This message appears if the policy you are testing contains condition keys or variables but you have not entered any values for these keys or variables in Simulation Settings.

To dismiss this message, choose Simulation Settings, Then type a value for each condition key or variable.

You have changed policies. These results are no longer valid.

This message appears if you have changed the selected policy while results are displayed in the Results pane. Results shown in the Results pane are not updated dynamically.

To dismiss this message, choose Run Simulation again to display new simulation results based on the changes made in the Policies pane.

The resource you entered for this simulation does not match this service.

This message appears if you have entered an Amazon Resource Name (ARN) in the Simulation Settings pane that does not match the service that you chose for the current simulation. For example, this message appears if you specify an ARN for an Amazon DynamoDB resource but you chose Amazon Redshift as the service to simulate.

To dismiss this message, do one of the following:

  • Remove the ARN from the box in the Simulation Settings pane.

  • Choose the service that matches the ARN that you specified in Simulation Settings.

This action belongs to a service that supports special access control mechanisms in addition to resource-based policies, such as S3 ACLs or Glacier vault lock policies. The policy simulator does not support these mechanisms, so the results can differ from your production environment.

No action required.

This message is informational. In the current version, the simulator evaluates policies attached to users and groups, and can evaluate resource-based policies for Amazon S3, Amazon SQS, Amazon SNS, and Amazon Glacier. The policy simulator does not support all access control mechanisms supported by other AWS services.

DynamoDB FGAC is currently not supported.

No action required.

This informationl message refers to fine-grained access control. This is the ability to use IAM policy conditions to determine who can access individual data items and attributes in DynamoDB tables and indexes as well as the actions that can be performed on them. The current version of the IAM policy simulator does not support this type of policy condition. For more information on DynamoDB fine-grained access control, see Fine-Grained Access Control for DynamoDB.

You have policies that do not comply with the policy syntax. You can use the Policy Validator to review and accept the recommended updates to your policies.

This message appears at the top of the policy list if you have policies that do not comply with the IAM policy grammar. In order to simulate these policies, follow the instructions at Validating JSON Policies to identify and fix these policies.

This policy must be updated to comply with the latest policy syntax rules.

This message is displayed if you have policies that do not comply with the IAM policy grammar. In order to simulate these policies, follow the instructions at Validating JSON Policies to identify and fix these policies.

Using the IAM Policy Simulator (AWS CLI, Tools for Windows PowerShell, and AWS API)

Policy simulator commands typically require calling APIs to do two things:

  1. Evaluate the policies and return the list of context keys that they reference. You need to know what context keys are referenced so that you can supply values for them in the next step.

  2. Simulate the policies, providing a list of actions, resources, and context keys that are used during the simulation.

For security reasons, the APIs have been broken into two groups:

In both cases, the API actions simulate the effect of one or more policies on a list of actions and resources. Each action is paired with each resource and the simulation determines whether the policies allow or deny that action for that resource. You can also provide values for any context keys that your policies reference. You can get the list of context keys that the policies reference by first calling GetContextKeysForCustomPolicy or GetContextKeysForPrincipalPolicy. If you don't provide a value for a context key, the simulation still runs. But the results might not be reliable because the simulator cannot include that context key in the evaluation.

To get the list of context keys

Use these commands to evaluate a list of policies and return a list of context keys that are used in the policies.

To simulate IAM policies

Use these commands to simulate IAM policies to determine a user's effective permissions.