Administrator actions

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:

1. Create security groups to organize users who can access these features.
2. Add members to the groups.
3. Create a custom administrator role by selecting the correct privilege.
4. Retrieve organizational unit IDs.
5. Apply the custom administrator role to the newly created groups.

Prerequisites

1. 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.
2. 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.
3. 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.

{
  roleName: "Education Admin", // customize as needed
  roleDescription: "Access to view analytics data", // customize as needed
  rolePrivileges: [
     {
        privilegeName: "EDU_ANALYTICS_DATA_ACCESS",
        serviceId: "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.

{
  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
}

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

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