Creating and managing custom roles

This page describes how to create and manage a custom role.

Before you begin

• Read Understanding IAM Custom Roles, which contains information about the permissions required to create custom roles and best practices.
• If you are using the gcloud command-line utility, make sure that you're using version 188.0.0 or later. To update gcloud to version 188.0.0, run the following command: gcloud components update --version 188.0.0

Viewing the available permissions for a resource

Before you create a custom role, you might want to know what permissions can be applied to a resource. You can get all permissions that can be applied to a resource, and the resources below that in the hierarchy, using the gcloud command-line tool, the Cloud Console, or the IAM API. For example, you can get all permissions that you can apply on an organization and on projects in that organization.

Console

1. Go to the Roles page in the Cloud Console.

   Open the Roles page

2. Select your project from the drop-down at the top of the page.
3. Select the checkbox for a resource's admin role to view all the permissions that you can apply on that resource. For example, when you select the Compute Instance Admin role, the right side panel displays all the permissions that you can apply on a Compute Engine instance.

gcloud command

Use the gcloud iam list-testable-permissions command to get a list of permissions that can be applied on a target resource. The returned permissions are the permissions that can be used to create a custom role at this resource and any resource below in the hierarchy.

The following example demonstrates how to list testable permissions for a project resource:

gcloud iam list-testable-permissions [PROJECT-ID]

[PROJECT-ID] is the ID of the project in the form of a full resource name: //cloudresourcemanager.googleapis.com/projects/PROJECT-ID, such as //cloudresourcemanager.googleapis.com/projects/my-project-id.

The list-testable-permissions command may return hundreds of results. To limit the results, you can also specify a filter expression. A truncated example of possible results is shown below:

---
name: appengine.applications.create
stage: GA
---
customRolesSupportLevel: TESTING
name: appengine.applications.disable
stage: GA
---
name: appengine.applications.get
stage: GA
---
customRolesSupportLevel: NOT_SUPPORTED
name: appengine.applications.list
onlyInPredefinedRoles: true
stage: GA
---
name: appengine.applications.update
stage: GA
---
name: appengine.instances.delete
stage: GA
---
name: appengine.instances.get
stage: GA
---

Note that each permission indicates whether it is supported in a custom role. For a complete list of supported and unsupported permissions, see Custom Roles Permissions Support.

REST API

QueryTestablePermissions returns all the permissions that can be applied on a resource. The returned permissions are the permissions that can be used to create a custom role at this resource and any resource below in the hierarchy. The only required input to this request is the full resource name such as //cloudresourcemanager.googleapis.com/projects/my-project.

Optionally, the caller can provide support for pagination if the resource has a long list of permissions.

Example

full_resource_name: '//cloudresourcemanager.googleapis.com/projects/my-project'

Error codes

Error Code	Status Message
INVALID_ARGUMENT	must be between 0 and 100
INVALID_ARGUMENT	Invalid pagination token encoding
INVALID_ARGUMENT	Invalid pagination token
INVALID_ARGUMENT	Pagination token is not for the specified container
INVALID_ARGUMENT	Invalid starting point in pagination token
INVALID_ARGUMENT	Invalid pagination token cookie
INVALID_ARGUMENT	Expired pagination token
INVALID_ARGUMENT	{full_resource_name} must be specified
INVALID_ARGUMENT	{full_resource_name}, does not match //[a-z0-9.-]/.a-z0-9.-]/.

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 .

View on GitHub Feedback

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<Permission> QueryTestablePermissions(
        string fullResourceName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var request = new QueryTestablePermissionsRequest
        {
            FullResourceName = fullResourceName
        };
        var response = service.Permissions.QueryTestablePermissions(request)
            .Execute();
        foreach (var p in response.Permissions)
        {
            Console.WriteLine(p.Name);
        }
        return response.Permissions;
    }
}

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 .

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

// queryTestablePermissions lists testable permissions on a resource.
func queryTestablePermissions(w io.Writer, fullResourceName string) ([]*iam.Permission, 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.QueryTestablePermissionsRequest{
		FullResourceName: fullResourceName,
	}
	response, err := service.Permissions.QueryTestablePermissions(request).Do()
	if err != nil {
		return nil, fmt.Errorf("Permissions.QueryTestablePermissions: %v", err)
	}
	for _, p := range response.Permissions {
		fmt.Fprintf(w, "Found permissions: %v", p.Name)
	}
	return response.Permissions, nil
}

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 .

View on GitHub Feedback

def query_testable_permissions(resource):
    """Lists valid permissions for a resource."""

    # pylint: disable=no-member
    permissions = service.permissions().queryTestablePermissions(body={
        'fullResourceName': resource
    }).execute()['permissions']
    for p in permissions:
        print(p['name'])

