Domain administrators have several controls to manage features and applications users in their domain can access. This page describes these features, how they might affect or be useful to an external integration, and relevant API requests.
Manage access to third-party apps for users under 18
Administrators must configure third-party applications in the Google Admin console for users under 18. If an administrator has not configured an application, users under 18 will be unable to access that application with their Google Workspace for Education account.
There is no action required from developers building applications for Google Workspace for Education users under 18. Configuring third-party apps can only be accomplished by administrators in the Admin console UI and can't be accomplished programmatically.
Designate custom administrator roles for Classroom features
Administrators can create custom administrator roles in the Admin console to allow certain individuals or groups with an Education Plus license to:
View Classroom analytics to understand data such as assignment completion, grade trends, and Classroom adoption.
Temporarily access classes in Classroom without assigning a permanent co-teacher.
This guide explains how to set up these features in your domain using Google APIs.
Automate the custom role assignment process
This guide will inform you how to complete the following steps to automate the custom role assignment process:
- Create security groups to organize users who can access these features.
- Add members to the groups.
- Create a custom administrator role by selecting the correct privilege.
- Retrieve organizational unit IDs.
- Apply the custom administrator role to the newly created groups.
Prerequisites
- Read the Quickstart guides to understand how to set up and run an application using Google APIs in languages such as JavaScript, Python, and Java.
- Before you use any of the Cloud Identity APIs described in this guide, you must set up Cloud Identity. These APIs are used to create groups to assign administrator privileges.
- Read the Groups API Overview and set up the Groups API if you would like to provide custom role access to a group of users instead of an individual user.
Create security groups
Create a security group with the groups.create
method. A group can be set as
a security group when the security label is included in the labels
field of
the request. For more information and limitations on creating security groups,
refer to the creating security groups guide.
POST https://cloudidentity.googleapis.com/v1/groups
Optionally, you can include the InitialGroupConfig
query parameter to
initialize the group owner:
POST https://cloudidentity.googleapis.com/v1/groups&initialGroupConfig={initialGroupConfig}
The account making this request requires one of the following scopes:
https://www.googleapis.com/auth/cloud-identity.groups
https://www.googleapis.com/auth/cloud-identity
https://www.googleapis.com/auth/cloud-platform
Request body
The request body contains details of the group to be created. The customerId
must begin with "C" (for example, C046psxkn
). Find your customer ID.
{
parent: "customers/<customer-id>",
description: "This is the leadership group of school A.",
displayName: "Leadership School A",
groupKey: {
id: "leadership_school_a@example.com"
},
labels: {
"cloudidentity.googleapis.com/groups.security": "",
"cloudidentity.googleapis.com/groups.discussion_forum": ""
}
}
Response
The response contains a new instance of the Operation
resource.
{
done: true,
response: {
@type: "type.googleapis.com/google.apps.cloudidentity.groups.v1.Group",
name: "groups/<group-id>", // unique group ID
groupKey: {
id: "leadership_school_a@example.com" // group email address
},
parent: "customers/<customer-id>",
displayName: "Leadership School A",
description: "This is the leadership group of school A.",
createTime: "<created time>",
updateTime: "<updated time>",
labels: {
"cloudidentity.googleapis.com/groups.security": "",
"cloudidentity.googleapis.com/groups.discussion_forum": ""
}
}
}
Add group members
Once you've created the group, the next step is to add members. A group member
can be a user or another security group. If you add a group as a member of
another group, there might be a delay of up to 10 minutes for membership to
propagate. In addition, the API returns an error for cycles in group
memberships. For example, if group1
is a member of group2
, group2
cannot
be a member of group1
.
To add a member to a group, use the following POST request to the
Directory API members.insert
method:
POST https://admin.googleapis.com/admin/directory/v1/groups/{groupKey}/members
The groupKey
path parameter is the new member's group email address or the
group's unique ID.
The account making the POST request requires one of the following scopes:
https://apps-apis.google.com/a/feeds/groups/
https://www.googleapis.com/auth/admin.directory.group
https://www.googleapis.com/auth/admin.directory.group.member
Request body
The request body contains details of the member
to be created.
{
email: "person_one@example.com",
role: "MEMBER", // can be `MEMBER`, `OWNER`, `MANAGER`
}
Response
The response contains the new instance of the member.
{
kind: "admin#directory#member",
etag: "<etag-value>", // role's unique ETag
id: "4567", // group member's unique ID
email: "person_one@example.com",
role: "MEMBER",
type: "GROUP",
status: "ACTIVE"
}
This request needs to be made for every user you would like to add as a member. You can batch these requests to reduce the number of HTTP connections your client has to make.
Create a privileged custom administrator role
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 administrator access more specifically than the prebuilt roles provided with Google Workspace. You can assign roles to users or security groups. For more detailed information on the limitations of role creation, refer to the custom role and role assignment limitations.
To create a new role, use the following POST request to the
Directory API roles.insert
method:
POST https://admin.googleapis.com/admin/directory/v1/customer/{customer}/roles
The customerId
is the same as the one used in step
1 of this guide.
The account making the POST request requires the following scope:
https://www.googleapis.com/auth/admin.directory.rolemanagement
Request body
The request body contains details of the role
to be created. Add a
privilegeName
and serviceId
for each privilege that should be granted with
this role.
Classroom analytics
The EDU_ANALYTICS_DATA_ACCESS
privilege is required in order to create a
custom role that can access analytics data, along with the serviceId
set
to 019c6y1840fzfkt
.
{
roleName: "Education Admin", // customize as needed
roleDescription: "Access to view analytics data", // customize as needed
rolePrivileges: [
{
privilegeName: "EDU_ANALYTICS_DATA_ACCESS",
serviceId: "019c6y1840fzfkt"
}
]
}
Temporary class access
The ADMIN_OVERSIGHT_MANAGE_CLASSES
privilege is required in order to
create a custom role that can temporarily access classes, along with the
serviceId
set to 019c6y1840fzfkt
.
{
roleName: "Education Admin", // customize as needed
roleDescription: "Access to manage classes privilege", // customize as needed
rolePrivileges: [
{
privilegeName: "ADMIN_OVERSIGHT_MANAGE_CLASSES",
serviceId: "019c6y1840fzfkt"
}
]
}
Call the privileges.list
method to retrieve a list of privilegeIds
and
serviceIds
.
Response
The response contains the new instance of the role.
Classroom analytics
{
kind: "admin#directory#role",
etag: "<etag-value>", // role's unique ETag
roleId: "<role-id>", // role's unique ID
roleName: "Education Admin",
roleDescription: "Access to view analytics data",
rolePrivileges: [
{
privilegeName: "EDU_ANALYTICS_DATA_ACCESS",
serviceId: "019c6y1840fzfkt"
}
],
isSystemRole: false,
isSuperAdminRole: false
}
Temporary class access
{
kind: "admin#directory#role",
etag: "<etag-value>", // role's unique ETag
roleId: "<role-id>", // role's unique ID
roleName: "Education Admin",
roleDescription: "Access to manage classes privilege",
rolePrivileges: [
{
privilegeName: "ADMIN_OVERSIGHT_MANAGE_CLASSES",
serviceId: "019c6y1840fzfkt"
}
],
isSystemRole: false,
isSuperAdminRole: false
}
Retrieve organizational unit IDs
You can limit the access of the custom administrator role to one or more
organizational units using the organizational unit ID. Use the OrgUnit API to
retrieve the orgUnitId
.
Classroom analytics
It's recommended that you select a student organizational unit and teacher organizational unit when assigning the custom administrator role to a specific user or group. Doing so allows users designated with the custom administrator privilege access to student and class-level data for the organizational units. If the student organizational unit is omitted, designated users won't have access to student data. If the teacher organizational unit is omitted, designated users won't have access to class-level data.
Temporary class access
You can limit temporary class access privileges by allowing users with the custom administrator role access to classes in specific organizational units. If restricting access to an organizational unit, the group assigned the custom administrator role can only access classes where the primary teacher of the class is in that organizational unit.
Assign the custom administrator role
To assign the custom administrator role to a group, use the following POST request. Refer to the custom role and role assignment limitations guidance for role assignment limits.
Directory API roleAssignments.insert
:
POST https://admin.googleapis.com/admin/directory/v1/customer/{customer}/roleassignments
Assign to a group or individual user
If assigning the privilege to a group, include the groupId
in the assignedTo
field in the request body. The groupId
was obtained in the Create security
groups step. If assigning the privilege to an
individual user, include the user's ID in the assignedTo
field in the request
body. The user's ID can be retrieved by calling users.get
and specifying the
user's email address as the userKey
parameter or by calling users.list
.
The account making the POST request requires the following scope:
https://www.googleapis.com/auth/admin.directory.rolemanagement
Request body
The request body contains details of the RoleAssignment
to be created. You
must make one request per organizational unit that you would like to associate
with this group.
{
roleId: "<role-id>", // role's unique ID obtained from Step 3
assignedTo: "<id>", // group ID or user ID
scopeType: "ORG_UNIT", // can be `ORG_UNIT` or `CUSTOMER`
orgUnitId: "<org-unit-id>" // organizational unit ID referenced in Step 4
}
Response
The response contains the new instance of the RoleAssignment
.
{
kind: "admin#directory#roleAssignment",
etag: "<etag-value>",
roleAssignmentId: "<role-assignment-id>",
roleId: "<role-id>",
assignedTo: "<group-id or user-id>",
assigneeType: "GROUP",
scopeType: "ORG_UNIT",
orgUnitId: "<org-unit-id>"
}
Resources
Additional information can be found at:
- Directory API Overview
- Directory API-specific authentication & authorization
- Directory API REST documentation
- Admin SDK API Developer Support