Viewing the grantable roles on resources

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.

  Enable the API

• Set up authentication.

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  C#

  To use the .NET samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

  C++

  To use the C++ samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

  Go

  To use the Go samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

  Java

  To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

  Python

  To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command:

     gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

  For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions 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 to projects, folders, and organizations.

You might also be able to get these permissions 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.

gcloud iam list-grantable-roles full-resource-name

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

namespace iam = ::google::cloud::iam_admin_v1;
[](std::string const& resource) {
  iam::IAMClient client(iam::MakeIAMConnection());
  int count = 0;
  for (auto& role : client.QueryGrantableRoles(resource)) {
    if (!role) throw std::move(role).status();
    std::cout << "Role successfully retrieved: " << role->name() << "\n";
    ++count;
  }
  if (count == 0) {
    std::cout << "No grantable roles found in resource: " << resource << "\n";
  }
}

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class CustomRoles
{
    public static IList<Role> ViewGrantableRoles(string fullResourceName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var request = new QueryGrantableRolesRequest
        {
            FullResourceName = fullResourceName
        };
        var response = service.Roles.QueryGrantableRoles(request).Execute();
        foreach (var role in response.Roles)
        {
            Console.WriteLine("Title: " + role.Title);
            Console.WriteLine("Name: " + role.Name);
            Console.WriteLine("Description: " + role.Description);
            Console.WriteLine();
        }
        return response.Roles;
    }
}

import (
	"context"
	"fmt"
	"io"

	iam "google.golang.org/api/iam/v1"
)

// viewGrantableRoles lists roles grantable on a resource.
func viewGrantableRoles(w io.Writer, fullResourceName string) ([]*iam.Role, error) {
	ctx := context.Background()
	service, err := iam.NewService(ctx)
	if err != nil {
		return nil, fmt.Errorf("iam.NewService: %w", err)
	}

	request := &iam.QueryGrantableRolesRequest{
		FullResourceName: fullResourceName,
	}
	response, err := service.Roles.QueryGrantableRoles(request).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.QueryGrantableRoles: %w", err)
	}
	for _, role := range response.Roles {
		fmt.Fprintf(w, "Found grantable role: %v\n", role.Name)
	}
	return response.Roles, err
}

QueryGrantableRolesRequest request = new QueryGrantableRolesRequest();
request.setFullResourceName(fullResourceName);

QueryGrantableRolesResponse response = service.roles().queryGrantableRoles(request).execute();

for (Role role : response.getRoles()) {
  System.out.println("Title: " + role.getTitle());
  System.out.println("Name: " + role.getName());
  System.out.println("Description: " + role.getDescription());
  System.out.println();
}

def view_grantable_roles(full_resource_name: str) -> None:
    roles = (
        service.roles()
        .queryGrantableRoles(body={"fullResourceName": full_resource_name})
        .execute()
    )

    for role in roles["roles"]:
        if "title" in role:
            print("Title: " + role["title"])
        print("Name: " + role["name"])
        if "description" in role:
            print("Description: " + role["description"])
        print(" ")

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

{
  "fullResourceName": "FULL_RESOURCE_NAME"
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/roles:queryGrantableRoles"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/roles:queryGrantableRoles" | Select-Object -Expand Content

{
  "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."
    }
  ]
}

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.