Google GSuite Synchronisation Tool

This repository contains a custom synchronisation tool for synchronising information from the Lookup service's LDAP personality to a Google hosted domain (aka "GSuite").

Configuration is performed via a configuration file. Take a look at the example configuration file for more information.

Usage

The tool can be invoked from the command line:

$ gsuitesync

By default this will log what will be done. To actually perform the synchronisation:

$ gsuitesync --really-do-this

See the output of gsuitesync --help for more information on valid command-line flags.

Unless overridden on the command line, the tool searches for its configuration file in the following places in the following order:

• A gsuitesync.yaml file in the current directory.
• ~/.gsuitesync/configuration.yaml.
• /etc/gsuitesync/configuration.yaml.

The first located file is used.

Installation

The command-line tool can be installed directly from the git repository:

$ pip3 install git+https://gitlab.developers.cam.ac.uk/uis/gsuite/synctool.git

For developers, the script can be installed from a cloned repo using pip:

$ cd /path/to/this/repo
$ pip3 install -e .

New users

When new users are created they are created with a random password which is immediately thrown away. They are created with a primary email of the form [uid]@[domain] where [uid] is the unique id from lookup (i.e. the CRSid) and [domain] is the name of the Google domain from the configuration.

Required API scopes

This tool requires the following OAuth2 scopes to audition the changes to be made:

• https://www.googleapis.com/auth/admin.directory.user.readonly
• https://www.googleapis.com/auth/admin.directory.group.readonly
• https://www.googleapis.com/auth/admin.directory.group.member.readonly
• https://www.googleapis.com/auth/apps.groups.settings

This tool requires the following OAuth2 scopes to actually perform changes:

• https://www.googleapis.com/auth/admin.directory.user
• https://www.googleapis.com/auth/admin.directory.group
• https://www.googleapis.com/auth/admin.directory.group.member

See the section on preparing a service account for information on how to grant a service account those scopes on your domain.

Preparing a service account (Admin Roles)

Google have updated the API to allow service accounts direct access to the API without needing domain-wide delegation.

1. Create a service account in the Google Console for this script.
2. Generate and download JSON credentials for the service account.
3. In the GSuite admin panel, go to "Account" > "Admin Roles" and create a new custom role with the following Admin API privileges (not Console privileges):
   • Users - Create, Read, Update and Update Custom Attributes
   • Groups - All privileges
4. Add the service account to the role using the "Assign service accounts" option when viewing the custom role's admins

Preparing a service account (Domain-wide Delegation)

This tool assumes it will be acting as a service account user. It will use this service account user to then act on behalf of an admin user in GSuite. To prepare such a service account user:

1. Create a service account in the Google Console for this script.
2. Generate and download JSON credentials for the service account.
3. Under "IAM" > "Service Accounts", select the service account, click "Edit", click "Show domain-wide delegation" and "Enable G Suite Domain-wide Delegation". Click "Save" to apply the changes.
4. Hover over the "?" symbol next to the generated client id and click "view client". Copy the Client ID from the popup panel.
5. In the GSuite admin panel, go to "Security Settings" > "API Controls" > "Manage Domain-Wide Delegation", and click "Add new".
6. Paste in the service account Client ID as "Client Name" and add a comma-separated list of scopes. See the section on required API scopes.

The scary-sounding "Enable G Suite Domain-wide Delegation" means that this service account is marked as being willing to "su" to another Google user. By adding the generated Client ID to the GSuite security settings you are, as domain administrator, giving that service account the ability to act as any user in the domain subject to the listed scopes.