FAQ | This is a LIVE service | Changelog

Skip to content
Snippets Groups Projects
Rich Wareham's avatar
Dr Rich Wareham authored
commit 6366bf5b783828249f7b6ffb9c026bdc2e08aaf2
Merge: 25f3c97 fb0fa5b
Author: Dr Rich Wareham <rjw57@cam.ac.uk>
Date:   Thu Sep 26 12:23:44 2019 +0000

    Merge branch 'issue-8-set-orgunitpath' into 'master'

    Set organization unit path when creating new users

    Closes #8

    See merge request uis/devops/gsuite/synctool!6

commit fb0fa5bc082bae71141732b2d3e8c8f6bdd56d46
Author: Robin Goodall <rjg21@cam.ac.uk>
Date:   Wed Sep 25 09:38:03 2019 +0100

    set orgUnitPath when creating new users (default to '/')

commit 25f3c97f3592ba76a74862e2c7b850b9ee947f0a
Merge: 4ff0035 777d796
Author: Dr Rich Wareham <rjw57@cam.ac.uk>
Date:   Wed Sep 11 11:22:17 2019 +0000

    Merge branch 'issue-6-retry-on-503' into 'master'

    Retry API requests when a HTTP 503 "Service unavaliable" is received

    Closes #6

    See merge request uis/devops/gsuite/synctool!5

commit 777d796e5c0188ae49d0f3e6d4c7371fc324973a
Author: Robin Goodall <rjg21@cam.ac.uk>
Date:   Tue Sep 10 15:23:07 2019 +0100

    missing orgUnitPath sanity check

commit 8a1b02aa9e69068f5f3abbec7d294e36a2879b08
Author: Robin Goodall <rjg21@cam.ac.uk>
Date:   Tue Sep 10 15:06:41 2019 +0100

    Retry on 503 responses

commit 4ff0035fb49754041d5bc8b38374adfdfadfbf86
Merge: 0d289d9 c2be733
Author: Robin Goodall <rjg21@cam.ac.uk>
Date:   Tue May 14 08:28:25 2019 +0000

    Merge branch 'issue-5-naming' into 'master'

    naming: prefer displayName over cn/sn

    Closes #5

    See merge request uis/devops/gsuite/synctool!4

commit c2be7330b68be5722d4d63c7c9210754a3cb6340
Author: Rich Wareham <rjw57@cam.ac.uk>
Date:   Wed May 8 15:35:24 2019 +0100

    naming: prefer displayName over cn/sn

    Now we have on-boarded users, move away from being compatible with the
    authenticator to using displayName in preference to cn/sn.

    Closes #5

commit 0d289d938f13c9c77708db586bf859237068afa3
Merge: efca9e7 dea989d
Author: Stephen Lovell <sml47@cam.ac.uk>
Date:   Wed May 8 13:05:10 2019 +0000

    Merge branch 'issue-2-configure-batch' into 'master'

    allow configuration of API batch size and inter-batch delay

    Closes #2

    See merge request uis/devops/gsuite/synctool!2

commit dea989d105341904c1eef8657ed0be9dcfa91a51
Author: Rich Wareham <rjw57@cam.ac.uk>
Date:   Wed May 8 11:55:33 2019 +0100

    configuration-example.yml: add documentation on batch size [CR]

    Clarify in documentation that there is a maximum API batch size of 1000.

commit efca9e7987d933dae8bb577adbc8402e846e1468
Merge: 6d1c7a8 961514f
Author: Stephen Lovell <sml47@cam.ac.uk>
Date:   Tue May 7 14:32:19 2019 +0000

    Merge branch 'issue-4-remove-progress' into 'master'

    remove useless progress indicator

    Closes #4

    See merge request uis/devops/gsuite/synctool!3

commit 961514f00e2265596a1f5a242e22550d4cf8f4d4
Author: Rich Wareham <rjw57@cam.ac.uk>
Date:   Tue May 7 12:11:53 2019 +0100

    remove useless progress indicator

    Closes #4

commit 07ec5eebe1c29d614160c6f2bf0e76c0d0689468
Author: Rich Wareham <rjw57@cam.ac.uk>
Date:   Thu May 2 15:52:49 2019 +0100

    allow configuration of API batch size and inter-batch delay

    Add configuration parameters to tweak how we call the Google API. Allow
    customisation of API batch size and the delay between calls to the API.
    This allows us to work around some Google API rate limits.

    Closes #2

commit 6d1c7a818e2fdc005714ea00e6d8ad1ad7c03cd4
Merge: 6f96eca a0b901a
Author: Robin Goodall <rjg21@cam.ac.uk>
Date:   Tue Apr 30 15:36:16 2019 +0000

    Merge branch 'initial-implementation' into 'master'

    initial implementation

    Closes #1

    See merge request uis/devops/gsuite/synctool!1

commit a0b901a4cf038cc7a30fa5e18c6d1d7843d49a2c
Author: Rich Wareham <rjw57@cam.ac.uk>
Date:   Fri Apr 26 17:05:25 2019 +0100

    initial implementation

    Provide an initial implementation f the tool and README documenting how
    to install, configure and run it.

    Closes #1

commit 6f96eca5086635cab3b924ec16b5355028acc4b9
Author: Rich Wareham <rjw57@cam.ac.uk>
Date:   Fri Apr 26 13:46:46 2019 +0100

    initial stub README
8ea24b2d
History

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

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

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

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

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" > "Advanced Settings" > "Manage API client access".
  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.