Getting the role metadata

Before you create a custom role, you might want to get the metadata for both predefined and custom roles. Role metadata includes the role ID and permissions contained in the role. You can view the metadata using the Google Cloud Platform Console or the IAM API.

To view the role metadata, use one of the methods below:

Console

1. Go to the Roles page in the Cloud Console.

   Open the Roles page

2. Select your organization or project from the drop-down at the top of the page.
3. Select the checkbox for one or more roles to view the role permissions. The right side panel displays the permissions contained in the role(s), if any.

The icons beside the role indicate if it's a custom role ("factory" icon) or a predefined role (hexagon icon).

If you want to find all the roles that include a specific permission, type the permission name in the Filter box at the top of the Roles list.

gcloud command

Use the gcloud iam roles describe command to view metadata for predefined roles and custom roles.

To view the metadata for a predefined role, execute the following gcloud command:

gcloud iam roles describe [ROLE-NAME]

[ROLE-NAME] is the name of the role, such as roles/viewer.

The following example demonstrates the output of the describe command when executed on the predefined role roles/iam.roleViewer:

gcloud iam roles describe roles/iam.roleViewer

description: Read access to all custom roles in the project.
etag: AA==
includedPermissions:
- iam.roles.get
- iam.roles.list
- resourcemanager.projects.get
- resourcemanager.projects.getIamPolicy
name: roles/iam.roleViewer
stage: GA
title: Role Viewer

To view the metadata for a custom role, first determine whether the custom role was created at the organization or project level. If the custom role was created at the organization level, execute the following gcloud command:

gcloud iam roles describe --organization [ORGANIZATION-ID] [ROLE-NAME]

[ORGANIZATION-ID] is the ID of the organization in the form of: 1234567. [ROLE-NAME] is the name of the custom role, such as myCustomRole.

To view the metadata for a project-level custom role, execute the following gcloud command:

gcloud iam roles describe --project [PROJECT-ID] [ROLE-NAME]

[PROJECT-ID] is the ID of the project, such as my-project-id. [ROLE-NAME] is the name of the custom role, such as myCustomRole.

For more information, see the reference documentation for gcloud iam roles describe.

REST API

If you know the role name of the role you want to view, use the roles.get method to get a custom role. If you don't know the role name, use the roles.list method to list all custom roles in an organization or a project.

To call GetRole(), set the following field in the GetRoleRequest:

• Name of the role such as roles/{ROLE-NAME} or organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}.

To call ListRoles(), set the following field in the ListRolesRequest:

• The parent for which you want to get all custom roles, such as organizations/{ORGANIZATION-ID} or projects/{PROJECT-ID}.

Error codes

Error code	Status Message
PERMISSION_DENIED	You don't have permission to get the role at {path}
NOT_FOUND	The role named {role} was not found.
INVALID_ARGUMENT	The role name must be in the form roles/{role}, or organizations/{organization-id}/roles/{role}.
PERMISSION_DENIED	You don't have permission to list roles in {path}.
INVALID_ARGUMENT	The parent{path} is invalid. The parent must be in the form organizations/{organization-id} or empty.
INVALID_ARGUMENT	Role view is not valid.

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 .

View on GitHub Feedback

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

public partial class CustomRoles
{
    public static Role GetRole(string name)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = service.Roles.Get(name).Execute();
        Console.WriteLine(role.Name);
        Console.WriteLine(String.Join(", ", role.IncludedPermissions));
        return role;
    }
}

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 .

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

// getRole gets role metadata.
func getRole(w io.Writer, name 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)
	}

	role, err := service.Roles.Get(name).Do()
	if err != nil {
		return nil, fmt.Errorf("Roles.Get: %v", err)
	}
	fmt.Fprintf(w, "Got role: %v\n", role.Name)
	for _, permission := range role.IncludedPermissions {
		fmt.Fprintf(w, "Got permission: %v\n", permission)
	}
	return role, nil
}

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 .

View on GitHub Feedback

def get_role(name):
    """Gets a role."""

    # pylint: disable=no-member
    role = service.roles().get(name=name).execute()
    print(role['name'])
    for permission in role['includedPermissions']:
        print(permission)

Creating a custom role

To create a custom role, a caller must possess iam.roles.create permission. By default, the owner of a project or an organization has this permission and can create and manage custom roles.

Users who are not owners, including organization admins, must be assigned either the Organization Role Administrator role, or the IAM Role Administrator role.

Console

To create a new custom role from scratch:

1. Go to the Roles page in the Cloud Console.

   Open the Roles page

2. Select your organization from the Organization drop-down.
3. Click Create Role.
4. Enter a Name, a Title, and Description for the role.
5. Click Add Permissions.
6. Select the permissions you want to include in the role and click Add Permissions. Use the All Services and All Types drop-downs to filter and select permissions by services and types.

