Before you grant an Identity and Access Management (IAM) role to a user for a resource, you might want to know what roles are available to grant on a particular resource.
Before you begin
-
Enable the IAM API.
Required roles
To get the permission that you need to list grantable roles,
ask your administrator to grant you the
Security Reviewer (roles/iam.securityReviewer
) IAM role on the resource that you want to list grantable roles for.
For more information about granting roles, see Manage access.
This predefined role contains the
getIamPolicy
permissions for all resource types. To list grantable roles, you need the getIamPolicy
permission for the resource that you want to list grantable roles for—for example, to list grantable roles for a project, you need the resourcemanager.projects.getIamPolicy
permission.
You might also be able to get this permission with custom roles or other predefined roles.
Understanding what roles are grantable
A role is grantable on or above a resource if it contains any permissions for
that resource type. For example, the storage.admin
role grants permissions to
the storage.buckets.get
and storage.objects.get
APIs, so it is grantable on
the Storage Buckets and Storage Objects resource types.
Roles can also be granted "above" the resource types that their permissions
are defined for. In other words, roles for lower-level resources can be granted
on a resource that is higher in the Google Cloud resource hierarchy. For
example, the storage.admin
role can also be granted at the project or
organization levels, in addition to Storage Buckets.
Permissions granted by a role only affect resources at the specified level or
below; they do not affect higher-level or peer resources. Additionally, when a
role is granted on a resource, only permissions applicable to the given resource
are granted, regardless of the role's name, description, or other permissions it
contains. For example, assigning the role resourcemanager.organizationAdmin
(which grants the permission resourcemanager.projects.list
) to a user on the
project level only grants them permissions for that specific project. It will
not allow them to list or administer all projects in the organization.
Similarly, assigning the compute.admin
role on a specific Compute Engine
instance only grants permissions for that instance, not others in the project.
Listing grantable roles
You can list grantable roles using the Google Cloud console, the Google Cloud CLI, the IAM API, or the IAM client libraries.
The Google Cloud console always lists all grantable roles for the resource you're viewing. The Google Cloud CLI, IAM API, and client libraries only list grantable roles for enabled APIs.
Console
To view grantable roles for a project, folder, or organization, do the following:
In the Google Cloud console, go to the IAM page.
Click Select a project at the top of the page.
Select the project, folder, or organization for which you want to view grantable roles.
Click
Grant access.Click Select a role. This menu displays all the roles, including any custom roles, that you can grant on this resource.
To view grantable roles for other resource types, do the following:
In the Google Cloud console, go to the page listing the resource for which you want to view grantable roles.
For example, to manage access to a Compute Engine instance, go to the VM instances page.
Select the checkbox next to the resource for which you want to view grantable roles.
Ensure that the info panel is visible. If it is not visible, click Show info panel.
Click
Add principal.Click Select a role. This menu displays all the roles, including any custom roles, that you can grant on this resource.
gcloud
Use the gcloud iam list-grantable-roles
command to return a list of all roles that can be applied to a given
resource.
gcloud iam list-grantable-roles full-resource-name
Depending on the desired resource, a large number of roles may be returned. To limit the results, you can specify a filter expression.
The output will look something like:
description: Full control of all Compute Engine resources.
name: roles/compute.admin
title: Compute Admin
---
description: Full control of Compute Engine instance resources.
name: roles/compute.instanceAdmin
title: Compute Instance Admin
# Additional results here...
REST
The
roles.queryGrantableRoles
method returns a list of all roles grantable on a resource.
Before using any of the request data, make the following replacements:
FULL_RESOURCE_NAME
: A URI consisting of the service name and the path to the resource. For examples, see Full resource names.
HTTP method and URL:
POST https://iam.googleapis.com/v1/roles:queryGrantableRoles
Request JSON body:
{ "fullResourceName": "FULL_RESOURCE_NAME" }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "roles": [ { "name": "roles/compute.admin", "title": "Compute Admin", "description": "Full control of all Compute Engine resources." }, { "name": "roles/compute.instanceAdmin", "title": "Compute Instance Admin (beta)", "description": "Full control of Compute Engine instance resources." } ] }
C++
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM C++ API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
C#
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM C# API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Go API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Java API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Python API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
In the examples above, the full resource name is a scheme-less URI consisting of a DNS-compatible API service name and a resource path.
For example, to return all roles grantable on a project, use:
//cloudresourcemanager.googleapis.com/projects/project-id
Lower-level resources have a more detailed fully qualified name. For example, use the following to return all roles grantable on a Compute Engine instance:
//compute.googleapis.com/projects/project-id/zones/zone-name/instances/instance-id
What's next
- Read about the available IAM roles.
- Find out how to choose the most appropriate predefined roles.
- Learn how to grant, change, and revoke a principal's access.
- See examples of resource names for different types of resources.