Manage roles

The Directory API lets you use role-based access control (RBAC) to manage access to features in your Google Workspace domain. You can create custom roles with privileges to limit admin access more specifically than the pre-built roles provided with Google Workspace. You can assign roles to users or security groups. This guide explains how to perform some basic role-related tasks.

The following is a list of common terms used by the Directory API with regard to RBAC within Google Workspace:

Privilege

The permission necessary to perform a task or operation in a Google Workspace domain. Represented by the Privilege resource. There is no persistent data associated with this resource.

Role

A collection of privileges that grants entities with that role the ability to perform certain tasks or operations. Represented by the Role resource.

Role assignment

The record of a particular role given to the user or group. Represented by the RoleAssignment resource.

Security group

A type of Cloud Identity group that is used to control access to organizational resources. Security groups can contain both individual users and groups.

Role and role assignment limits

You can only create a limited amount of custom roles or role assignments, so if you're getting close to the limit, consolidate or remove them to stay under the limit. Roles and role assignments have the following limits:

• You can create up to 750 custom roles for your entire organization.
• You can create up to 500 role assignments per organizational unit (OU), where the root organization is considered a unit. For example, you can assign 350 roles in the root organization and 400 roles within another OU that you have defined, such as a department of a company. All of the Google Workspace pre-built administrator roles default to the organization-wide scope. Learn more about limits on the privileges that can be assigned at the OU level.

Roles and role assignment have the following limits for groups:

• You can assign any role except Super Admin.
• You can have up to 250 role assignments to groups in total at the overall OU and within each OU.
• The group must be a security group in your organization.
• We recommend restricting group membership to users in your organization. You can add users from outside your organization, but they might not get the role privileges. For details, see Restrict group membership.

Role assignment to groups

If you need to assign more than 500 roles in an OU, you can add multiple members to a security group and assign a role to the group. Group role assignments have some additional limitations—see the Admin help center for specific information.

Note: To create security groups, you must use the Cloud Identity API. You can't use the Directory API. For more information, see the security group documentation.

Google Admin console role-to-privilege mapping

To assign roles for users that access their privileges through the Admin console, certain extra privileges might need to be granted. For example, to grant a user the ability to create other users through the Admin console, not only is the USERS_CREATE privilege required but also the USERS_UPDATE and ORGANIZATION_UNITS_RETRIEVE privileges. The following table maps Admin console functionality to the required privilege grants for managing users and organizational units.

Admin console functionality	Privileges needed
Organizational Units - Read	ORGANIZATION_UNITS_RETRIEVE
Organizational Units - Create	ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_CREATE
Organizational Units - Update	ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_UPDATE
Organizational Units - Delete	ORGANIZATION_UNITS_RETRIEVE + ORGANIZATION_UNITS_DELETE
Organizational Units	ORGANIZATION_UNITS_ALL
Users - Read	USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Create	USERS_CREATE + USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Users - Update	USERS_UPDATE + ORGANIZATION_UNITS_RETRIEVE
Users - Move Users	USERS_MOVE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Rename Users	USERS_ALIAS + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Reset Password	USERS_RESET_PASSWORD + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Force Password Change	USERS_FORCE_PASSWORD_CHANGE + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Add/Remove Aliases	USERS_ADD_NICKNAME + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
Users - Suspend Users	USERS_SUSPEND + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE
GROUPS	GROUPS_ALL
Security - User Security Management	USER_SECURITY_ALL + USERS_RETRIEVE + ORGANIZATION_UNITS_RETRIEVE

Use case examples

Before you begin

Complete the authentication and authorization steps for Google Workspace.

Get a list of domain privileges

To get a paginated list of supported privileges in your domain, use the privileges.list() method.

• If you're an administrator getting privileges in your own domain, use my_customer as the customer ID.

• If you're a reseller getting privileges for one of your customers, use the customer ID returned by the Retrieve a user operation.

Request

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles/ALL/privileges

Response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns the privileges supported in the domain:

{
  "kind": "admin\#directory\#privileges",
  "etag": ...,
  "items": [
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "02afmg282jiquyg",
      "privilegeName": "APP_ADMIN",
      "isOuScopable": false
    },
    {
      "kind": "admin\#directory\#privilege",
      "etag": ...,
      "serviceId": "04f1mdlm0ki64aw",
      "privilegeName": "MANAGE_USER_SETTINGS",
      "isOuScopable": true,
      "childPrivileges": [
        {
          "kind": "admin\#directory\#privilege",
          "etag": ...,
          "serviceId": "04f1mdlm0ki64aw",
          "privilegeName": "MANAGE_APPLICATION_SETTINGS",
          "isOuScopable": true
        }
      ]
    },
    ...
  ]
}

Get existing roles

To get a list of existing roles, use the following GET request and include the authorization described in Authorize requests.

• If you're an administrator getting roles in your own domain, use my_customer as the customer ID.

• If you are reseller getting roles for a customer, use the customer ID that you got using the Retrieve a user operation.

Request

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

Response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns the roles that exist in the domain:

