Searching IAM allow policies

The Cloud Asset API allows you to use a custom query language to search Identity and Access Management (IAM) allow policies in a project, folder, or organization.

Before you begin

Search allow policies

Console

To search all IAM allow policies, complete the following steps.

  1. Go to the Asset Inventory page in the Google Cloud console.

    Go to Asset Inventory

  2. To set the scope of your search, open the Projects list box in the menu bar, and then select the organization, folder, or project to query.

  3. Select the IAM policy tab.

  4. To search allow policies, you can use a preset query or build your own.

    • To use a preset query, select options from Query Presets on the Filter results pane. To filter results, select options from Filters.

    • To build your own query, enter the query text in the Filter bar. Select the text box, and then a list of searchable fields display. Policy search supports multiple fields. Learn more about query syntax.

The allow policies matching the query are listed in the Result table.

To view the query as a Google Cloud CLI command, select View query.

To export the results, select Download CSV.

gcloud

You can call SearchAllIamPolicies using the gcloud asset search-all-iam-policies command. You must be running Google Cloud CLI version 302.0.0 or newer. You can check your version with the gcloud version command:

gcloud asset search-all-iam-policies \
    --scope=SCOPE \
    --query="QUERY" \
    --asset-types=ASSET_TYPE_1,ASSET_TYPE_2,... \
    --order-by=ORDER_BY

Provide the following values:

  • SCOPE: Required. A scope can be a project, a folder, or an organization. The search is limited to the IAM allow policies in this scope. The caller must be granted a role that contains the cloudasset.assets.searchAllIamPolicies permission on the selected scope. If not specified, the configured project property is used.

    The allowed values are:

    • projects/PROJECT_ID

    • projects/PROJECT_NUMBER

      How to find a Google Cloud project number

      Console

      To find a Google Cloud project number, complete the following steps:

      1. Go to the Dashboard page in the Google Cloud console.

        Go to Dashboard

      2. Click the switcher box in the menu bar.
      3. Select your organization from the Select from box, and then search for your project name.
      4. Click the project name to switch to that project. The project number is shown in the Project info card.

      gcloud CLI

      You can retrieve a Google Cloud project number with the following command:

      gcloud projects describe PROJECT_ID --format="value(projectNumber)"

    • folders/FOLDER_ID

      How to find a Google Cloud folder ID

      Console

      To find a Google Cloud folder ID, complete the following steps:

      1. Go to the Google Cloud console.

        Go to the Google Cloud console

      2. Click the switcher box in the menu bar.
      3. Click the Select from box, and then select your organization.
      4. Search for your folder name. The folder ID is shown next to the folder name.

      gcloud CLI

      You can retrieve a Google Cloud folder ID that's located at the organization level with the following command:

      gcloud resource-manager folders list \
          --organization=$(gcloud organizations describe ORGANIZATION_NAME \
            --format="value(name.segment(1))") \
          --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \
          --format="value(ID)"

      Where TOP_LEVEL_FOLDER_NAME can be a full or partial string match. Remove the --format option to see further information about the found folders.

      To get the ID of a folder within another folder, list the subfolders:

      gcloud resource-manager folders list --folder=FOLDER_ID

    • organizations/ORGANIZATION_ID

      How to find a Google Cloud organization ID

      Console

      To find a Google Cloud organization ID, complete the following steps:

      1. Go to the Google Cloud console.

        Go to the Google Cloud console

      2. Click the switcher box in the menu bar.
      3. Click the Select from box, and then select your organization.
      4. Click the All tab. The organization ID is shown next to the organization name.

      gcloud CLI

      You can retrieve a Google Cloud organization ID with the following command:

      gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"

  • QUERY: Optional. The query statement. See Query syntax for more information. If not specified or empty, it searches all the IAM allow policies in the specified scope. Note that the query string is compared against each allow policy binding, including its principals, roles, and IAM conditions. The returned allow policies only contain the bindings that match your query. To learn more about the allow policy structure, see Understanding policies.

    Examples:

    • policy:amy@gmail.com to find allow policy bindings that specify user "amy@gmail.com".

    • policy:roles/compute.admin to find allow policy bindings that specify the Compute Admin role.

    • policy:comp* to find allow policy bindings that contain "comp" as a prefix of any word in the binding.

    • policy.role.permissions:storage.buckets.update to find allow policy bindings that specify a role containing the "storage.buckets.update" permission. Note that if the caller hasn't been granted a role that contains the iam.roles.get permission on the desired role, allow policy bindings that specify this role are dropped from the search results.

    • policy.role.permissions:upd* to find allow policy bindings that specify a role containing "upd" as a prefix of any word in the binding. Note that if the caller hasn't been granted a role that contains the iam.roles.get permission on the desired role, allow policy bindings that specify this role are dropped from the search results.

    • resource:organizations/123456 to find allow policy bindings that are set on "organizations/123456".

    • resource=//cloudresourcemanager.googleapis.com/projects/myproject to find allow policy bindings that are set on the project named "myproject".

    • Important to find allow policy bindings that contain "Important" as a word in any of the searchable fields (except for the included permissions).

    • resource:(instance1 OR instance2) policy:amy to find allow policy bindings that are set on resources "instance1" or "instance2" and also specify user "amy".

    • roles:roles/compute.admin to find allow policy bindings that specify the Compute Admin role.

    • memberTypes:user to find allow policy bindings that contain the "user" principal type.

  • ASSET_TYPE: Optional. A list of asset types that the Identity and Access Management allow policies are attached to. If empty, it searches the Identity and Access Management allow policies that are attached to all the searchable asset types. Regular expressions are supported. If the regular expression does not match any supported asset type, an INVALID_ARGUMENT error is returned.

  • ORDER_BY: Optional. A comma-separated list of fields specifying the sorting order of the results. The default order is ascending. Add DESC after the field name to indicate descending order. Redundant space characters are ignored. Example: "assetType DESC, resource". Only singular primitive fields in the response are sortable:

    • resource

    • assetType

    • project

    All the other fields such as repeated fields (for example, folders) and non-primitive fields (for example, policy) are not supported.

