Test role changes with Policy Simulator

This page describes how to simulate a change to an IAM allow policy using Policy Simulator. It also explains how to interpret the results of the simulation, and how to apply the simulated allow policy if you choose to.

This feature only evaluates access based on allow policies.

To learn how to simulate changes to other types of policies, see the following:

Before you begin

  • Enable the Policy Simulator and Resource Manager APIs.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the APIs

  • Optional: Learn how Policy Simulator for allow policies works.

Required permissions

Before you simulate a change to an allow policy, you need to make sure you have the appropriate permissions. Certain permissions are required to run a simulation; others are not required, but help you get the most complete results from the simulation.

To learn more about Identity and Access Management (IAM) roles, see Understanding roles.

Required target resource permissions

The target resource of the simulation is the resource whose allow policies you're simulating.

To get the permissions that you need to run a simulation, ask your administrator to grant you the following IAM roles on the target resource:

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to run a simulation. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to run a simulation:

  • cloudasset.assets.searchAllResources
  • policysimulator.replays.run
  • service.resource.getIamPolicy, where resource is the resource type of the target resource and service is the name of the Google Cloud service that owns that resource.
  • Apply simulated policy changes: service.resource.setIamPolicy, where resource is the resource type of the target resource and service is the name of the Google Cloud service that owns that resource.

You might also be able to get these permissions with custom roles or other predefined roles.

Required host resource permissions

The host resource of a simulation is the project, folder, or organization that creates and runs the simulation. The host resource does not need to be related to the target resource in any way.

The way you set the host resource depends on the platform you're using.

Console

The host resource is the project, folder, or organization that appears in the resource selector.

To change the host resource, choose a different project, folder, or organization in the resource selector.

gcloud

The host resource is the current quota project. To set the quota project, use the gcloud auth application-default set-quota-project command.

REST

You manually specify the host resource each time you send a request. See Simulating a policy change on this page for details.

To get the permissions that you need to run a simulation, ask your administrator to grant you the Simulator Admin (roles/policysimulator.admin) IAM role on the host resource. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to run a simulation. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to run a simulation:

  • policysimulator.replayResults.list
  • policysimulator.replays.create
  • policysimulator.replays.get

You might also be able to get these permissions with custom roles or other predefined roles.

To get the most complete results from a simulation, we recommend that you have certain IAM and Google Workspace permissions. If you don't have some or all of these permissions, you can still run a simulation. However, running a simulation without these permissions could result in an increased number of unknown access changes, because you might not be able to retrieve information that could impact the results of the simulation.

We recommend that you have the Security Reviewer role (roles/iam.securityReviewer) for your organization when running a simulation. Alternatively, if you already have the Security Admin role (roles/iam.securityAdmin), you don't need to be granted any additional roles.

These roles give you the following permissions, which help you get the most complete results from the simulation:

  • iam.roles.get and