{
  "kind": "admin\#directory\#roles",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/DywA6_jaJCYw-f0lFs2-g17UWe8\"",
  "items": [
    {
      "kind": "admin\#directory\#role",
      "etag": ... ,
      "roleId": "3894208461012993",
      "roleName": "_SEED_ADMIN_ROLE",
      "roleDescription": "Google Workspace Administrator Seed Role",
      "rolePrivileges": [
        {
          "privilegeName": "SUPER_ADMIN",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ROOT_APP_ADMIN",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_APIS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        ...
      ],
      "isSystemRole": true,
      "isSuperAdminRole": true
    },
    {
      "kind": "admin\#directory\#role",
      "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/bTXiZXfuK1NGr_f4paosCWXuHmw\"",
      "roleId": "3894208461012994",
      "roleName": "_GROUPS_ADMIN_ROLE",
      "roleDescription": "Groups Administrator",
      "rolePrivileges": [
        {
          "privilegeName": "CHANGE_USER_GROUP_MEMBERSHIP",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "USERS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "GROUPS_ALL",
          "serviceId": "00haapch16h1ysv"
        },
        {
          "privilegeName": "ADMIN_DASHBOARD",
          "serviceId": "01ci93xb3tmzyin"
        },
        {
          "privilegeName": "ORGANIZATION_UNITS_RETRIEVE",
          "serviceId": "00haapch16h1ysv"
        }
      ],
      "isSystemRole": true
    },
    ...
  ]
}

List all role assignments

To get a paginated list of all direct role assignments, use the roleAssignments.list() method. The API might return empty results with a page token when the userKey parameter is set. You should continue pagination until no page token is returned.

• If you're an administrator getting role assignments in your own domain, use my_customer as the customer ID.

• If you're a reseller getting role assignments for one of your customers, use the customer ID returned by the Retrieve a user operation.

Request

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

Response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns all roles assigned in the domain:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"user",
  "scopeType:"CUSTOMER",
}

List all indirect role assignments

To get a paginated list of all role assignments, including those indirectly assigned to a user because of the groups that they belong to, use the roleAssignments.list() method.

The API might return empty results with a page token. You should continue pagination until no page token is returned.

• If you're an administrator getting role assignments in your own domain, use my_customer as the customer ID.

• If you're a reseller getting role assignments for one of your customers, use the customer ID returned by the Retrieve a user operation.

• Replace USER_KEY with a value that identifies the user in the API request. For more information, see users.get.

Request

GET https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments?userKey=USER_KEY&includeIndirectRoleAssignments=true

Response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns all roles assigned in the domain and whether the assigneeType is user or group:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId:"3894208461013211",
  "assignedTo:"100662996240850794412",
  "assigneeType:"group",
  "scopeType:"CUSTOMER",
}

Create a role

To create a new role, use the following POST request and include the authorization described in Authorize requests. Add a privilegeName and serviceId for each privilege that should be granted with this role. For the request and response properties, see the API Reference.

Request

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roles

{
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

Response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns the properties for the new role:

{
  "kind": "admin\#directory\#role",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/uX9tXw0qyijC9nUKgCs08wo8aEM\"",
  "roleId": "3894208461013031",
  "roleName": "My New Role",
  "rolePrivileges": [
    {
      "privilegeName": "GROUPS_ALL",
      "serviceId": "00haapch16h1ysv"
    },
    {
      "privilegeName": "USERS_ALL",
      "serviceId": "00haapch16h1ysv"
    }
  ]
}

Create a role assignment

To assign a role, use the following POST method and include the authorization described in Authorize requests.

• To assign the role to a user, add a JSON body with the user_id of the user, which you can get from users.get(), the roleId (as described in Get existing roles), and the scope_type.

• To assign the role to a service account, add a JSON body with the unique_id of the service account (as defined in Identity and Access Management (IAM)), the roleId (as described in Get existing roles), and the scope_type.

• To assign the role to a group, add a JSON body with the group_id of the group, which you can get from groups.get(), the roleId (as described in Get existing roles), and the scope_type.

Request

POST https://admin.googleapis.com/admin/directory/v1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns the properties for the new role assignment:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER"
}

Create a role assignment with conditions

Note: This feature is only available in the v1.1beta1 version of the API, and only to Enterprise Standard, Enterprise Plus, Google Workspace for Education Plus and Cloud Identity Premium customers. No additional setup is needed to use the feature. Role assignment with conditions isn't respected in the Admin console yet.

You can grant roles to perform actions that meet specific conditions. Currently, only two conditions are supported:

• Only applicable to security groups
• Not applicable to security groups

When condition is set, it will only take effect when the resource being accessed meets the condition. If condition is empty, the role (roleId) is applied to the actor (assignedTo) at the scope (scopeType) unconditionally.

To assign a role to a user, use the following POST method and include the authorization described in Authorize requests.

Add a JSON body with the user_id of the user, which you can get from users.get(), the roleId as described in Get existing roles, and the condition. The two condition strings have to be used verbatim as shown below and they only work with the Groups Editor and Groups Reader pre-built administrator roles. These conditions follow Cloud IAM condition syntax.

Request

Only applicable to security groups

POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

Not applicable to security groups

POST https://admin.googleapis.com/admin/directory/v1.1beta1/customer/customer_id/roleassignments

{
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}

Response

A successful response returns an HTTP 200 status code. Along with the status code, the response returns the properties for the new role assignment:

{
  "kind": "admin\#directory\#roleAssignment",
  "etag": "\"sxH3n22L0-77khHtQ7tiK6I21Yo/VdrrUEz7GyXqlr9I9JL0wGZn8yE\"",
  "roleAssignmentId": "3894208461013211",
  "roleId": "3894208461012995",
  "assignedTo": "100662996240850794412",
  "scopeType": "CUSTOMER",
  "condition": "!api.getAttribute('cloudidentity.googleapis.com/groups.labels',
    []).hasAny(['groups.security']) && resource.type ==
    'cloudidentity.googleapis.com/Group'"
}