The following are example gcloud commands:

  • Find all IAM allow policy bindings in your organizations/123456 that contain the mycompany.com domain:

    gcloud asset search-all-iam-policies \
        --scope=organizations/123456 \
        --query="policy:\"domain:mycompany.com\""
    
  • Find all IAM allow policy bindings in your organizations/123456 where myuser@mycompany.com has been granted the Owner (roles/owner) basic role:

    gcloud asset search-all-iam-policies \
        --scope=organizations/123456 \
        --query="policy:(roles/owner myuser@mycompany.com)"
    
  • Find all IAM allow policy bindings in your organizations/123456 that are set on projects/12345678:

    gcloud asset search-all-iam-policies \
        --scope=organizations/123456 \
        --query="resource:projects/12345678"
    

REST

You can call SearchAllIamPolicies using a valid OAuth token for a project. To call the SearchAllIamPolicies method from Cloud Shell or any console where the gcloud command is available:

  1. If you haven't configured your project's OAuth consent screen, you need to do so. An email address and product name are required for the OAuth consent screen.

    1. Go to the OAuth consent screen for your project.

      Configure consent screen

    2. Enter the Application name you want to display.

    3. Under Support email, select the email address you want to display as a public contact. This must be your email address, or a Google Group you own.

    4. Add any optional details you'd like.

    5. Click Save.

  2. Create an OAuth token for your project. See Setting up OAuth 2.0 for more information.

    1. Go to the Create OAuth client ID page.

      Create OAuth client

    2. Select Desktop app as your Application type.

    3. Click Create.

  3. Download the client_secret.json file.

    1. Go to the Credentials page.

    2. To the right of your new Client ID, click Download JSON.

    3. Securely store the file in a location that only your app can access.

  4. Log in using the JSON file with the following command.

    gcloud auth application-default login --client-id-file=YOUR_JSON_FILE
    

    This command prompts you to open a link. Make sure the page shows the Application name you set in your OAuth consent screen.

  5. You can now query IAM allow policies using curl commands.

    curl -X POST \
         -H "X-HTTP-Method-Override: GET" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
              "assetTypes": [
                "ASSET_TYPE_1",
                "ASSET_TYPE_2",
                "..."
              ],
              "orderBy": "ORDER_BY",
              "pageSize": PAGE_SIZE,
              "query": "QUERY"
             }' \
         https://cloudasset.googleapis.com/v1/SCOPE:searchAllIamPolicies
    

    Provide the following details:

    • ASSET_TYPE: Optional. A list of asset types that the Identity and Access Management allow policies are attached to. If empty, it searches the Identity and Access Management allow policies that are attached to all the searchable asset types. Regular expressions are supported. If the regular expression does not match any supported asset type, an INVALID_ARGUMENT error is returned.

    • ORDER_BY: Optional. A comma-separated list of fields specifying the sorting order of the results. The default order is ascending. Add DESC after the field name to indicate descending order. Redundant space characters are ignored. Example: "assetType DESC, resource". Only singular primitive fields in the response are sortable:

      • resource

      • assetType

      • project

      All the other fields such as repeated fields (for example, folders) and non-primitive fields (for example, policy) are not supported.

    • PAGE_SIZE: Optional. The number of results to return per page. The maximum is 2000. If the value is set to 0 or a negative value, an appropriate default is selected. A nextPageToken is returned to retrieve subsequent results.

    • QUERY: Optional. The query statement. See Query syntax for more information. If not specified or empty, it searches all the IAM allow policies in the specified scope. Note that the query string is compared against each allow policy binding, including its principals, roles, and IAM conditions. The returned allow policies only contain the bindings that match your query. To learn more about the allow policy structure, see Understanding allow policies.

      Examples:

      • policy:amy@gmail.com to find allow policy bindings that specify user "amy@gmail.com".

      • policy:roles/compute.admin to find allow policy bindings that specify the Compute Admin role.

      • policy:comp* to find allow policy bindings that contain "comp" as a prefix of any word in the binding.

      • policy.role.permissions:storage.buckets.update to find allow policy bindings that specify a role containing the "storage.buckets.update" permission. Note that if the caller hasn't been granted a role that contains the iam.roles.get permission on the desired role, allow policy bindings that specify this role are dropped from the search results.

      • policy.role.permissions:upd* to find allow policy bindings that specify a role containing "upd" as a prefix of any word in the role permission. Note that if the caller hasn't been granted a role that contains the iam.roles.get permission on the desired role, allow policy bindings that specify this role are dropped from the search results.

      • resource:organizations/123456 to find allow policy bindings that are set on "organizations/123456".

      • resource=//cloudresourcemanager.googleapis.com/projects/myproject to find allow policy bindings that are set on the project named "myproject".

      • Important to find allow policy bindings that contain "Important" as a word in any of the searchable fields (except for the included permissions).

      • resource:(instance1 OR instance2) policy:amy to find allow policy bindings that are set on resources "instance1" or "instance2" and also specify user "amy".

      • roles:roles/compute.admin to find allow policy bindings that specify the Compute Admin role.

      • memberTypes:user to find allow policy bindings that contain the "user" principal type.

    • SCOPE: A scope can be a project, a folder, or an organization. The search is limited to the IAM allow policies in this scope. The caller must be granted a role that contains the cloudasset.assets.searchAllIamPolicies permission on the selected scope. If not specified, the configured project property is used.

      The allowed values are:

      • projects/PROJECT_ID

      • projects/PROJECT_NUMBER

        How to find a Google Cloud project number

        Console

        To find a Google Cloud project number, complete the following steps:

        1. Go to the Dashboard page in the Google Cloud console.

          Go to Dashboard

        2. Click the switcher box in the menu bar.
        3. Select your organization from the Select from box, and then search for your project name.
        4. Click the project name to switch to that project. The project number is shown in the Project info card.

        gcloud CLI

        You can retrieve a Google Cloud project number with the following command:

        gcloud projects describe PROJECT_ID --format="value(projectNumber)"

      • folders/FOLDER_ID

        How to find a Google Cloud folder ID

        Console

        To find a Google Cloud folder ID, complete the following steps:

        1. Go to the Google Cloud console.

          Go to the Google Cloud console

        2. Click the switcher box in the menu bar.
        3. Click the Select from box, and then select your organization.
        4. Search for your folder name. The folder ID is shown next to the folder name.

        gcloud CLI

        You can retrieve a Google Cloud folder ID that's located at the organization level with the following command:

        gcloud resource-manager folders list \
            --organization=$(gcloud organizations describe ORGANIZATION_NAME \
              --format="value(name.segment(1))") \
            --filter='"DISPLAY_NAME":"TOP_LEVEL_FOLDER_NAME"' \
            --format="value(ID)"

        Where TOP_LEVEL_FOLDER_NAME can be a full or partial string match. Remove the --format option to see further information about the found folders.

        To get the ID of a folder within another folder, list the subfolders:

        gcloud resource-manager folders list --folder=FOLDER_ID

      • organizations/ORGANIZATION_ID

        How to find a Google Cloud organization ID

        Console

        To find a Google Cloud organization ID, complete the following steps:

        1. Go to the Google Cloud console.

          Go to the Google Cloud console

        2. Click the switcher box in the menu bar.
        3. Click the Select from box, and then select your organization.
        4. Click the All tab. The organization ID is shown next to the organization name.

        gcloud CLI

        You can retrieve a Google Cloud organization ID with the following command:

        gcloud organizations describe ORGANIZATION_NAME --format="value(name.segment(1))"

