Analyzing IAM policies

This page shows how to use the Policy Analyzer to find out which identities, or principals (users, service accounts, groups, and domains), have what access to which Google Cloud resources.

Typical questions the Policy Analyzer can help you answer are "Who can access this IAM service account?", "Who can read data in this BigQuery dataset that contains personally identifiable information (PII)?", or "Who can access this Cloud Storage bucket at date/time X?"

You can use the AnalyzeIamPolicy method to issue an analysis request, and then get results in its response. Note that the analysis results may not be complete, depending on the amount of data that needs to be processed. If you want to get full results, write the results for further analysis, or store them on your own, you can use AnalyzeIamPolicyLongrunning to write to BigQuery or Cloud Storage.

Overview

The Policy Analyzer allows you to perform access administration, provides access visibility, and can also be used for audit and compliance-related tasks.

In particular:

  • The Policy Analyzer supports resource and policy hierarchy and inheritance. The inherited policies and resource hierarchy beneath the analysis scope you specified will be considered when analyzing effective policies.
  • The Policy Analyzer supports user group expansion, so even if a user is included in a group, we can still help identify their access.
  • The Policy Analyzer supports role to permission expansion, which allows more flexibility in your queries since you can query by permission and/or roles.
  • The Policy Analyzer supports a limited set of resource expansion within the resource hierarchy. For example, in the query results, you can expand all VM instances within a project, or all projects under a folder.
  • The Policy Analyzer supports IAM conditional role bindings, however it may need additional context about the request. For example, to analyze conditions based on date/time attributes, the Policy Analyzer requires the time point in the request. This feature is only supported via the API and gcloud tool.
  • When analyzing IAM policies, the Policy Analyzer supports service account impersonation analysis, including "chained" impersonation at many levels. The Policy Analyzer helps to analyze any indirect access through service accounts. This feature is only supported via the API and gcloud tool.

For example, the following analysis use cases are possible:

  • Determining which principals can access a resource: Find principals that have been granted access on a specified resource. This type of analysis could be used to answer questions like the following:

    • "Who has any access to this IAM service account?"
    • "Who has permission to impersonate this IAM service account?"
    • "Who are the billing administrators on project A?"
    • (API and gcloud tool only): "Who can update project A by impersonating a service account?"
  • Determining which principals have certain roles or permissions: Find principals that have the specified roles/permissions on any applicable resources. This type of analysis could be used to answer questions like the following:

    • "Who has permission to impersonate service accounts in my organization?"
    • "Who are the billing administrators in my organization?"
    • (API and gcloud tool only): "Who in my organization can read a BigQuery dataset by impersonating a service account?"
  • Determining what access a principal has on a resource: Find what access has been granted on a specified resource to a specified principal. This type of analysis could be used to answer questions like the following:

    • "What roles and permissions does user Ivy have on this BigQuery dataset?"
    • "What roles and permissions does the dev-testers group have on any resource in this project?"
    • (API and gcloud tool only): "What roles and permissions does the user Ivy have on this BigQuery dataset if Ivy impersonates a service account?"
  • Determining which resources a principal can access: Find resources that a principal has been granted access to. This could be used to answer questions such as:

    • "Which BigQuery datasets does the user Ivy have permission to read?"
    • "Which BigQuery datasets is the dev-testers group the data owner of?"
    • "What VMs can John delete in project A?"
    • (API and gcloud tool only): "What VMs can the user John delete by impersonating a service account?"
  • Determining conditional access: Find resources that a principal can access for a given condition attribute. This could be used to answer questions such as:

    • (API and gcloud tool only): "Which principals have compute.instances.get or compute.instances.start permissions on a given instance at a specific time?"

Before you begin

  • You must enable the Cloud Asset API for your project.

  • If you are using the API to run these queries, you need to set up your environment and gcurl.

    1. Set up your environment.

    2. To set up a gcurl alias, complete the following steps.

      If you are on a Compute Engine instance, run the following command.

      alias gcurl='curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json" -X POST -H "X-HTTP-Method-Override: GET"'
      

      If you are not on a Compute Engine instance, run the following command.

      alias gcurl='curl -H "$(oauth2l header --json CREDENTIALS cloud-platform)" \
      -H "Content-Type: application/json" -X POST -H "X-HTTP-Method-Override: GET"'
      

      Where CREDENTIALS is your credentials file path, such as ~/credentials.json.

Required permissions

The following permissions are required to run a policy analysis.

Permissions on the scope

To analyze a policy, you need the following IAM permissions on the scope that you are analyzing:

  • cloudasset.assets.analyzeIamPolicy
  • cloudasset.assets.searchAllResources
  • cloudasset.assets.searchAllIamPolicies

