Newer
Older
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
This repository contains a custom synchronisation tool for synchronising
information from the [Lookup service](https://www.lookup.cam.ac.uk/)'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](configuration-example.yaml) for more information.
## Usage
The tool can be invoked from the command line:
```console
$ gsuitesync
```
By default this will log what will be done. To actually perform the
synchronisation:
```console
$ 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:
```console
$ 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``:
```console
$ 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](https://gsuiteupdates.googleblog.com/2020/08/use-service-accounts-google-groups-without-domain-wide-delegation.html)
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**.