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 Overview of IAM Policies.

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.

  • 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

By default, any user that can access the AWS console can use the simulator to test policies that are not yet attached to a user, group, or role. Just choose New Policy from the mode menu at the top, choose Create New Policy under Policy Sandbox, and type or copy a policy into the simulator. Policies added here are used only in the simulation so that no sensitive information is disclosed.

To allow a console user to test policies that are attached to IAM users, groups, or roles, you must provide your users with permissions to retrieve those policies. To allow console users to test resource-based policies, you must provide your users with permission to retrieve the resource's policy.

To allow console users to simulate policies for a user

  1. For inline policies, grant permissions to take the following actions:
    ListUsers
    GetUser
    GetUserPolicy
  2. For managed policies, grant permission to take the following actions:
    ListUsers
    GetUser
    GetPolicy

To allow console users to test resource-based policies

Grant permission to retrieve the resource's policy.

For example, to simulate resource-based policies in an Amazon S3 bucket, you must allow the user to take the following actions:

s3:GetBucketPolicy
s3:GetObjects

For examples of policies that allow a console user to simulate policies, see Allow Users to Access the Policy Simulator.

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

Grant permissions to take the following actions:

GetContextKeysForCustomPolicy
SimulateCustomPolicy

To allow users to access APIs that simulate the policies attached to a specified IAM user, group, role, or resource

Grant permissions to take the following actions:

GetContextKeysForPrincipalPolicy
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.

For examples of API policies that allow a user to simulate policies, see Allow Users to Access the Policy Simulator APIs.

Using the IAM Policy Simulator (AWS Management Console)

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

To use the policy simulator:

  1. Open the IAM policy simulator at https://policysim.aws.amazon.com/. (If you are not already signed in to AWS, you are prompted to sign in).

    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 Your AWS Account.

    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 userChoose Users in the Users, Groups, and Roles list. Then choose the user.
    A policy attached to a groupChoose Groups in the Users, Groups, and Roles list. Then choose the group.
    A policy attached to a roleChoose Roles in the Users, Groups, and Roles list. Then choose the role.
    A policy attached to a resourceSee Step 7.
    A custom policySelect New Policy from the mode list in the top right corner. Then, in the Policy Sandbox pane on the left, click Create New Policy, enter or paste a policy, then click Apply.

    Tip

    If you want to test a policy that is attached to a user or group, you can launch the IAM policy simulator directly from the IAM console: In the navigation pane, click Users or Groups. Choose the name of the user or group that you want to test a policy on, and then scroll down to the Permissions section. 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. The IAM Policy Simulator opens in a new window and displays the selected policy in the Policies pane.

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

  4. Under Policy Simulator, click Select service and then choose the service to test. Then click 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 Setttings and Results. If you return to a for which you selected actions, the Select actions menu continues to show your selections.

  5. (Optional) If any of the policies that you choose in Step 2 and Step 3 test the value of global AWS context keys in a Condition element, then the key names appear in the Global Settings section. You can supply values for those keys by expanding the Global Settings section and typing values for the key names displayed there.

    Caution

    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.

  6. (Optional) Each selected action appears in the 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, click 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 that you want to simulate access to. By default, each resource is set to a wildcard (*). You can also specify a value for any context keys that are referenced by the policy's Condition element. As noted previously, keys with empty values are ignored, which can cause simulation failures or unreliable results.

    1. Expand each row by clicking the arrow next to the action name to 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 a resource-level permissions but does not require it, then you can choose the Add Resource button to select the resource type 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 against 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 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 EC2 scenario includes 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 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

  7. (Optional) If you want to include a resource-based policy in your simulation, then you must first select the actions you want to simulate on that resource in Step 4. 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).

  8. 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.

  9. 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, and 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.

MessageSteps 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 messageThe 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, click Simulation Settings, then enter 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 do not update dynamically.

To dismiss this message, click 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 you chose for the current simulation. For example, this message appears if you specify an ARN for a Amazon DynamoDB resource but you chose Amazon Redshift as the service to simulate, you will see this message.

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 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 message is informational. It refers to fine-grained access control, which 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 is displayed 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 Using Policy Validator 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 Using Policy Validator 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 APIs 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

These commands evaluate a list of policies and return a list of context keys used in the policies.

To simulate IAM policies

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