Client library and API reference

How to construct a query

See Query syntax to learn more about the query language.

See Searching IAM allow policies samples to learn more about the sample queries for various real use cases.

Query IAM allow policies by binding information

To search IAM allow policies, a query expression is in the following format:

policy:QUERY

You can also exclusively search for principal types or roles with the following formats:

  • Exact match:

    • memberTypes=QUERY

    • roles=QUERY

  • Partial match:

    • memberTypes:QUERY

    • roles:QUERY

Principal

IAM allow policy bindings support five types of principals:

  1. Google accounts, such as user:user@gmail.com

  2. Google groups, such as group:devs@googlegroups.com

  3. Cloud Identity and G Suite domains, such as domain:google.com

  4. Service accounts, such as serviceAccount:my-other-app@appspot.gserviceaccount.com

  5. Special identifiers, such as allUsers and allAuthenticatedUsers

You can limit your query to allow policies related to a specific user by using the following syntax:

policy:"user:amy@mycompany.com"

Note that you must quote user:amy@mycompany.com with double quotations, since it contains special char :. You can omit the user: or group: prefix in a query string, if the query value is unique enough or if you want to search for the email address regardless of the principal type. For example, the following query likely only matches a user:

policy:amy@mycompany.com

You can also limit your query to policies related to a specific principal type by using the following syntax:

