Searching IAM policies

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

Before you begin

Enable the Cloud Asset API for your project.
Ensure that the caller has been granted a role that contains the cloudasset.assets.searchAllIamPolicies permission. See the Access control topic for more information.

Search policies

Console

To search all IAM policies, complete the following steps.

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

Go to Asset Inventory
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.
Select the IAM policy tab.
To search 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 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: Optional. A scope can be a project, a folder, or an organization. The search is limited to the IAM policies in this scope. The caller must be granted a role that contains the cloudasset.assets.searchAllIamPolicies permission on the desired 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:
  
  Go to the Dashboard page in the Google Cloud console.
  
  Go to Dashboard
  
  Click the switcher box in the menu bar.
  
  Select your organization from the Select from box, and then search for your project name.
  
  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:
  
  Go to the Google Cloud console.
  
  Go to the Google Cloud console
  
  Click the switcher box in the menu bar.
  
  Click the Select from box, and then select your organization.
  
  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:
  
  Go to the Google Cloud console.
  
  Go to the Google Cloud console
  
  Click the switcher box in the menu bar.
  
  Click the Select from box, and then select your organization.
  
  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 policies in the specified scope. Note that the query string is compared against each IAM policy binding, including its principals, roles, and IAM conditions. The returned IAM policies only contain the bindings that match your query. To learn more about the IAM policy structure, see Understanding policies.

Examples:
- policy:amy@gmail.com to find IAM policy bindings that specify user "amy@gmail.com".
- policy:roles/compute.admin to find IAM policy bindings that specify the Compute Admin role.
- policy:comp* to find IAM policy bindings that contain "comp" as a prefix of any word in the binding.
- policy.role.permissions:storage.buckets.update to find IAM 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, policy bindings that specify this role are dropped from the search results.
- policy.role.permissions:upd* to find IAM 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, policy bindings that specify this role are dropped from the search results.
- resource:organizations/123456 to find IAM policy bindings that are set on "organizations/123456".
- resource=//cloudresourcemanager.googleapis.com/projects/myproject to find IAM policy bindings that are set on the project named "myproject".
- Important to find IAM 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 IAM policy bindings that are set on resources "instance1" or "instance2" and also specify user "amy".
- roles:roles/compute.admin to find IAM policy bindings that specify the Compute Admin role.
- memberTypes:user to find IAM policy bindings that contain the "user" principal type.
ASSET_TYPE: Optional. A list of asset types that the Identity and Access Management policies are attached to. If empty, it searches the Identity and Access Management 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 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 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 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:

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.

