Searching IAM policies

The Cloud Asset API allows you to use a custom query language to search Identity and Access Management (IAM) policies within 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.

Calling SearchAllIamPolicies

gcloud

You can call SearchAllIamPolicies using the gcloud asset search-all-iam-policies command. You must be running Cloud SDK 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_TYPES,… \
  --order-by=ORDER_BY \
  --page-size=PAGE_SIZE \

Where:

• (Optional) SCOPE: A scope can be a project, a folder, or an organization. The search is limited to the IAM policies within 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 will be used. To find the configured project, run: gcloud config get-value project. To change the setting, run: gcloud config set project PROJECT_ID.

  The allowed values are:

  • projects/PROJECT_ID (e.g., "projects/foo-bar")
  • projects/PROJECT_NUMBER (e.g., "projects/12345678")
  • folders/FOLDER_NUMBER (e.g., "folders/1234567")
  • organizations/ORGANIZATION_NUMBER (e.g., "organizations/123456")

• (Optional) QUERY: The query statement. See How to construct a query for more information. If not specified or empty, it will search all the IAM policies within 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 will only contain the bindings that match your query. To learn more about the IAM policy structure, see Understanding policies.

  Examples:

  • policy:[e-mail] to find IAM policy bindings that specify user "[e-mail]".
  • 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 will be 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 will be 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.

• (Optional) ASSET_TYPES: A list of asset types that the Identity and Access Management policies are attached to. If empty, it will search the Identity and Access Management policies that are attached to all the searchable asset types. Regular expressions are also supported. For example:

  • "compute.googleapis.com.*" snapshots IAM policies attached to asset type starts with "compute.googleapis.com".
  • ".*Instance" snapshots IAM policies attached to asset type ends with "Instance".
  • ".*Instance.*" snapshots IAM policies attached to asset type contains "Instance".

  See RE2 for all supported regular expression syntax. If the regular expression does not match any supported asset type, an INVALID_ARGUMENT error will be returned.

• (Optional) ORDER_BY: 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 (e.g., folders) and non-primitive fields (e.g., policy) are not supported.

• (Optional) PAGE_SIZE: The page size for search result pagination. The maximum is 500. If the value is set to 0, an appropriate default will be selected.

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 [e-mail] has been granted the Owner (roles/owner) basic role:

  gcloud asset search-all-iam-policies \
    --scope='organizations/123456' \
    --query='policy:(roles/owner [e-mail])'
  

• 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'
  

api

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'll need to do so. An email address and product name are required for the OAuth consent screen.

   Don't enter any confidential information on the OAuth consent screen. Any information you save to the OAuth consent screen may 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.

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
   

   Note that this command will prompt you to open a link. Make sure the page shows the Application name you set in your OAuth consent screen.

5. Generate an auth token for your account with the following command:

   TOKEN=$(gcloud auth application-default print-access-token)
   

6. You can now query IAM policies using curl commands.

   PAGE_SIZE=PAGE_SIZE
   PAGE_TOKEN="PAGE_TOKEN"
   SCOPE="SCOPE"
   QUERY="QUERY"
   ASSET_TYPES="ASSET_TYPES,…"
   ORDER_BY="ORDER_BY"
   curl -s -G \
       -H "Authorization: Bearer $TOKEN" \
       -d "page_size=$PAGE_SIZE" \
       -d "page_token=$PAGE_TOKEN" \
       -d "scope=$SCOPE" \
       -d "asset_types=$ASSET_TYPES,…" \
       -d "order_by=$ORDER_BY" \
       --data-urlencode "query=$QUERY" \
       "https://cloudasset.googleapis.com/v1/$SCOPE:searchAllIamPolicies"
   

• (Optional) SCOPE: A scope can be a project, a folder, or an organization. The search is limited to the IAM policies within this scope. The caller must be granted a role that contains the cloudasset.assets.searchAllIamPolicies permission on the desired scope.

  The allowed values are:

  • projects/PROJECT_ID (e.g., "projects/foo-bar")
  • projects/PROJECT_NUMBER (e.g., "projects/12345678")
  • folders/FOLDER_NUMBER (e.g., "folders/1234567")
  • organizations/ORGANIZATION_NUMBER (e.g., "organizations/123456")