Creating a custom role based on an existing predefined role:

1. Go to the Roles page in the Cloud Console.

   Open the Roles page

2. Select your organization from the Organization drop-down.
3. Select the roles on which you want to base the new custom role.
4. Click Create Role from Selection.
5. Enter a Name, a Title, and Description for the role.
6. Uncheck the permissions you want to exclude from the role.
7. Click Add Permissions to include any permissions.
8. Click Create.

gcloud command

Use the gcloud iam roles create command to create new custom roles. You can use this command in two ways:

• By providing a YAML file that contains the role definition
• By using flags to specify the role definition

When creating a custom role, you must specify whether it applies to the organization level or project level by using the --organization [ORGANIZATION-ID] or --project [PROJECT-ID] flags. Each example below creates a custom role at the project level.

To create a custom role using a YAML file:

Create a YAML file that contains the definition for your custom role. The file must be structured in the following way:

title: [ROLE-TITLE]
description: [ROLE-DESCRIPTION]
stage: [LAUNCH-STAGE]
includedPermissions:
- [PERMISSION-1]
- [PERMISSION-2]

Each of the placeholder values is described below:

• [ROLE-TITLE] is a friendly title for the role, such as "Role Viewer".
• [ROLE-DESCRIPTION] is a short description about the role, such as "My custom role description".
• [LAUNCH-STAGE] indicates the stage of a role in the launch lifecycle, such as ALPHA, BETA, or GA.
• includedPermissions specifies the list of one or more permissions to include in the custom role, such as - iam.roles.get.

Save the YAML file, and then execute the following gcloud command:

gcloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

Each of the placeholder values is described below:

• [ROLE-ID] is the name of the role, such as viewer.
• [PROJECT-ID] is the name of the project, such as my-project-id.
• [YAML_FILE-PATH] is the path to the location of your YAML file that contains the custom role definition.

The following example YAML file demonstrates how to create a role definition:

title: "Role Viewer"
description: "My custom role description."
stage: "ALPHA"
includedPermissions:
- iam.roles.get
- iam.roles.list

The following example demonstrates how to create a role using the YAML file:

gcloud iam roles create viewer --project my-project-id \
--file my-role-definition.yaml

If the role was created successfully, the following response is returned:

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

To create a custom role using flags:

Execute the following gcloud command:

cloud iam roles create [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--permissions [PERMISSIONS-LIST] --stage [LAUNCH-STAGE]

Each of the placeholder values is described below:

• [ROLE-ID] is the name of the role, such as viewer.
• [PROJECT-ID] is the name of the project, such as my-project-id.
• [ROLE-TITLE] is a friendly title for the role, such as "Role Viewer".
• [ROLE-DESCRIPTION] is a short description about the role, such as "My custom role description.".
• [PERMISSIONS-LIST] contains a comma-separated list of permissions you want to include in the custom role. For example: iam.roles.get,iam.roles.list.
• [LAUNCH-STAGE] indicates the stage of a role in the launch lifecycle, such as ALPHA, BETA, or GA.

The following example demonstrates how to create a role using flags:

gcloud iam roles create viewer --project my-project-id \
--title "Role Viewer" --description "My custom role description." \
--permissions iam.roles.get,iam.roles.list --stage ALPHA

If the role was created successfully, the following response is returned:

Created role [viewer].
description: My custom role description.
etag: BwVkBX0sQD0=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

REST API

Use the create method to create a new custom role.

Set the following required parameters in the request:

• The role_id that you want to use for the new custom role, such as appengine.myCustomStorageAuditor.
• Description of the custom role, such as "This role grants access to list storage resources, their capacity, and access policies".
• A list of permissions you want to associate with this role.
• Note that setting the name field in the role will result in an error.

We recommend that you also set the following optional parameters:

• Title for the custom role, such as "Example Custom Role Editor".
• Set a value for the stage, such as GA.

stage takes the following values: ALPHA, BETA, GA, DEPRECATED, or DISABLED.

Some predefined roles contain deprecated permissions or permissions that are otherwise not permitted in custom roles. Creating a custom role based on a predefined role that contains any deprecated or restricted permissions will fail.

Example

parent: '[PARENT-NAME]'
role_id: '[ROLE-ID]'
role {
    name: ''
    title: '[ROLE-TITLE]'
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})",

Where:

• [PARENT-NAME] is the name of either the organization in which you're creating the custom role, for example organizations/0000000000000001, or the project ID in which you're creating the custom role, for example projects/my-project.
• [ROLE-ID] is the ID of the custom role. For example appengine.myCustomStorageAuditor.
• [ROLE-TITLE] is the title for the role. For example, Storage Auditor.
• [ROLE-DESCRIPTION] is the description for what the role does.
• [PERMISSION] is the permission you want to include in the custom role.