policy:user
memberTypes:user
memberTypes=user

It's possible that policy:user might match a different principal type. For example: group:test-user@mycompany.com. Use memberTypes to limit the search to specific principal types.

Examples: Query by principal
  • Find all IAM allow policy bindings that specify user Amy:

    policy:amy
    
  • Find all IAM allow policy bindings that specify domain mydomain.com:

    policy:mydomain.com
    
  • Find all IAM allow policy bindings that specify user Amy and John:

    policy:(amy john)
    
  • Find all IAM allow policy bindings that specify user Amy or John:

    policy:(amy OR john)
    
  • Find all IAM allow policy bindings in your organization that contain amy@mycompany.com:

    policy:amy@mycompany.com
    
  • Find all IAM allow policy bindings in your organization that contain the mycompany.com domain:

    policy:"domain:mycompany.com"
    
  • Find all IAM allow policy bindings that assign roles to the mycompany.gserviceaccount.com service account:

    policy:"serviceAccount:mycompany.gserviceaccount.com"
    
  • Find all IAM allow policy bindings that assign roles to the admins group:

    policy:"group:admins"
    
  • Find all IAM allow policy bindings that assign roles to all users:

    memberTypes:allUsers
    
  • Find all IAM allow policy bindings that assign roles to all authenticated users:

    memberTypes:allAuthenticatedUsers
    
  • Find all IAM allow policy bindings that assign roles to either amy@mycompany.com or to the mycompany.com domain:

    policy:(amy@mycompany.com OR "domain:mycompany.com")
    

Role

IAM allow policy bindings support different types of roles. All IAM role names start with the roles/ prefix.

  1. Basic roles: There are three roles that existed prior to the introduction of IAM: Owner (roles/owner), Editor (roles/editor), and Viewer (roles/viewer).

  2. Predefined roles: IAM provides additional predefined roles that give granular access to different resources. See all the predefined roles.

  3. Custom roles: User-defined IAM roles containing a curated list of permissions.

You can limit your query to allow policies related to a specific role by using the following syntax:

policy:roles/role-name
roles:roles/role-name
roles=roles/role-name

Note that you can omit the roles/ prefix in a query string if the query value is unique enough. For example, the following query likely only matches the role roles/cloudasset.owner:

policy:cloudasset.owner
roles:cloudasset.owner

It's possible that policy:cloudasset.owner might match a different role. For example, when a role is granted to the principal user:cloudasset.owner@mycompany.com. Use roles to limit the search to roles.

Examples: Query by role
  • Find all IAM allow policy bindings that specify the owner role.

    policy:roles/owner
    roles:roles/owner
    roles=roles/owner
    
  • Find all IAM allow policy bindings that assign amy@mycompany.com the owner role:

    policy:(roles/owner amy@mycompany.com)
    
  • Find all IAM allow policy bindings that assign the compute.admin role to principals whose email address contains the word john:

    policy:(roles/compute.admin john)
    
  • Find all IAM allow policy bindings that grant the viewer role to users that have "swe" or "sde" as a prefix.

    policy:(roles/viewer (swe* OR sde*))
    

