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

Before you list grantable roles, ensure that the service has been enabled in the project. If a service hasn't been enabled, its roles will not be returned.

Console

  1. Open the IAM page in the GCP Console.

    Open the IAM page

  2. Click the "Select a project" drop-down menu 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 or domain in Members.

The Select a role drop-down menu displays all the roles (including any custom roles) that you can grant to the member on this resource.

GCLOUD COMMAND

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 API

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

Request:

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

Body:

{
    "fullResourceName": [FULL-RESOURCE-NAME]
}

Response:

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

C#

Before trying this sample, follow the C# setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM C# API reference documentation .

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;
    }
}

Go

Before trying this sample, follow the Go setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Go API reference documentation .

import (
	"context"
	"fmt"
	"io"

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

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

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

Java

Before trying this sample, follow the Java setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Java API reference documentation .

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();
}

Python

Before trying this sample, follow the Python setup instructions in the Cloud IAM Quickstart Using Client Libraries . For more information, see the Cloud IAM Python API reference documentation .

def view_grantable_roles(full_resource_name):
    roles = service.roles().queryGrantableRoles(body={
        'fullResourceName': full_resource_name
    }).execute()

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

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]

To learn more about how full resource names are constructed, see the article Resource Names and the reference documentation for the API service you want to get grantable roles for.

What's next

Oliko tästä sivusta apua? Kerro mielipiteesi

Palautteen aihe:

Tämä sivu
Cloud IAM Documentation