Note: When calling create, the name field of the role in the request should not be set. Upon creation, the custom role's name will be set to either organizations/{ORGANIZATION-ID}/roles/{ROLE-ID}, or projects/{PROJECT-ID}/roles/{ROLE-ID}.

Error codes

Error Code	Status Message
PERMISSION_DENIED	You don't have permission to create a role in {parent}.
ALREADY_EXISTS	A role named {role-id} in {parent} already exists.
INVALID_ARGUMENT	The parent {parent} is invalid. The parent must be in the form organizations/{organization-id}.
INVALID_ARGUMENT	The role_id {role-id} is invalid. It doesn't match pattern {pattern}.
INVALID_ARGUMENT	The number of permissions in the role is greater than the maximum of {max}.
INVALID_ARGUMENT	The role.stage {stage} is invalid.

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 .

View on GitHub Feedback

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 Role CreateRole(string name, string projectId, string title,
        string description, IList<string> permissions, string stage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var role = new Role
        {
            Title = title,
            Description = description,
            IncludedPermissions = permissions,
            Stage = stage
        };
        var request = new CreateRoleRequest
        {
            Role = role,
            RoleId = name
        };
        role = service.Projects.Roles.Create(request,
            "projects/" + projectId).Execute();
        Console.WriteLine("Created role: " + role.Name);
        return role;
    }
}

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 .

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

// createRole creates a custom role.
func createRole(w io.Writer, projectID, name, title, description, stage string, permissions []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.CreateRoleRequest{
		Role: &iam.Role{
			Title:               title,
			Description:         description,
			IncludedPermissions: permissions,
			Stage:               stage,
		},
		RoleId: name,
	}
	role, err := service.Projects.Roles.Create("projects/"+projectID, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Create: %v", err)
	}
	fmt.Fprintf(w, "Created role: %v", role.Name)
	return role, nil
}

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 .

View on GitHub Feedback

def create_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().create(
        parent='projects/' + project,
        body={
            'roleId': name,
            'role': {
                'title': title,
                'description': description,
                'includedPermissions': permissions,
                'stage': stage
            }
        }).execute()

    print('Created role: ' + role['name'])
    return role

Editing an existing custom role

Read-Modify-Write

A common pattern for updating a resource's metadata, such as a custom role, is to read its current state, update the data locally, and then send the modified data for writing. This pattern could cause a conflict if two or more independent processes attempt the sequence simultaneously. For example, if two owners for a project try to make conflicting changes to a role at the same time, some changes could fail. Cloud IAM solves this problem using an etag property in custom roles. This property is used to verify if the custom role has changed since the last request. When you make a request to Cloud IAM with an etag value, Cloud IAM compares the etag value in the request with the existing etag value associated with the custom role. It writes the change only if the etag values match.

When you update a role, first get the role using roles.get(), update the role, and then write the updated role using roles.patch(). Use the etag value when setting the role only if the corresponding role in roles.get() contains an etag value.

Note: When modifying a custom role by adding or removing any of the following permissions: resourcemanager.organizations.get, resourcemanager.folders.get, and resourcemanager.projects.get, the change to the custom role may require up to 24 hours to take effect for the organizations.search and folders.search Cloud Resource Manager APIs. The API projects.list is also subject to this delay for API calls that do not provide a filter specifying a parent type and ID. This delay occurs because these permissions involve search functionality, and it can take up to 24 hours between rebuilds of the search index.

Console

1. Go to the Roles page in the Cloud Console.

   Open the Roles page

2. Select your organization from the Organization drop-down.
3. Click on a custom role.
4. Click Edit Role.
5. Click Add Permissions to add new permissions to the role.
6. Uncheck permissions to remove permissions from the role.
7. Click Update to save the edited role.

gcloud command

Use the gcloud iam roles update command to update custom roles. You can use this command in two ways:

• By providing a YAML file that contains the updated role definition
• By using flags to specify the updated role definition

When updating a custom role, you must specify whether it applies to the organization level or project level by using the --organization [ORGANIZATION-ID] or --project [PROJECT-ID] flags. Each example below creates a custom role at the project level.

To update a custom role using a YAML file:

Get the current definition for the role by executing the following gcloud command:

gcloud iam roles describe [ROLE-ID] --project [PROJECT-ID]

Each of the placeholder values is described below:

• [ROLE-ID] is the name of the role to update, such as viewer.
• [PROJECT-ID] is the name of the project, such as my-project-id.

