The Directory API lets you use role-based access control to manage user access to features in your domain. You do this by managing privileges and roles and their assignment to users.
Overview
A privilege is necessary to perform certain tasks and operations in a domain. A role is a collection of privileges (of possibly different services like the Users service, Chrome, and so on) that grants users with that role the ability to perform certain tasks or operations. A role assignment is a record of a particular role given to a user.
The methods in this guide can be used to create roles and manage role assignments for users in a domain. The general process involves using the following three resources:
- The privileges resource is used to get a list of supported privileges in the domain.
- The roles resource is used to create new roles or get existing roles.
- The roleAssignments resource is used to assign a role to a user in the domain.
Role and role assignment limits
Roles and role assignments have hard limits, described below. Trying to add more than the limit returns an error, so if you are getting close, consolidate or remove them to stay under it.
- Custom roles: You can create up to 750 custom roles for your entire organization.
- Role assignments: 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 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.
Get supported privileges
To get a list of supported privileges, use the following GET request and include the authorization described in Authorize requests.
If you are an administrator getting privileges in your own domain, use
my_customer
as the customer ID.If you are 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 are 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
},
...
]
}
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(), theroleId
as described in Get existing roles, and thescope_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)), theroleId
as described in Get existing roles, and thescope_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
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'"
}
Assign Admin Console UI roles
To assign roles for users that will access their privileges through the Admin
Console UI, certain extra privileges may need to be granted. For example, to
grant a user the ability to create other users through the Admin Console UI, not
only is the USERS_CREATE
privilege required but also the USERS_UPDATE
and
ORGANIZATION_UNITS_RETRIEVE
privileges. The following table maps Admin
Console UI functionality to the required privilege grants for managing users
and organizational units.
Admin Console UI 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 |