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
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 allow policies
Console
To search all IAM allow policies, complete the following steps.
Go to the Asset Inventory page in the Google Cloud console.
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 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 thecloudasset.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:
-
Go to the Dashboard page in the Google Cloud console.
- 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.
- 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.
- 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 allow policies in the specifiedscope
. 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:[email protected]
to find allow policy bindings that specify user "[email protected]".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 theiam.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 theiam.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, anINVALID_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. AddDESC
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 themycompany.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[email protected]
has been granted the Owner (roles/owner
) basic role:gcloud asset search-all-iam-policies \ --scope=organizations/123456 \ --query="policy:(roles/owner [email protected])"
Find all IAM allow policy bindings in your
organizations/123456
that are set onprojects/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.
Go to the OAuth consent screen for your project.
Enter the Application name you want to display.
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.
Add any optional details you'd like.
Click Save.
Create an OAuth token for your project. See Setting up OAuth 2.0 for more information.
Go to the Create OAuth client ID page.
Select Desktop app as your Application type.
Click Create.
Download the
client_secret.json
file.Go to the Credentials page.
To the right of your new Client ID, click
Download JSON.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 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, anINVALID_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. AddDESC
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 to0
or a negative value, an appropriate default is selected. AnextPageToken
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 specifiedscope
. 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:[email protected]
to find allow policy bindings that specify user "[email protected]".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 theiam.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 theiam.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 thecloudasset.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:
-
Go to the Dashboard page in the Google Cloud console.
- 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.
- 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.
- 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 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:
Google accounts, such as
user:[email protected]
Google groups, such as
group:[email protected]
Cloud Identity and G Suite domains, such as
domain:google.com
Service accounts, such as
serviceAccount:[email protected]
Special identifiers, such as
allUsers
andallAuthenticatedUsers
You can limit your query to allow policies related to a specific user by using the following syntax:
policy:"user:[email protected]"
Note that you must quote user:[email protected]
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:[email protected]
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:[email protected]
. 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
andJohn
:policy:(amy john)
Find all IAM allow policy bindings that specify user
Amy
orJohn
:policy:(amy OR john)
Find all IAM allow policy bindings in your organization that contain
[email protected]
:policy:[email protected]
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
[email protected]
or to themycompany.com
domain:policy:([email protected] OR "domain:mycompany.com")
Role
IAM allow 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 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:[email protected]
. 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
[email protected]
the owner role:policy:(roles/owner [email protected])
Find all IAM allow policy bindings that assign the
compute.admin
role to principals whose email address contains the wordjohn
: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
andcloudasset.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
andcompute.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 useramy
: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
ormyfolder
:resource:(myproject OR myfolder)
Find all IAM allow policy bindings that are set on
cloudresourcemanager
resources and assign the owner role togmail.com
users:resource:cloudresourcemanager policy:(roles/owner gmail.com)
Find all IAM allow policy bindings that are set on resources whose
project
has number123
:project:123
Find all IAM allow policy bindings that are set on resources contained in
folder
with number123
:folders:123
Find all IAM allow policy bindings that are set on resources whose
organization
has number123
: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) containImportant
as a word:Important
Find all IAM allow policy bindings in your
scope
whose metadata fields (for example, allow policy bindings or resource fields) containimport
as a prefix of any word:import*