The describe command returns the role's definition and includes an etag value that uniquely identifies the current version of the role. The etag value should be provided in the updated role definition to ensure that any concurrent role changes are not overwritten.

The describe command returns the following output:

description: [ROLE-DESCRIPTION]
etag: [ETAG-VALUE]
includedPermissions:
- [PERMISSION-1]
- [PERMISSION-2]
name: [ROLE-ID]
stage: [LAUNCH-STAGE]
title: [ROLE-TITLE]

Each of the placeholder values is described below:

• [ROLE-DESCRIPTION] is a short description about the role, such as "My custom role description".
• [ETAG-VALUE] is the unique identifier for the current version of the role, such as BwVkBkbfr70=.
• includedPermissions specifies the list of one or more permissions to include in the custom role, such as - iam.roles.get.
• [ROLE-ID] is the hierarchical ID for the role, depending on whether it was created at the project or organization level. For example: projects/my-project-id/roles/viewer
• [LAUNCH-STAGE] indicates the stage of a role in the launch lifecycle, such as ALPHA, BETA, or GA.
• [ROLE-TITLE] is a friendly title for the role, such as "Role Viewer".

To update the role, either include the outputted role definition to a YAML file or update the original YAML file with the outputted etag value.

Consider the following example YAML file, which contains the output from the describe command and adds two Cloud Storage permissions:

description: My custom role description.
etag: BwVkBkbfr70=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

Save the YAML file, and then execute the following gcloud command:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--file [YAML_FILE-PATH]

Each of the placeholder values is described below:

• [ROLE-ID] is the name of the role to update, such as viewer.
• [PROJECT-ID] is the name of the project, such as my-project-id.
• [YAML_FILE-PATH] is the path to the location of your YAML file that contains the updated custom role definition.

The following example demonstrates how to update a role using the YAML file:

gcloud iam roles update viewer --project my-project-id \
--file my-role-definition.yaml

If the role was updated successfully, the following response is returned:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

To update a custom role using flags:

Each part of a role definition can be updated using a corresponding flag. See the gcloud iam roles update topic for a list of all possible flags.

You can use the following flags to add or remove permissions:

• --add-permissions [PERMISSIONS]: Adds one or more comma-separated permissions to the role.
• --remove-permissions [PERMISSIONS]: Removes one or more comma-separated permissions from the role.

Alternatively, you can simply specify the new permissions using the --permissions [PERMISSIONS] flag and providing a comma-separated list of permissions to replace the existing permissions list.

To update other aspects of the role definition, execute the following gcloud command:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--title [ROLE-TITLE] --description [ROLE-DESCRIPTION] \
--stage [LAUNCH-STAGE]

Each of the placeholder values is described below:

• [ROLE-ID] is the name of the role, such as viewer.
• [PROJECT-ID] is the name of the project, such as my-project-id.
• [ROLE-TITLE] is a friendly title for the role, such as "Role Viewer".
• [ROLE-DESCRIPTION] is a short description about the role, such as "My custom role description.".
• [LAUNCH-STAGE] indicates the stage of a role in the launch lifecycle, such as ALPHA, BETA, or GA.

The following example demonstrates how to add permissions to a role using flags:

gcloud iam roles update viewer --project my-project-id \
--add-permissions storage.buckets.get,storage.buckets.list

If the role was updated successfully, the following response is returned:

description: My custom role description.
etag: BwVkBwDN0lg=
includedPermissions:
- iam.roles.get
- iam.roles.list
- storage.buckets.get
- storage.buckets.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

REST API

Use the Role UpdateRole(UpdateRoleRequest) method to edit an existing custom role.

If you know the role ID of the custom role you wish to edit, get the role using the roles.get() method and then update the role using roles.patch().

If you don't know the role ID of the custom role you wish to edit, list all the roles using ListRoles() to identify the role. roles.list() returns a list of all roles referencing the resource. Then update the role using roles.patch().

Set the following required parameter in the roles.patch():

• Name of the role such as organizations/{ORGANIZATION-ID}/roles/{ROLE-ID}.

Optionally set the update_mask field to specify the field(s) that can be updated in the future.

Example

name: '[ROLE-NAME]'
role {
    name: '[ROLE-NAME]'
    title: '[ROLE-TITLE]'
    description: '[ROLE-DESCRIPTION]'
    included_permissions: '[PERMISSION]'
    included_permissions: '[PERMISSION]'
})"

Where:

• [ROLE-NAME] is the name of the role. For example, organizations/123456/roles/appengine.customRoleEditor. Can be in the form roles/{ROLE-NAME}, organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}, or projects/{PROJECT-ID}/roles/{ROLE-NAME}

  Note: Leaving the [ROLE-NAME] that is inside the role empty is recommended. The method will return an error if the two names are not identical and the name inside role is not empty.

