Console
    Contact Us Start free

    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.

        Install the Google Cloud CLI.

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

        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.

        If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity .

      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.

        Install the Google Cloud CLI.

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

        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.

        If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity .

      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.

        Install the Google Cloud CLI.

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

        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.

        If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity .

      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.

        Install the Google Cloud CLI.

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

        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.

        If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity .

      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.

        Install the Google Cloud CLI.

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

        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.

        If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity .

      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.

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

      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 .

    This 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 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 notallow 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:

    1. In the Google Cloud console, go to the IAMpage.

      Go to the IAM page

    2. Click Select a projectat the top of the page.

    3. Select the project, folder, or organization for which you want to view grantable roles.

    4. Click Grant access.

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

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

      Go to VM instances

    2. Select the checkbox next to the resource for which you want to view grantable roles.

    3. Ensure that the info panel is visible. If it is not visible, click Show info panel.

    4. Click Add principal.

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

    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 Before you begin .

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

    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 Before you begin .

      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

    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 Before you begin .

      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 
 }

    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 Before you begin .

      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

    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 Before you begin .

      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 
 ( 
 " " 
 )

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

    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
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: