Searching Cloud IAM policies

Beta

This feature is in a pre-release state and might change or have limited support. For more information, see the product launch stages.

The Cloud Asset API allows you to use a custom query language to search Cloud Identity and Access Management (Cloud 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 primitive 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 278.0.0 or newer. You can check your version with the gcloud version command.

gcloud beta asset search-all-iam-policies \
  --scope=SCOPE \
  --query=QUERY \
  --page-size=PAGE_SIZE \
  --page-token=PAGE_TOKEN

Where:

• (Optional) SCOPE: The search result scope is limited within a project, folder, or organization. You must have the cloudasset.assets.searchAllIamPolicies permission granted to the caller for the desired scope. The default value is your configured project property. The allowed values are:
  • projects/PROJECT_ID (e.g., "projects/foo")
  • projects/PROJECT_NUMBER (e.g., "projects/12345")
  • folders/FOLDER_NUMBER (e.g., "folders/1234")
  • organizations/ORGANIZATION_NUMBER (e.g., "organizations/123")
• (Optional) QUERY: The query statement. See How to construct a query for more information. Some examples include:
  • "policy : [e-mail]": to find Cloud IAM policies that specify user "amy".
  • "policy : compute.admin": to find Cloud IAM policies that specify the Compute Admin (roles/compute.admin) role.
  • "resource : projects/123456": to find Cloud IAM policies that are set on "projects/123456".
• (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. The following are example gcloud commands.

• Find all Cloud IAM policies in your organizations/123456 that contain the mycompany.com domain:

  gcloud beta asset search-all-iam-policies \
    --scope='organizations/123456' \
    --query='policy : "domain:mycompany.com"'
  

• Find all Cloud IAM policies in your organizations/123456 that have [e-mail] granted the Owner (roles/owner) primitive role:

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

• Find all Cloud IAM policies in your organizations/123456 that are set on the projects/123456:

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

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 Cloud 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/v1p1beta1/$SCOPE/iamPolicies:searchAll"
   

• SCOPE is required. The search result scope is limited within a project, folder, or organization. You must have the cloudasset.assets.searchAllIamPolicies permission granted to the caller for the desired scope. The allowed values are:
  • projects/PROJECT_ID (e.g., "projects/foo")
  • projects/PROJECT_NUMBER (e.g., "projects/12345")
  • folders/FOLDER_NUMBER (e.g., "folders/1234")
  • organizations/ORGANIZATION_NUMBER (e.g., "organizations/123")
• (Optional) QUERY: The query statement. See How to construct a query for more information. Some examples include:
  • "policy : [e-mail]": to find Cloud IAM policies that specify user "amy".
  • "policy : compute.admin": to find Cloud IAM policies that specify the Compute Admin (roles/compute.admin) role.
  • "resource : projects/123456": to find Cloud IAM policies that are set on "projects/123456".
• (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

To learn about the query language, see query syntax.

Note that search Cloud IAM policies don't support the following two syntax types:

• NOT in combinations
• Prefix in wildcards

Query Cloud IAM policies by binding information

To search Cloud IAM policies, a query expression will be in the following format:

policy : QUERY

Note: The query string is compared to each Cloud IAM policy binding, including its members, roles, and Cloud IAM conditions. The returned Cloud IAM policies, will only contain the bindings that match your query.

Member

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

policy : "user:[e-mail]"

Cloud 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

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

policy : "[e-mail]"

Examples: query by member

• Return Cloud IAM policies that specify user Amy:

  policy : amy
  

• Return Cloud IAM policies that specify domain mydomain.com:

  policy : mydomain.com
  

• Return Cloud IAM policies that specify user Amy and John:

  policy : (amy john)
  

• Return Cloud IAM policies that specify user Amy or John:

  policy : (amy OR john)
  

• Find all Cloud IAM policies in your organization that contain [e-mail]:

  policy : [e-mail]
  

• Find all Cloud IAM policies in your organization that contain the mycompany.com domain:

  policy : "domain:mycompany.com"
  

• Return Cloud IAM policies that assign roles to the mycompany.gserviceaccount.com service account:

  policy : "serviceAccount:mycompany.gserviceaccount.com"
  

• Return Cloud IAM policies that assign roles to the admins group:

  policy : "group:admins"
  

• Return Cloud IAM policies that assign roles to the all users:

  policy : allUsers
  

• Return Cloud IAM policies that assign roles to all authenticated users:

  policy : allAuthenticatedUsers
  

• Return Cloud IAM policies that assign roles to either [e-mail] or to the mycompany.com domain:

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

Role

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

policy : "roles/role-name"

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

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

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

• Return Cloud IAM policies that specify the owner role.

  policy : roles/owner
  

• Return Cloud IAM policies that assign [e-mail] the owner role:

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

• Return Cloud IAM policies that assign the compute.admin role to members whose email address contains the word john:

  policy : (roles/compute.admin john)
  

• Return Cloud IAM policies that grant the viewer role to users that has "swe" or "sde" substring.

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

Query Cloud IAM policies by resource

When performing a search, you can specify a full resource name to only search the policies that are directly set on the resource:

    resource : "projects/my-proj-id"

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

Examples: query by resource

• Return Cloud IAM policies that directly set on a resource, if you know the full resource name of the resource:

  resource : "//cloudresourcemanager.googleapis.com/projects/my-proj-id"
  

• Return Cloud IAM policies that directly set on resources, if you know a substring part of the resource id:

  resource : "*my-proj*"
  

• Return Cloud IAM policies that directly set on resources of a given service type:

  resource : "*//cloudresourcemanager*"
  

• Return Cloud IAM policies that are set on either myproject or myfolder:

  resource : ("myproject" OR "myfolder")
  

• Return policies which are set on cloudresourcemanager resources and assign the owner role to gmail.com users:

  resource : cloudresourcemanager policy : (roles/owner gmail.com)