• [ROLE-TITLE] is the title for the role. For example, New custom editor.

• [ROLE-DESCRIPTION] is a description for the role. For example, "My new long description of editor".
• [PERMISSION] is the permission that you want to include in the role. For example, storage.objects.update.

Error codes

Error Code	Status Message
PERMISSION_DENIED	You don't have permission to update the role.
INVALID_ARGUMENT	Predefined roles cannot be updated.
INVALID_ARGUMENT	The name in the request ([ROLE-NAME]) and the name in the role ([ROLE-NAME]) must match.
INVALID_ARGUMENT	Permission [PERMISSION] is not valid.
ABORTED	There were concurrent policy changes, since the etag did not match. Please retry the entire read-modify-write with exponential backoff.

Some predefined roles contain deprecated permissions or permissions that are otherwise not permitted in custom roles. Creating a custom role based on a predefined role that contains any deprecated or restricted permissions will fail.

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 .

View on GitHub Feedback

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 Role EditRole(string name, string projectId, string newTitle,
        string newDescription, IList<string> newPermissions, string newStage)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });
        // First, get a Role using List() or Get().
        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Get(resource).Execute();
        // Then you can update its fields.
        role.Title = newTitle;
        role.Description = newDescription;
        role.IncludedPermissions = newPermissions;
        role.Stage = newStage;
        role = service.Projects.Roles.Patch(role, resource).Execute();
        Console.WriteLine("Updated role: " + role.Name);
        return role;
    }
}

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 .

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

// editRole modifies a custom role.
func editRole(w io.Writer, projectID, name, newTitle, newDescription, newStage string, newPermissions []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)
	}

	resource := "projects/" + projectID + "/roles/" + name
	role, err := service.Projects.Roles.Get(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Get: %v", err)
	}
	role.Title = newTitle
	role.Description = newDescription
	role.IncludedPermissions = newPermissions
	role.Stage = newStage
	role, err = service.Projects.Roles.Patch(resource, role).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Patch: %v", err)
	}
	fmt.Fprintf(w, "Updated role: %v", role.Name)
	return role, nil
}

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 .

View on GitHub Feedback