• (Optional) QUERY: The query statement. See how to construct a query for more information. If not specified or empty, it will search all the IAM policies within 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 will only contain the bindings that match your query. To learn more about the IAM policy structure, see Understanding policies.

  Examples:

  • policy:[e-mail] to find IAM policy bindings that specify user "[e-mail]".
  • 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 will be 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 will be 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.

• (Optional) ASSET_TYPES: A list of asset types that the Identity and Access Management policies are attached to. If empty, it will search the Identity and Access Management policies that are attached to all the searchable asset types. Regular expressions are also supported. For example:

  • "compute.googleapis.com.*" snapshots IAM policies attached to asset type starts with "compute.googleapis.com".
  • ".*Instance" snapshots IAM policies attached to asset type ends with "Instance".
  • ".*Instance.*" snapshots IAM policies attached to asset type contains "Instance".

  See RE2 for all supported regular expression syntax. If the regular expression does not match any supported asset type, an INVALID_ARGUMENT error will be returned.

• (Optional) ORDER_BY: 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 (e.g., folders) and non-primitive fields (e.g., policy) are not supported.

• (Optional) PAGE_SIZE: The page size for search result pagination. The maximum is 2000. If the value is set to 0, an appropriate default will be selected.

• (Optional) PAGE_TOKEN: The token representing the next batch of results from the preceding call to this method. The page_token must be the same as the value of next_page_token from the preceding call's response.

Client library and API reference

• SearchAllIamPolicies:
  • Client library
  • REST reference
  • RPC reference

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 will be in the following format:

policy:QUERY

Note: The query string is compared to each IAM policy binding, including its principals, roles, and conditions. The returned IAM policies will only contain the bindings that match your query. To learn more about the IAM policy structure, see Understanding policies.

Note: policy as a nested object does not support the equals (=) operator.

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:

1. Google accounts, such as user:[e-mail]
2. Google groups, such as group:[e-mail]
3. Cloud Identity and G Suite domains, such as domain:google.com
4. Service accounts, such as serviceAccount:[e-mail]
5. 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:[e-mail]"

Note that you must quote user:[e-mail] 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 will likely only match a user:

policy:[e-mail]

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

Note that it is possible that policy:user may match a different principal type. For example: group:[e-mail]. 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 [e-mail]:

  policy:[e-mail]
  

• 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 [e-mail] or to the mycompany.com domain:

  policy:([e-mail] OR "domain:mycompany.com")
  

Role

IAM 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 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 will likely only match role roles/cloudasset.owner:

policy:cloudasset.owner
roles:cloudasset.owner

Note that it is possible that policy:cloudasset.owner may match a different role. For example, when a role is granted to the principal user:[e-mail]. 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 [e-mail] the owner role:

  policy:(roles/owner [e-mail])
  

• 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 may 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 may 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

Note: 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 will be dropped from the search results. The caller can be granted the iam.roles.get access from the Security Reviewer role, Security Admin role, Viewer role, Editor role, Owner role, etc. See IAM permissions reference for more information about which roles contain the iam.roles.get permission.

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... (e.g. 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 (e.g. foo.bar.get). Instead, they can match with two different permissions (e.g. 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

Note: Not all the asset types are searchable. See the list of searchable types.

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 simply use a free text query without specifing a field. The response will return policies as long as there is a searchable field (e.g. policy binding fields or resource fields) matching the query.

Note: Free text search doesn't support searching the included permissions. To search by included permissions, you have to specify a field query.

Examples: Query by free text

• Find all IAM policy bindings within your scope whose metadata fields (e.g., policy bindings or resource fields) contain Important as a word:

  Important
  

• Find all IAM policy bindings within your scope whose metadata fields (e.g., policy bindings or resource fields) contain import as a prefix of any word:

  import*