These permissions are included in the following predefined roles:

  • Cloud Asset Owner (roles/cloudasset.owner)
  • Cloud Asset Viewer (roles/cloudasset.viewer)

See Access control for more information about Cloud Asset API permissions and roles.

Permissions on IAM roles

When you specify a folder or a project as the scope in your request, if the analysis encounters any principals with an IAM custom role defined at the organization level, you need the iam.roles.get permission on that role so that the analysis can use its definition on your behalf.

Permissions on Google Workspace group memberships

When you check which principals can access a resource, if you choose to expand the members of a group, we will try to expand groups to members with your end user credential. Thus, you will only be able to see members for those groups that you have permission to view the membership of.

When creating a query to determine what access a principal has on a resource or which resources a principal has access to, you specify a principal. We will try to find out which groups (directly or indirectly) that the specified principal is a member of. Again, your end user credential is used; you will only be able to see groups that you have permission to view the membership of.

To view memberships, the principal must be granted the groups.read permission. Roles that contain this permission include the Groups Reader Admin role, or more powerful roles such as the Groups Admin or Super Admin. See this topic for more information.

Analysis Query

An analysis query is composed of a scope, one or more selectors, and other advanced options.

Scope

For each analysis query, you need to specify a scope: an organization, a folder, or a project. All IAM policies defined in that scope (either at or below the scoped resource level) will be included in the analysis. As a result, IAM policies defined above the scoped resource level are not considered in the analysis.

Resource Selector

Resource selector allows you to specify one resource to analyze who has what access on it in the specified scope.

See the IamPolicyAnalysisQuery reference for more information.

Identity Selector

Identity selector allows you to specify an identity to analyze which resources the specified identity has access to in the specified scope.

See the IamPolicyAnalysisQuery reference for more information.

Access Selector

Access selector allows you to specify multiple roles or permissions to find out who has been granted them on which resources in the specified scope.

See the IamPolicyAnalysisQuery reference for more information.

Advanced Options

Besides scope and selectors, you can also specify other advanced options in your query to get more results back.

See the IamPolicyAnalysisQuery reference for more information.

Determining which principals can access a resource

You can use the 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

  1. In the Cloud Console, go to the Policy analyzer page.

    Go to the Policy analyzer page

  2. In the Create query from template section, click Build customized query.

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

  4. 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.
  5. Optional: Click Continue, then select any advanced options that you want to enable for this query.

  6. In the Custom query pane, click 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.

gcloud

You can call AnalyzeIamPolicy on your API-enabled project using the asset analyze-iam-policy gcloud command. You must be running Cloud SDK version 314.0.0 or later. You can check your version with the gcloud version command.

To check which principals have the COMMA_SEPARATED_PERMISSIONS on the FULL_RESOURCE_NAME under ORG_ID:

gcloud asset analyze-iam-policy --organization="ORG_ID" \
    --full-resource-name="FULL_RESOURCE_NAME" \
    --permissions="COMMA_SEPARATED_PERMISSIONS"

For example, to check which principals have the compute.instances.get or compute.instances.start permissions on the Compute Engine instance ipa-gce-instance-2 under organization 1234567890:

gcloud asset analyze-iam-policy --organization="1234567890" \
    --full-resource-name="//compute.googleapis.com/projects/project1/zones/us-central1-a/instances/ipa-gce-instance-2" \
    --permissions="compute.instances.get,compute.instances.start"

REST

  1. Analyze the IAM policies and write results using the gcurl alias.

  2. Create a file request.json for the request body and set its contents to the analysis request in JSON format.

    For example, the following request body checks who has compute.instances.get or compute.instances.start permissions on the Compute Engine instance ipa-gce-instance-2:

    {
      "analysisQuery": {
        "resourceSelector": {
          "fullResourceName":
            "//compute.googleapis.com/projects/project1/zones/us-central1-a/instances/ipa-gce-instance-2"
         },
        "accessSelector": {
          "permissions": [
            "compute.instances.get",
            "compute.instances.start"
          ]
        }
      }
    }
    
  3. Analyze IAM policies using the following gcurl command.

    gcurl -d @request.json  \
    "https://cloudasset.googleapis.com/v1/organizations/ORG_ID:analyzeIamPolicy"
    

    Where ORG_ID is your organization ID, such as 1234567890.

Determining which principals have certain roles or permissions

You can use the 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

  1. In the Cloud Console, go to the Policy analyzer page.

    Go to the Policy analyzer page

  2. In the Create query from template section, click Build customized query.

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

  4. In the Parameter 1 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, 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.
  7. Optional: Click Continue, then select any advanced options that you want to enable for this query.

  8. In the Custom query pane, click 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 any in-scope resource.

