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
• Grant the cloudasset.assets.searchAllIamPolicies permission to the user account or service account that is making the request. This permission is included in basic roles and predefined roles listed in Roles.

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 \
  --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 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 members, 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 IAM policy doc.

  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 callers don't have iam.roles.get access to a role's included permissions, 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 callers don't have iam.roles.get access to a role's included permissions, 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".

• (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.

Note: You can only search IAM policies that are set on the searchable resource types. 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 that have [e-mail] 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 the 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"
   curl -s -G \
       -H "Authorization: Bearer $TOKEN" \
       -d "page_size=$PAGE_SIZE" \
       -d "page_token=$PAGE_TOKEN" \
       --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 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 members, 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 IAM policy doc.

  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 Cloud IAM policy bindings that specify a role containing the "storage.buckets.update" permission. Note that if callers don't have iam.roles.get access to a role's included permissions, 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 callers don't have iam.roles.get access to a role's included permissions, 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".

• (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.

Note: You can only search IAM policies that are set on the searchable resource types.

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 members, 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 IAM policy doc.

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

Member

IAM policy bindings support five types of members:

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 member type. For example, the following query will likely only match a user:

policy:[e-mail]

Examples: query by member

• 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 the all users:

  policy:allUsers
  

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

  policy: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

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

Examples: query by role

• Find all IAM policy bindings that specify the owner role.

  policy: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 members 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*))
  

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: If callers don't have iam.roles.get access to a role's included permissions, policy bindings that specify this role will be dropped from the search results. The callers 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 to find more details about which roles can grant the iam.roles.get access.

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 resource name

When performing a search, you can specify a full resource name to only search the policies that are directly set on the resource. A query expression is in the following formats:

• Exact Match: resource=QUERY
• Partial Match: resource:QUERY

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

Examples: query by resource name

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

Query IAM policies by free text

You can also simply use a free text query without specifing a field. Then it will return policies, as long as there is a searchable field (e.g. policy binding fields, resource name) 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, resource name) contain Important as a word:

  Important
  

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

  import*