def edit_role(name, project, title, description, permissions, stage):
    """Creates a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'title': title,
            'description': description,
            'includedPermissions': permissions,
            'stage': stage
        }).execute()

    print('Updated role: ' + role['name'])
    return role

Disabling a custom role

You can disable a custom role. When a role is disabled, any policy bindings related to the role are inactivated, meaning that the permissions in the role will not be granted, even if you grant the role to a user.

Console

1. Go to the Roles page in the Cloud Console.

   Open the Roles page

2. Click on "Select a project" drop-down at the top of the page.
3. Select your organization or project.
4. Select a custom role and click Disable.

gcloud command

Use the gcloud iam roles update command to disable a custom role by setting its launch stage to DISABLED. As described in the gcloud tab of the Editing an existing custom role section, you can update an existing custom role in the following two ways:

• By providing a YAML file that contains the updated role definition
• By using flags to specify the updated role definition

The easiest way to disable an existing custom role is to use the --stage flag and set it to DISABLED. Execute the following gcloud command:

gcloud iam roles update [ROLE-ID] --project [PROJECT-ID] \
--stage DISABLED

Each of the placeholder values is described below:

• [ROLE-ID] is the name of the role, such as viewer.
• [PROJECT-ID] is the name of the project, such as my-project-id. You can also use the --organization [ORGANIZATION-ID] flag if the role was created at the organization level, such as 1234567.

The following example demonstrates how to disable a role:

gcloud iam roles update viewer --project my-project-id \
--stage DISABLED

If the role was updated successfully, the following response is returned:

description: My custom role description.
etag: BwVkB5NLIQw=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: DISABLED
title: Role Viewer

REST API

Use the roles.patch() method to disable a custom role.

If you know the role ID of the custom role you wish to disable, get the role using the roles.get() method. Change the stage property of the role to DISABLED, and then call the roles.patch() method to update role.

If you don't know the role ID of the custom role you wish to disable, list all the roles using roles.list() to identify the role. roles.list() returns a list of all roles referencing the resource. Identify the role you wish to disable, change its rolelaunchstage property to DISABLED, and then call the roles.patch() method to update role.

To disable a role, set the following fields:

• Set name to the full name of the role, organizations/{organization-id}/roles/{role}.
• In the Role, set the stage to DISABLED.
• Set the update_mask to 'paths: stage'.

To re-enable the role, follow the same process above as disable the role, but set the stage property of role to ALPHA, \ BETA, or GA.

Example

name: 'organizations/123456/roles/appengine.customRoleEditor'
role {
    name: 'organizations/123456/roles/appengine.customRoleEditor'`
    stage: 'DISABLED'
}
update_mask {
    paths:  stage
}

Error codes

Error Code	Status Message
PERMISSION_DENIED	You don't have permission to update the role
INVALID_ARGUMENT	Curated roles cannot be updated.
INVALID_ARGUMENT	The name in the request ([ROLE-NAME]) and the name in the role ([ROLE-NAME]) must match.
INVALID_ARGUMENT	Permission [PERMISSION] is not valid.
ABORTED	There were concurrent policy changes. Please retry the whole read-modify-write with exponential backoff.

C#

Update the stage field of the role to DISABLED.

Go

Update the stage field of the role to DISABLED.

Python

Update the stage field of the role to DISABLED.

Listing the roles

Console

1. Go to the Roles page in the Cloud Console.

   Open the Roles page

   
   All the custom roles for the the project are listed on the page.

gcloud command

Use the gcloud iam roles list command to list custom roles and predefined roles for a project or organization.

Execute the following gcloud command to list custom roles, specifying either project-level or organization-level custom roles:

gcloud iam roles list --project [PROJECT-ID]

[PROJECT-ID] is the name of the project, such as my-project-id. You can also use the --organization [ORGANIZATION-ID] flag if the role was created at the organization level, such as 1234567.

To list deleted roles, you can also specify the --show-deleted flag.

Execute the following gcloud command to list predefined roles:

gcloud iam roles list

REST API

The roles.list() method can be used to list all custom roles defined in an organization or project; it can also be used to list the predefined roles by setting the parent field in the request to "".

To call roles.list(), set the following field in the request:

• The parent that you want to use to get all custom roles for, such as
  • projects/{PROJECT-ID}
  • organizations/{ORGANIZATION-ID}

If you want the result to contain the permissions of each role set the view field to RoleView::FULL.

If you want the result to contain roles that have been recently deleted set the showDeleted field to true.

If you want to list all predefined roles, set the parent to "" (empty string).

Error codes

Error Code	Status Message
PERMISSION_DENIED	You don't have permission to list roles in {path}.
INVALID_ARGUMENT	The parent {path} is invalid. The parent must be in the form organizations/{organization-id}, projects/{project-id} or empty.
INVALID_ARGUMENT	Role view is not valid.

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 .

View on GitHub Feedback

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> ListRoles(string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var response = service.Projects.Roles.List("projects/" + projectId)
            .Execute();
        foreach (var role in response.Roles)
        {
            Console.WriteLine(role.Name);
        }
        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 .

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

// listRoles lists a project's roles.
func listRoles(w io.Writer, projectID 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)
	}

	response, err := service.Projects.Roles.List("projects/" + projectID).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.List: %v", err)
	}
	for _, role := range response.Roles {
		fmt.Fprintf(w, "Listing role: %v\n", role.Name)
	}
	return response.Roles, nil
}

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 .

View on GitHub Feedback

def list_roles(project_id):
    """Lists roles."""

    # pylint: disable=no-member
    roles = service.roles().list(
        parent='projects/' + project_id).execute()['roles']
    for role in roles:
        print(role['name'])

Deleting a custom role

Console

1. Go to the Roles page in the Cloud Console.

   Open the Roles page

2. Select the role you wish to delete and click on the trash icon on top of the page.

gcloud command

Use the gcloud iam roles delete command to delete a custom role. The role is suspended and cannot be used to create new IAM policy bindings.

Execute the following gcloud command to delete a custom roles:

gcloud iam roles delete [ROLE-ID] --project [PROJECT-ID]

Each of the placeholder values is described below:

• [ROLE-ID] is the name of the role, such as viewer.
• [PROJECT-ID] is the name of the project, such as my-project-id. You can also use the --organization [ORGANIZATION-ID] flag if the role was created at the organization level, such as 1234567.

The role will not be included in gcloud iam roles list, unless the --show-deleted flag is included. Deleted roles are indicated by the deleted: true block in a list response, such as:

---
deleted: true
description: My custom role description.
etag: BwVkB5NLIQw=
name: projects/my-project-id/roles/viewer
title: Role Viewer
---

REST API

roles.delete deletes a role. The role is suspended and cannot be used to create new IAM policy bindings.

The name can be in the following formats

• organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
• projects/{PROJECT-ID}/roles/{ROLE-NAME}

Error codes

Error Code	Status Message
PERMISSION_DENIED	You don't have permission to delete the role at {path}.
FAILED_PRECONDITION	You can't delete role {ROLE-NAME} as it is already deleted.
FAILED_PRECONDITION	You can't delete a role {ROLE-NAME} that is reserved.
INVALID_ARGUMENT	Curated roles cannot be in a deleted state.

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 .

View on GitHub Feedback

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

public partial class CustomRoles
{
    public static void DeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        service.Projects.Roles.Delete(
            $"projects/{projectId}/roles/{name}").Execute();
        Console.WriteLine("Deleted role: " + name);
    }
}

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 .

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

// deleteRole deletes a custom role.
func deleteRole(w io.Writer, projectID, name string) error {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return fmt.Errorf("iam.New: %v", err)
	}

	_, err = service.Projects.Roles.Delete("projects/" + projectID + "/roles/" + name).Do()
	if err != nil {
		return fmt.Errorf("Projects.Roles.Delete: %v", err)
	}
	fmt.Fprintf(w, "Deleted role: %v", name)
	return nil
}

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 .

View on GitHub Feedback

def delete_role(name, project):
    """Deletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().delete(
        name='projects/' + project + '/roles/' + name).execute()

    print('Deleted role: ' + name)
    return role