gcloud

You can call AnalyzeIamPolicy on your API-enabled project using the asset analyze-iam-policy gcloud command. You must be running Cloud SDK version 314.0.0 or later. You can check your version with the gcloud version command.

To check which principals have the COMMA_SEPARATED_PERMISSIONS under ORG_ID:

gcloud asset analyze-iam-policy --organization="ORG_ID" \
    --permissions="COMMA_SEPARATED_PERMISSIONS"

For example, to check which principals have the compute.instances.get or compute.instances.start permissions under organization 1234567890:

gcloud asset analyze-iam-policy --organization="1234567890" \
    --permissions="compute.instances.get,compute.instances.start"

REST

  1. Analyze the IAM policies and write results using the gcurl alias.

  2. Create a file request.json for the request body and set its contents to the analysis request in JSON format.

    For example, the following request body checks which principals have compute.instances.get or compute.instances.start permissions on any applicable resources:

    {
      "analysisQuery": {
        "accessSelector": {
          "permissions": [
            "compute.instances.get",
            "compute.instances.start"
          ]
        }
      }
    }
    
  3. Analyze IAM policies using the following gcurl command.

    gcurl -d @request.json  \
    "https://cloudasset.googleapis.com/v1/organizations/ORG_ID:analyzeIamPolicy"
    

    Where ORG_ID is your organization ID, such as 1234567890.

Determining what access a principal has on a resource

You can use the Policy Analyzer to check what roles or permissions a principal has on a resource in your organization. To get this information, create a query that includes the principal whose access you want to analyze and the resource that you want to analyze access for.

Console

1. In the Cloud Console, go to the Policy analyzer page.

  <a class="button button-primary" href="https://console.cloud.google.com/iam-admin/analyzer"
  target="console" track-type="task" track-name="consoleLink"
  track-metadata-position="body" track-metadata-end-goal="queryOnPrincipalWithResource">
  Go to the Policy analyzer page</a>
  1. In the Create query from template section, click Build customized query.
  2. 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.
  3. Choose the resource and principal to check:

    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 Principal from the drop-down menu.
    5. In the Principal field, start typing the name of a user, service account, or group. Then, select the user, service account, or group whose access you want to analyze from the list of principals provided.
  4. Optional: Click Continue, then select any advanced options that you want to enable for this query.

  5. In the Custom query pane, click Run query. The report page shows the query parameters you entered, and a results table of all roles that the specified principal has on the specified resource.

gcloud

You can call AnalyzeIamPolicy on your API-enabled project using the asset analyze-iam-policy gcloud command. You must be running Cloud SDK version 314.0.0 or higher. You can check your version with the gcloud version command.

To determine which roles or permissions has the USER been granted on the FULL_RESOURCE_NAME under ORG_ID:

gcloud asset analyze-iam-policy --organization="ORG_ID" \
    --full-resource-name="FULL_RESOURCE_NAME" \
    --identity="USER"

For example, which roles or permissions has the user user1@example.com been granted on the Compute Engine instance ipa-gce-instance-2 under organization 1234567890:

gcloud asset analyze-iam-policy --organization="1234567890" \
    --full-resource-name="//compute.googleapis.com/projects/project1/zones/us-central1-a/instances/ipa-gce-instance-2" \
    --identity="user:user1@example.com"

REST

  1. Analyze the IAM policies and write results using the gcurl alias.

  2. Create a file request.json for the request body and set its contents to the analysis request in JSON format.

    For example, the following request body checks which roles or permissions the user user1@example.com has been granted on the Compute Engine instance ipa-gce-instance-2:

    {
      "analysisQuery": {
        "resourceSelector": {
          "fullResourceName":
            "//compute.googleapis.com/projects/project1/zones/us-central1-a/instances/ipa-gce-instance-2"
         },
        "identitySelector": {
          "identity": "user:user1@example.com"
        }
      }
    }
    
  3. Analyze IAM policies using the following gcurl command.

    gcurl -d @request.json \
    "https://cloudasset.googleapis.com/v1/organizations/ORG_ID:analyzeIamPolicy"
    

    Where ORG_ID is your organization ID, such as 1234567890.

Determining which resources a principal can access

You can use the Policy Analyzer to check which resources within your organization a principal has a certain roles or permissions on. To get this information, create a query that includes the principal whose access you want to analyze and one or more permissions or roles that you want to check for.

