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.
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 the Asset Inventory page - 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_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: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 theiam.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 theiam.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 themycompany.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
wheremyuser@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 onprojects/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:
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.
- Go to the OAuth consent screen
for your project.
Configure consent screen - 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.
- Go to the OAuth consent screen
for your project.
Create an OAuth token for your project. See Setting up OAuth 2.0 for more information.
- Go to the Create OAuth client ID page.
Create OAuth client - Select Desktop app as your Application type.
- Click Create.
- Go to the Create OAuth client ID page.
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
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.
Generate an auth token for your account with the following command:
TOKEN=$(gcloud auth application-default print-access-token)
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: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 theiam.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 theiam.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 ofnext_page_token
from the preceding call's response.
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 will be 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
andallAuthenticatedUsers
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 will likely only match 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
Note that it is possible that policy:user
may 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
andJohn
:policy:(amy john)
Find all IAM policy bindings that specify user
Amy
orJohn
: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 themycompany.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 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: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 wordjohn
: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
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
, andcloudasset.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
andcompute.disks.create
permissions:policy.role.permissions:(compute.instances.create compute.disks.create)
Find all IAM 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 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
ormyfolder
:resource:(myproject OR myfolder)
Find all IAM 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 policy bindings that are set on resources whose
project
has number123
:project:123
Find all IAM policy bindings that are set on resources contained in
folder
with number123
:folders:123
Find all IAM policy bindings that are set on resources whose
organization
has number123
: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.
Examples: Query by free text
Find all IAM policy bindings within your
scope
whose metadata fields (e.g., policy bindings or resource fields) containImportant
as a word:Important
Find all IAM policy bindings within your
scope
whose metadata fields (e.g., policy bindings or resource fields) containimport
as a prefix of any word:import*