Viewing the Grantable Roles on Resources

Before you grant an IAM role to a user for a resource, you might want to know what roles are available to grant on a particular resource.

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 GCP 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

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 RESOURCE

Where RESOURCE is the fully qualified name for the desired resource. 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

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

Console

  1. Open the IAM page in the GCP Console.

    Open the IAM page

  2. Click on "Select a project" drop-down at the top of the page.
  3. Select the project or organization for which you want to view roles.
  4. Click Add.
  5. Enter the member email in Members.

The Roles drop-down displays all the roles (including the custom roles) that you can grant to the member on this resource.

API

QueryGrantableRoles returns a list of all roles grantable on a resource.

Request URL

POST https://iam.googleapis.com/v1/roles:queryGrantableRoles

Request body

{
    "fullResourceName": RESOURCE
}

Where RESOURCE is the fully qualified name for the desired resource. 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

Example output

{
    "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."
        }
        // Additional results here...
    ]
}

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Identity and Access Management Documentation