IAM conditions

IAM allow policy bindings might contain a condition object, which allows you to define and enforce conditional, attribute-based access control for Google Cloud resources. See Overview of IAM Conditions for more information.

You can limit your query to allow policies related to a specific condition by using the following syntax:

policy:condition_information
Examples: Query by condition
  • Find all IAM allow policy bindings that specify a condition, whose title/description contains the word "myCondition":

    policy:myCondition
    
  • Find all IAM allow policy bindings that specify a condition, whose expression contains the attribute "request.time":

    policy:"request.time"
    

Query IAM allow policies by included permissions

Roles in an allow policy can include a list of permissions. See IAM permissions reference for more details. You can limit your query to allow policies containing a specific permission. A query expression is in the following formats:

  • Exact match: policy.role.permissions=QUERY
  • Partial match: policy.role.permissions:QUERY
Examples: Query by permissions
  • Find all IAM allow policy bindings that contain the compute.instances.create permission:

    policy.role.permissions:compute.instances.create
    policy.role.permissions=compute.instances.create
    
  • Find all IAM allow policy bindings that contain the compute.instances related permissions:

    policy.role.permissions:compute.instances
    
  • Find all IAM allow policy bindings that contain permissions cloudasset.assets.export... (for example, cloudasset.assets.exportAssets and cloudasset.assets.exportIamPolicyAnalysis):

    policy.role.permissions:cloudasset.assets.export*
    
  • Find all IAM allow policy bindings that grant someone permissions to change IAM allow policies:

    policy.role.permissions:setIamPolicy
    
  • Find all IAM allow policy bindings with a role containing both compute.instances.create and compute.disks.create permissions:

    policy.role.permissions:(compute.instances.create compute.disks.create)
    
  • Find all IAM allow policy bindings that contain the compute.instances.create permission and specify user amy:

    policy.role.permissions:compute.instances.create policy:amy
    policy.role.permissions=compute.instances.create policy:amy
    

Query IAM allow policies by associated resource

When performing a search, you can specify a full resource name to only search the allow policies that are directly set on the resource. You can also specify a project, a folder or an organization to only search the allow policies that are set on resources located under the given project/folder/organization. A query expression is in the following formats:

  • Exact match:

    • resource=QUERY

    • project=QUERY

    • folders=QUERY

    • organization=QUERY

  • Partial match:

    • resource:QUERY

    • project:QUERY

    • folders:QUERY

    • organization:QUERY

Examples: Query by associated resource

  • Find all IAM allow policy bindings that are directly set on a resource whose full resource name exactly equals //cloudresourcemanager.googleapis.com/projects/myproject:

    resource=//cloudresourcemanager.googleapis.com/projects/myproject
    
  • Find all IAM allow policy bindings that are directly set on resources whose full resource name contains the word myproject:

    resource:myproject
    
  • Find all IAM allow policy bindings that are directly set on resources whose full resource name contains a word with given prefix myproj:

    resource:myproj*
    
  • Find all IAM allow policy bindings that are directly set on resources of a given service type:

    resource:cloudresourcemanager
    
  • Find all IAM allow policy bindings that are set on either myproject or myfolder:

    resource:(myproject OR myfolder)
    
  • Find all IAM allow policy bindings that are set on cloudresourcemanager resources and assign the owner role to gmail.com users:

    resource:cloudresourcemanager policy:(roles/owner gmail.com)
    
  • Find all IAM allow policy bindings that are set on resources whose project has number 123:

    project:123
    
  • Find all IAM allow policy bindings that are set on resources contained in folder with number 123:

    folders:123
    
  • Find all IAM allow policy bindings that are set on resources whose organization has number 123:

    organization:123
    

Query IAM allow policies by free text

You can also use a free text query without specifying a field. The response returns allow policies as long as there is a searchable field (for example, allow policy binding fields or resource fields) matching the query.

Examples: Query by free text

  • Find all IAM allow policy bindings in your scope whose metadata fields (for example, allow policy bindings or resource fields) contain Important as a word:

    Important
    
  • Find all IAM allow policy bindings in your scope whose metadata fields (for example, allow policy bindings or resource fields) contain import as a prefix of any word:

    import*