Creating and Managing Custom Roles

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

Before you begin

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

    Open the Roles page

  2. Select your project from the dropdown 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.

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/buckets/bucket1'`

Error codes

Error CodeStatus Message
INVALID_ARGUMENTmust be between 0 and 100
INVALID_ARGUMENTInvalid pagination token encoding
INVALID_ARGUMENTInvalid pagination token
INVALID_ARGUMENTPagination token is not for the specified container
INVALID_ARGUMENTInvalid starting point in pagination token
INVALID_ARGUMENTInvalid pagination token cookie
INVALID_ARGUMENTExpired pagination token
INVALID_ARGUMENT{full_resource_name} must be specified
INVALID_ARGUMENT{full_resource_name}, does not match //[a-z0-9.-]/.a-z0-9.-]/.

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

Role icons

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.

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 CodeStatus Message
PERMISSION_DENIEDYou don't have permission to get the role at {path}
NOT_FOUNDThe role named {role} was not found.
INVALID_ARGUMENTThe role name must be in the form roles/{role}, or organizations/{organization_id}/roles/{role}.
PERMISSION_DENIEDYou don't have permission to list roles in {path}.
INVALID_ARGUMENTThe parent{path} is invalid. The parent must be in the form organizations/{organization_id} or empty.
INVALID_ARGUMENTRole view is not valid.

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 Platform 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 curated role:

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

    Open the Roles page

  2. Select your organization from the Organization drop-down.
  3. Select the roles based on which you want to create 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.

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.

Error codes

Error CodeStatus Message
PERMISSION_DENIEDYou don't have permission to create a role in {parent}.
ALREADY_EXISTSA role named {role_id} in {parent} already exists.
INVALID_ARGUMENTThe parent {parent} is invalid. The parent must be in the form organizations/{organization_id}.
INVALID_ARGUMENTThe role_id {role_id} is invalid. It doesn't match pattern {pattern}.
INVALID_ARGUMENTThe number of permissions in the role is greater than the maximum of {max}.
INVALID_ARGUMENTThe role.stage {stage} is invalid.

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.

Console


  1. Go to the Roles page in the Cloud Platform 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.

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 CodeStatus Message
PERMISSION_DENIEDYou don't have permission to update the role.
INVALID_ARGUMENTPredefined roles cannot be updated.
INVALID_ARGUMENTThe name in the request ([ROLE_NAME]) and the name in the role ([ROLE_NAME]) must match.
INVALID_ARGUMENTPermission [PERMISSION] is not valid.
ABORTEDThere 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.

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

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 CodeStatus Message
PERMISSION_DENIEDYou don't have permission to update the role
INVALID_ARGUMENTCurated roles cannot be updated.
INVALID_ARGUMENTThe name in the request ([ROLE_NAME]) and the name in the role ([ROLE_NAME]) must match.
INVALID_ARGUMENTPermission [PERMISSION] is not valid.
ABORTEDThere were concurrent policy changes. Please retry the whole read-modify-write with exponential backoff.

Listing the roles

Console


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

    Open the Roles page


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

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 show_deleted field to true.

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

Error codes

Error CodeStatus Message
PERMISSION_DENIEDYou don't have permission to list roles in {path}.
INVALID_ARGUMENTThe parent {path} is invalid. The parent must be in the form organizations/{organization_id}, projects/{project_id} or empty.
INVALID_ARGUMENTRole view is not valid.

Viewing the grantable roles on resources

Console


  1. Go to the [IAM page][] in the Google Cloud Console.
  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.

API


QueryGrantableRoles returns a list of all roles that a resource can reference. It does not include roles that have no permissions. The only required parameter in the request is the full resource name such as //cloudresourcemanager.googleapis.com/projects/my-project. Optionally, the caller can provide a RoleView, which determines if the Role includes all permissions that the role contains in the response.

Example

full_resource_name: '//automatedtests.googleapis.com/projects/my-project/buckets/bucket1'`

Error codes

Error CodeStatus Message
INVALID_ARGUMENT{full_resource_name} must be specified
INVALID_ARGUMENT{full_resource_name}, does not match //[a-z0-9.-]/.

Deleting a custom role

Console


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

    Open the Roles page

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

The role is suspended and cannot be used to create new IAM policy bindings. Existing bindings remain, but are inactive. The role can be undeleted within 7 days. After 7 days, the role is permanently deleted and all bindings associated with the role are removed.

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}

The role will not be included in list, unless show_deleted is set in the request. The role will contain the deleted boolean and it is set to true if the role is in this state.

Existing bindings remain, but are inactive. The role can be undeleted within 7 days. After 7 days, the role is permanently deleted and all bindings associated with the role are removed.

Error codes

Error CodeStatus Message
PERMISSION_DENIEDYou don't have permission to delete the role at {path}.
FAILED_PRECONDITIONYou can't delete role {ROLE_NAME} as it is already deleted.
FAILED_PRECONDITIONYou can't delete a role {ROLE_NAME} that is reserved.
INVALID_ARGUMENTCurated roles cannot be in a deleted state.

Undeleting a custom role

Console


  1. Go to the Roles page in the Cloud Platform 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.

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 CodeStatus Message
PERMISSION_DENIEDYou don't have permission to undelete the role at {path}.
FAILED_PRECONDITIONA role that is not deleted cannot be undeleted.
FAILED_PRECONDITIONYou can't undelete a role {ROLE_NAME} which is reserved.
INVALID_ARGUMENTPredefined roles cannot be undeleted.

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

Cloud Identity and Access Management Documentation