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?" and "Who can read data in this BigQuery dataset that contains personally identifiable information (PII)?"

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, so that no matter where you are trying to query, the hierarchy will always 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.
  • (API and gcloud tool only) 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.

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?"

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.

Permission on the Google Cloud organization, folder, or project

To analyze a policy, you need the following IAM permissions on the Google Cloud organization, folder, or project 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.

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 organization. To get this information, create a query about a principal 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. Click the Build customized query drop-down menu and click Principal.

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

  4. In the Select roles or permissions, or both section, select one or more roles or permissions to analyze:

    • To add a role, click Add role. Then, select a role from the list of roles. To add another role, click Add another role and select the role that you want to add.
    • To add a permission, click Add permissions. Then, select the permissions you want to add. To add additional permissions, click Add more permissions and select the permissions that you want to add.
  5. Optional: To list individual users inside groups in the results page, click the switch in the Group option section.

  6. Click Run query to run your query. The report page shows the query parameters you inputted, and a results table of all principals with the specified roles and 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 about a principal 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. Click the Build customized query drop-down menu and click Principal.

  3. Leave the Resource field blank.

  4. In the Select roles or permissions, or both section, select one or more roles or permissions to analyze:

    • To add a role, click Add role. Then, select a role from the list of roles. To add another role, click Add another role and select the role that you want to add.
    • To add a permission, click Add permissions. Then, select the permissions you want to add. To add additional permissions, click Add more permissions and select the permissions that you want to add.
  5. Optional: To list individual users inside groups in the results page, click the switch in the Group option section.

  6. Click Run query to run your query. The report page shows the query parameters you inputted, and a results table of all principals with the specified roles and permissions on any resource in the project.

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 about access 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.

    Go to the Policy analyzer page

  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. 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: To list permission inside roles in the results page, click the switch in the Role option section.

  5. Click Run query to run your query. The report page shows the query parameters you inputted, and a results table of all the roles that the specified principal has on the resource you inputted.

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 about a resource 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. Click the Build customized query drop-down menu and click Resource.

  3. 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. In the Select roles or permissions, or both section, select one or more roles or permissions to analyze:

    • To add a role, click Add role. Then, select a role from the list of roles. To add another role, click Add another role and select the role that you want to add.
    • To add a permission, click Add permissions. Then, select the permissions you want to add. To add additional permissions, click Add more permissions and select the permissions that you want to add.
  5. Optional: To list the resources within projects in the results page, click the switch in the Resource option section.

  6. Click Run query to run your query. The report page shows the query parameters you inputted, and a results table of all the resources on which the specified principal has the inputted 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.

Client library and API reference

Constructing a query

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

Limitations

  • Policy Analyzer in the Cloud Console does not support analyzing service account impersonation. If you want to analyze service account impersonation, use the REST API or gcloud tool.

  • IAM Conditions are shown as-is in the returned policy bindings; the conditions are not explained further. If one or more conditions exist in a binding, it means that all identities outputed under that binding have conditional access.

  • Not all resource types are supported. Please see the supported resources types list.