When a role is deleted, its bindings remain, but are inactive. You can undelete a role within 7 days. During this 7 day period, the role will show as Deleted in the Cloud Console, and will not appear in programmatic list commands (unless showDeleted is set in the request).

After 7 days, the role is scheduled for permanent deletion. This process takes 30 days. During the 30 day window, the role and all associated bindings are permanently removed, and you cannot create a new role with the same role ID.

After the role has been permanently deleted, 37 days after the initial deletion request, you can create a new role using the same role ID.

Undeleting a custom role

Console

1. Go to the Roles page in the Cloud Console.

   Open the Roles page

2. Locate the role you wish to undelete, click on the more icon at the end of the row, and click Undelete.

The role can only be undeleted within 7 days of deletion. After 7 days the role is permanently deleted and all bindings associated with the role are removed.

gcloud command

Use the gcloud iam roles undelete command to undelete a custom role. When you undelete a role, it's returned back to its previous state.

The role can only be undeleted within 7 days of deletion. After 7 days the role is permanently deleted and all bindings associated with the role are removed.

Execute the following gcloud command to undelete a custom role:

gcloud iam roles undelete [ROLE-ID] --project [PROJECT-ID]

Each of the placeholder values is described below:

• [ROLE-ID] is the name of the role, such as viewer.
• [PROJECT-ID] is the name of the project, such as my-project-id. You can also use the --organization [ORGANIZATION-ID] flag if the role was created at the organization level, such as 1234567.

The following example demonstrates how to undelete a custom role:

gcloud iam roles undelete viewer --project my-project-id

If the role was undeleted successfully, the following response is returned:

description: My custom role description.
etag: BwVkCAx9W6w=
includedPermissions:
- iam.roles.get
- iam.roles.list
name: projects/my-project-id/roles/viewer
stage: ALPHA
title: Role Viewer

REST API

roles.undelete brings a role back to its previous state.

The name can be in the following formats

• organizations/{ORGANIZATION-ID}/roles/{ROLE-NAME}
• projects/{PROJECT-ID}/roles/{ROLE-NAME}

The role can only be undeleted within 7 days of deletion. After 7 days the role is permanently deleted and all bindings associated with the role are removed.

Error codes

Error Code	Status Message
PERMISSION_DENIED	You don't have permission to undelete the role at {path}.
FAILED_PRECONDITION	A role that is not deleted cannot be undeleted.
FAILED_PRECONDITION	You can't undelete a role {ROLE-NAME} which is reserved.
INVALID_ARGUMENT	Predefined roles cannot be undeleted.

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 .

View on GitHub Feedback

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

public partial class CustomRoles
{
    public static Role UndeleteRole(string name, string projectId)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        string resource = $"projects/{projectId}/roles/{name}";
        var role = service.Projects.Roles.Undelete(
            new UndeleteRoleRequest(), resource).Execute();
        Console.WriteLine("Undeleted role: " + role.Name);
        return role;
    }
}

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 .

View on GitHub Feedback

import (
	"context"
	"fmt"
	"io"

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

// undeleteRole restores a deleted custom role.
func undeleteRole(w io.Writer, projectID, name 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)
	}

	resource := "projects/" + projectID + "/roles/" + name
	request := &iam.UndeleteRoleRequest{}
	role, err := service.Projects.Roles.Undelete(resource, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.Roles.Undelete: %v", err)
	}
	fmt.Fprintf(w, "Undeleted role: %v", role.Name)
	return role, nil
}

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 .

View on GitHub Feedback

def undelete_role(name, project):
    """Undeletes a role."""

    # pylint: disable=no-member
    role = service.projects().roles().patch(
        name='projects/' + project + '/roles/' + name,
        body={
            'stage': 'DISABLED'
        }).execute()

    print('Disabled role: ' + role['name'])
    return role