Caution: Don't enter any confidential information on the OAuth consent screen. Any information you save to the OAuth consent screen might be publicly visible for anyone who accesses your URL. Email and product details are displayed on the login screen and when someone tries to access a resource for which they don't have permission.
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.
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.
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.
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.
You can now query IAM 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
```
Note: This is a GET method. However, the server doesn't accept a body for GET methods and the request URL is also length limited. To avoid errors, use a POST instead, and set a header of X-HTTP-Method-Override: GET.

Provide the following details:
- ASSET_TYPE: Optional. A list of asset types that the Identity and Access Management policies are attached to. If empty, it searches the Identity and Access Management 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 policies in the specified scope. Note that the query string is compared against each IAM policy binding, including its principals, roles, and IAM conditions. The returned IAM policies only contain the bindings that match your query. To learn more about the IAM policy structure, see Understanding policies.
  
  Examples:
  - policy:amy@gmail.com to find IAM policy bindings that specify user "amy@gmail.com".
  - policy:roles/compute.admin to find IAM policy bindings that specify the Compute Admin role.
  - policy:comp* to find IAM policy bindings that contain "comp" as a prefix of any word in the binding.
  - policy.role.permissions:storage.buckets.update to find IAM 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, policy bindings that specify this role are dropped from the search results.
  - policy.role.permissions:upd* to find IAM 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, policy bindings that specify this role are dropped from the search results.
  - resource:organizations/123456 to find IAM policy bindings that are set on "organizations/123456".
  - resource=//cloudresourcemanager.googleapis.com/projects/myproject to find IAM policy bindings that are set on the project named "myproject".
  - Important to find IAM 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 IAM policy bindings that are set on resources "instance1" or "instance2" and also specify user "amy".
  - roles:roles/compute.admin to find IAM policy bindings that specify the Compute Admin role.
  - memberTypes:user to find IAM 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 policies in this scope. The caller must be granted a role that contains the cloudasset.assets.searchAllIamPolicies permission on the desired 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:
    
    Go to the Dashboard page in the Google Cloud console.
    
    Go to Dashboard
    
    Click the switcher box in the menu bar.
    
    Select your organization from the Select from box, and then search for your project name.
    
    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:
    
    Go to the Google Cloud console.
    
    Go to the Google Cloud console
    
    Click the switcher box in the menu bar.
    
    Click the Select from box, and then select your organization.
    
    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:
    
    Go to the Google Cloud console.
    
    Go to the Google Cloud console
    
    Click the switcher box in the menu bar.
    
    Click the Select from box, and then select your organization.
    
    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

SearchAllIamPolicies:

How to construct a query

See Query syntax to learn more about the query language.

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

Query IAM policies by binding information

To search IAM 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 policy bindings support five types of principals:

Google accounts, such as user:user@gmail.com
Google groups, such as group:devs@googlegroups.com
Cloud Identity and G Suite domains, such as domain:google.com
Service accounts, such as serviceAccount:my-other-app@appspot.gserviceaccount.com
Special identifiers, such as allUsers and allAuthenticatedUsers

You can limit your query to 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 policy bindings that specify user Amy:
```
policy:amy
```
Find all IAM policy bindings that specify domain mydomain.com:
```
policy:mydomain.com
```
Find all IAM policy bindings that specify user Amy and John:
```
policy:(amy john)
```
Find all IAM policy bindings that specify user Amy or John:
```
policy:(amy OR john)
```
Find all IAM policy bindings in your organization that contain amy@mycompany.com:
```
policy:amy@mycompany.com
```
Find all IAM policy bindings in your organization that contain the mycompany.com domain:
```
policy:"domain:mycompany.com"
```
Find all IAM policy bindings that assign roles to the mycompany.gserviceaccount.com service account:
```
policy:"serviceAccount:mycompany.gserviceaccount.com"
```
Find all IAM policy bindings that assign roles to the admins group:
```
policy:"group:admins"
```
Find all IAM policy bindings that assign roles to all users:
```
memberTypes:allUsers
```
Find all IAM policy bindings that assign roles to all authenticated users:
```
memberTypes:allAuthenticatedUsers
```
Find all IAM 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 policy bindings support different types of roles. All IAM role names start with the roles/ prefix.

Basic roles: There are three roles that existed prior to the introduction of IAM: Owner (roles/owner), Editor (roles/editor), and Viewer (roles/viewer).
Predefined roles: IAM provides additional predefined roles that give granular access to different resources. See all the predefined roles.
Custom roles: User-defined IAM roles containing a curated list of permissions.

You can limit your query to 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 policy bindings that specify the owner role.

policy:roles/owner
roles:roles/owner
roles=roles/owner

Find all IAM policy bindings that assign amy@mycompany.com the owner role:
```
policy:(roles/owner amy@mycompany.com)
```
Find all IAM 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 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 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 policies related to a specific condition by using the following syntax:

policy:condition_information

Examples: Query by condition

Find all IAM policy bindings that specify a condition, whose title/description contains the word "myCondition":
```
policy:myCondition
```
Find all IAM policy bindings that specify a condition, whose expression contains the attribute "request.time":
```
policy:"request.time"
```

Query IAM policies by included permissions

Roles in a policy can include a list of permissions. See IAM permissions reference for more details. You can limit your query to 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 policy bindings that contain the compute.instances.create permission:

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

Find all IAM policy bindings that contain the compute.instances related permissions:
```
policy.role.permissions:compute.instances
```
Find all IAM 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 policy bindings that grant someone permissions to change IAM policies:
```
policy.role.permissions:setIamPolicy
```
Find all IAM policy bindings with a role containing both compute.instances.create and compute.disks.create permissions:
```
policy.role.permissions:(compute.instances.create compute.disks.create)
```
Note: query terms after policy.role.permissions are matching against the policy binding's included permissions list. Quering with policy.role.permissions:(foo bar) doesn't guarantee that word foo and word bar must match with a single permission (for example, foo.bar.get). Instead, they can match with two different permissions (for example, foo.get and bar.get). See combination in query syntax for more information.

Find all IAM 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 policies by associated resource

When performing a search, you can specify a full resource name to only search the policies that are directly set on the resource. You can also specify a project, a folder or an organization to only search the 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 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 policy bindings that are directly set on resources whose full resource name contains the word myproject:
```
resource:myproject
```
Find all IAM policy bindings that are directly set on resources whose full resource name contains a word with given prefix myproj:
```
resource:myproj*
```
Find all IAM policy bindings that are directly set on resources of a given service type:
```
resource:cloudresourcemanager
```
Find all IAM policy bindings that are set on either myproject or myfolder:
```
resource:(myproject OR myfolder)
```
Find all IAM 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 policy bindings that are set on resources whose project has number 123:
```
project:123
```
Find all IAM policy bindings that are set on resources contained in folder with number 123:
```
folders:123
```
Find all IAM policy bindings that are set on resources whose organization has number 123:
```
organization:123
```

Query IAM policies by free text

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

Examples: Query by free text

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

Searching IAM policies

Before you begin

Search policies

Console

gcloud

Console

gcloud CLI

Console

gcloud CLI

Console

gcloud CLI

REST

Console

gcloud CLI

Console

gcloud CLI

Console

gcloud CLI

Client library and API reference

How to construct a query

Query IAM policies by binding information

Principal

Examples: Query by principal

Role

Examples: Query by role

IAM conditions

Examples: Query by condition

Query IAM policies by included permissions

Examples: Query by permissions

Query IAM policies by associated resource

Examples: Query by associated resource

Query IAM policies by free text

Examples: Query by free text