Console

  1. In the Cloud Console, go to the Policy analyzer page.

    Go to the Policy analyzer page

  2. In the Create query from template section, click Build customized query.

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

  4. Choose the principal to check and the role or permission to check for:

    1. In the Parameter 1 field, select Principal from the drop-down menu.
    2. In the Principal field, start typing the name of a user, service account, or group. Then, select the user, service account, or group whose access you want to analyze from the list of principals 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.
  5. Optional: Click Continue, then select any advanced options that you want to enable for this query.

  6. In the Custom query pane, click Run query. The report page shows the query parameters you entered, and a results table of all the resources on which the specified principal has the specified roles or permissions.

gcloud

You can call AnalyzeIamPolicy on your API-enabled project using the asset analyze-iam-policy gcloud command. You must be running Cloud SDK version 314.0.0 or higher. You can check your version with the gcloud version command.

To determine on which resource does a USER have COMMA_SEPARATED_PERMISSIONS under ORG_ID:

gcloud asset analyze-iam-policy --organization="ORG_ID" \
    --identity="USER" \
    --permissions="COMMA_SEPARATED_PERMISSIONS"

For example, on which resources does user1@example.com have compute.instances.get or compute.instances.start permissions under organization 1234567890:

gcloud asset analyze-iam-policy --organization="1234567890" \
    --identity="user:user1@example.com" \
    --permissions="compute.instances.get,compute.instances.start"

REST

  1. Analyze the IAM policies and write results using the gcurl alias.

  2. Create a file request.json for the request body and set its contents to the analysis request in JSON format.

    For example, the following request body checks which resources user1@example.com has the compute.instances.get or compute.instances.start permissions on:

    {
      "analysisQuery": {
        "identitySelector": {
          "identity": "user:user1@example.com"
         },
        "accessSelector": {
          "permissions": [
            "compute.instances.get",
            "compute.instances.start"
          ]
        }
      }
    }
    
  3. Analyze IAM policies using the following gcurl command.

    gcurl -d @request.json  \
    "https://cloudasset.googleapis.com/v1/organizations/ORG_ID:analyzeIamPolicy"
    

    Where ORG_ID is your organization ID, such as 1234567890.

Determining conditional access

The Policy Analyzer can analyze IAM conditional role bindings to determine which principals have a desired condition attribute constraining their access to resources. For example, a service account may be granted one or more roles on a resource that only allows access during a specific date or time.

You can set accessTime in the ConditionContext field to enable date/time attribute conditional role binding analysis.

gcloud

You can call AnalyzeIamPolicy on your API-enabled project using the asset analyze-iam-policy gcloud command. You must be running Cloud SDK version 335.0.0 or later. You can check your version with the gcloud version command.

To check which principals have the COMMA_SEPARATED_PERMISSIONS on the FULL_RESOURCE_NAME under ORG_ID at DATE_TIME:

gcloud asset analyze-iam-policy --organization="ORG_ID" \
    --full-resource-name="FULL_RESOURCE_NAME" \
    --permissions="COMMA_SEPARATED_PERMISSIONS" \
    --access-time="DATE_TIME"

For example, to check which principals have the compute.instances.get or compute.instances.start permissions on the Compute Engine instance ipa-gce-instance-2 under organization 1234567890 at 2099-03-01T00:00:00Z. For information on time formats, see gcloud topic datetimes.

gcloud asset analyze-iam-policy --organization="1234567890" \
    --full-resource-name="//compute.googleapis.com/projects/project1/zones/us-central1-a/instances/ipa-gce-instance-2" \
    --permissions="compute.instances.get,compute.instances.start" \
    --access-time="2099-03-01T00:00:00Z"

REST

  1. Analyze the IAM policies and write results using the gcurl alias.

  2. Create a file request.json for the request body and set its contents to the analysis request in JSON format.

    For example, the following request body checks who has compute.instances.get or compute.instances.start permissions on the Compute Engine instance ipa-gce-instance-2 at 2099-03-01T00:00:00Z:

    {
      "analysisQuery": {
        "resourceSelector": {
          "fullResourceName":
            "//compute.googleapis.com/projects/project1/zones/us-central1-a/instances/ipa-gce-instance-2"
         },
        "accessSelector": {
          "permissions": [
            "compute.instances.get",
            "compute.instances.start"
          ]
        },
        "conditionContext": {
          "accessTime": "2099-03-01T00:00:00Z"
        }
      }
    }
    
  3. Analyze IAM policies using the following gcurl command.

    gcurl -d @request.json  \
    "https://cloudasset.googleapis.com/v1/organizations/ORG_ID:analyzeIamPolicy"
    

    Where ORG_ID is your organization ID, such as 1234567890.

Client library and API reference

Constructing a query

To learn about other use cases and options for queries, see analyzing IAM policy query samples.