Analyze allow policies

This page shows how to use Policy Analyzer for allow policies to find out which principals have what access to which Google Cloud resources.

Principals can include the following:

Users, groups, or domains
Service accounts
Agent identities
Workload identities
Workforce identities

The examples on this page show how to run a Policy Analysis query and immediately view the results. If you want to export the results for further analysis, you can use AnalyzeIamPolicyLongrunning to write query results to BigQuery or Cloud Storage.

Before you begin

Enable the Cloud Asset API.
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 API

You must enable the API in the project you will use to send the query. This doesn't have to be the same resource that you scope your query to.
Optional: Understand how Policy Analyzer works.
Optional: If you want to execute more than 20 policy analysis queries per organization per day, ensure that you have an organization-level activation of the Premium or Enterprise tier of Security Command Center. For more information, see Billing questions.

Required roles and permissions

The following roles and permissions are required to analyze allow policies.

Required IAM roles

To get the permissions that you need to analyze an allow policy, ask your administrator to grant you the following IAM roles on the project, folder, or organization that you will scope your query to:

Cloud Asset Viewer (roles/cloudasset.viewer)
To analyze policies with custom IAM roles: Role Viewer (roles/iam.roleViewer)
To use the Google Cloud CLI to analyze policies: Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

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

These predefined roles contain the permissions required to analyze an allow policy. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to analyze an allow policy:

cloudasset.assets.analyzeIamPolicy
cloudasset.assets.searchAllResources
cloudasset.assets.searchAllIamPolicies
To analyze policies with custom IAM roles: iam.roles.get
To use the Google Cloud CLI to analyze policies: serviceusage.services.use

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

Required Google Workspace permissions

If you want to expand groups in query results to see if a principal has certain roles or permissions as a result of their membership in a Google Workspace group, you need the groups.read Google Workspace permission. This permission is contained in the Groups Reader Admin role, and in more powerful roles such as the Groups Admin or Super Admin roles. To learn how to grant these roles, see Assign specific admin roles.

Determine which principals can access a resource

You can use Policy Analyzer to check which principals have certain roles or permissions on a specific resource in your project, folder, or organization. To get this information, create a query that includes the resource that you want to analyze access for and one or more roles or permissions to check for.

Console

In the Google Cloud console, go to the Policy analyzer page.

Go to the Policy analyzer page
In the Analyze policies section, find the pane labeled Custom query and click Create custom query in that pane.
In the Select query scope field, select the project, folder, or organization that you want to scope the query to. Policy Analyzer will analyze access for that project, folder, or organization, as well as any resources within that project, folder, or organization.
Choose the resource to check and the role or permission to check for:
1. In the Parameter 1 field, select Resource from the drop-down menu.
2. In the Resource field, enter the full resource name of the resource that you want to analyze access for. If you don't know the full resource name, start typing the display name of the resource, then select the resource from the list of resources provided.
3. Click Add selector.
4. In the Parameter 2 field, select either Role or Permission.
5. In the Select a role or Select a permission field, select the role or permission that you want to check for.
6. Optional: To check for additional roles and permissions, continue adding Role and Permission selectors until all the roles and permissions that you want to check for are listed.
Optional: Click Continue, then select any advanced options that you want to enable for this query.
In the Custom query pane, click Analyze > Run query. The report page shows the query parameters you entered, and a results table of all principals with the specified roles or permissions on the specified resource.

Policy analysis queries in the Google Cloud console can take one minute to run. After one minute, the Google Cloud console stops the query and displays all available results. If the query didn't finish in that time, the Google Cloud console displays a banner indicating that the results are incomplete. To get more results for these queries, export the results to BigQuery.

You can generate a visualization of your query by clicking Visualize results. For more information, see Visualize results (Preview).

gcloud

Before using any of the command data below, make the following replacements:

RESOURCE_TYPE: The type of the resource that you want to scope your search to. Only IAM allow policies attached to this resource and to its descendants will be analyzed. Use the value project, folder, or organization.
RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to scope your search to. Only IAM allow policies attached to this resource and to its descendants will be analyzed. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
FULL_RESOURCE_NAME: The full resource name of the resource that you want to analyze access for. For a list of full resource name formats, see Resource name format.
PERMISSIONS: A comma-separated list of the permissions that you want to check for—for example, compute.instances.get,compute.instances.start. If you list multiple permissions, Policy Analyzer will check for any of the permissions listed.

Execute the gcloud asset analyze-iam-policy command:

Linux, macOS, or Cloud Shell

gcloud asset analyze-iam-policy --RESOURCE_TYPE=RESOURCE_ID \
    --full-resource-name=FULL_RESOURCE_NAME \
    --permissions='PERMISSIONS'

Windows (PowerShell)

gcloud asset analyze-iam-policy --RESOURCE_TYPE=RESOURCE_ID `
    --full-resource-name=FULL_RESOURCE_NAME `
    --permissions='PERMISSIONS'

Windows (cmd.exe)

Note: If this command uses ' for quoting content, replace these single quotes with double quotes. If quoting is nested, use \" to escape the inner quotes.

gcloud asset analyze-iam-policy --RESOURCE_TYPE=RESOURCE_ID ^
    --full-resource-name=FULL_RESOURCE_NAME ^
    --permissions='PERMISSIONS'

You receive a YAML response with analysis results. Each analysis result lists a set of accesses, identities, and resources that are relevant to your query, followed by the related IAM role binding. If the role binding is conditional, the analysis result also includes the result of the condition evaluation. If the condition couldn't be evaluated, the result is CONDITIONAL.

The principals that have any of the specified permissions on the specified resource are listed in the identities fields in the response. The following example shows a single analysis result with the identities field highlighted.

...
---
ACLs:
- accesses:
  - permission: compute.instances.get
  - permission: compute.instances.start
  identities:
  - name: user:my-user@example.com
  resources:
  - fullResourceName: //cloudresourcemanager.googleapis.com/projects/my-project
policy:
  attachedResource: //cloudresourcemanager.googleapis.com/projects/my-project
  binding:
    members:
    - user: my-user@example.com
    role: roles/compute.admin
---
...

If the request times out before the query finishes, you get a DEADLINE_EXCEEDED error. To get more results for these queries, write the results to either BigQuery or Cloud Storage using the long-running version of analyze-iam-policy. For instructions, see Write policy analysis to BigQuery or Write policy analysis to Cloud Storage.

REST

To determine which principals have certain permissions on a resource, use the Cloud Asset Inventory API's analyzeIamPolicy method.

Before using any of the request data, make the following replacements:

RESOURCE_TYPE: The type of the resource that you want to scope your search to. Only IAM allow policies attached to this resource and to its descendants will be analyzed. Use the value projects, folders, or organizations.
RESOURCE_ID: The ID of the Google Cloud project, folder, or organization that you want to scope your search to. Only IAM allow policies attached to this resource and to its descendants will be analyzed. Project IDs are alphanumeric strings, like my-project. Folder and organization IDs are numeric, like 123456789012.
FULL_RESOURCE_NAME: The full resource name of the resource that you want to analyze access for. For a list of full resource name formats, see Resource name format.
PERMISSION_1, PERMISSION_2... PERMISSION_N: The permissions that you want to check for—for example, compute.instances.get. If you list multiple permissions, Policy Analyzer will check for any of the permissions listed.

HTTP method and URL:

POST https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID:analyzeIamPolicy

Request JSON body:

{
  "analysisQuery": {
    "resourceSelector": {
      "fullResourceName": "FULL_RESOURCE_NAME"
    },
    "accessSelector": {
      "permissions": [
        "PERMISSION_1",
        "PERMISSION_2",
        "PERMISSION_N"
      ]
    }
  }
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "X-HTTP-Method-Override: GET" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID:analyzeIamPolicy"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "X-HTTP-Method-Override" = "GET" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudasset.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID:analyzeIamPolicy" | Select-Object -Expand Content

APIs Explorer (browser)

Copy the request body and open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.

You receive a JSON response with analysis results. Each analysis result describes a relevant IAM role binding, then lists the resource, accesses, and principals in that binding. If the role binding is conditional, the analysis result also includes the result of the condition evaluation. If the condition couldn't be evaluated, the result is listed as CONDITIONAL.

...
{
  "attachedResourceFullName": "//cloudresourcemanager.googleapis.com/projects/my-project",
  "iamBinding": {
    "role": "roles/compute.admin",
    "members": [
      "user:my-user@example.com"
    ]
  },
  "accessControlLists": [
    {
      "resources": [
        {
          "fullResourceName": "//cloudresourcemanager.googleapis.com/projects/my-project"
        }
      ],
      "accesses": [
        {
          "permission": "compute.instances.get"
        },
        {
          "permission": "compute.instances.start"
        }
      ]
    }
  ],
  "identityList": {
    "identities": [
      {
        "name": "user:my-user@example.com"
      }
    ]
  },
  "fullyExplored": true
},
...

If the request times out before the query finishes, you get a DEADLINE_EXCEEDED error. To get more results for these queries, write the results to either BigQuery or Cloud Storage using the long-running version of analyzeIamPolicy. For instructions, see Write policy analysis to BigQuery or Write policy analysis to Cloud Storage.

Determine which principals have certain roles or permissions

You can use Policy Analyzer to check which principals have specific roles or permissions on any Google Cloud resource in your organization. To get this information, create a query that includes one or more roles or permissions to check for, but does not specify a resource.

Console

In the Google Cloud console, go to the Policy analyzer page.

Go to the Policy analyzer page
In the Analyze policies section, find the pane labeled Custom query and click Create custom query in that pane.
In the Select query scope field, select the project, folder, or organization that you want to scope the query to. Policy Analyzer will analyze access for that project, folder, or organization, as well as any resources within that project, folder, or organization.
In the Parameter 1 field, select either Role or Permission.
In the Select a role or Select a permission field, select the role or permission that you want to check for.
Optional: To check for additional roles and permissions, do the following:
1. Click Add selector.
2. In the Parameter 2 field, select either Role or Permission.
3. In the Select a role or Select a permission field, select the role or permission that you want to check for.
4. Continue adding Role and Permission selectors until all the roles and permissions that you want to check for are listed.
Optional: Click Continue, then select any advanced options that you want to enable for this query.

Analyze allow policies Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Required roles and permissions

Required IAM roles

Required permissions

Required Google Workspace permissions

Determine which principals can access a resource

Console

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

Determine which principals have certain roles or permissions

Console

Analyze allow policies