Gmail Service Account

This section walks through setting up the Gmail connector using a Service Account. More info on Service Accounts can be found here. A Google Workspace is required.

If you'd rather use an individuals account + OAuth to access Gmail, checkout the section here.

Authorization#

Create Google Cloud Project#

• https://console.cloud.google.com/projectcreate

Enable Gmail API and Admin SDK#

• On the left panel, open APIs & services

• Go to Enabled APIs and services

• On the top click +ENABLE APIS AND SERVICES

• Search for Gmail API and click ENABLE

• Alternatively visit this link, select your project and enable the Gmail API

• Also enable Admin SDK API (search and enable)

Create Service Account#

• Go to the Service Account management page in Google Cloud.

• Click Create Service Account button and fill out the fields in step 1. You can ignore steps 2 and 3.

• Go to the Keys section, and click Add Key. Download this key. You will provide it when creating the credential in Nexus later.

Note for Google Organizations created after April 2024:

• To give the service account the proper permissions you will have to navigate to this link

• Then select Manage, select Override parent's policy and then select Not enforced under Rules.

• Finally, select SET POLICY

Grant domain-wide delegation#

Give this Service Account read-only access to Gmail

• Copy the Unique ID of the Service Account

• Go to the Domain-wide Delegation page in the Google Admin Console.

• Click Add new, fill in the client ID with the Unique ID of the Service account

• Copy this comma separated list of scopes and paste it into field OAuth scopes: https://www.googleapis.com/auth/gmail.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly,https://www.googleapis.com/auth/admin.directory.user.readonly

Indexing#

First, navigate to the Admin Panel and select the Gmail connector.

Then, create a new credential. In the Authenticate with Nexus step, upload the service account key you downloaded when creating the service account. Each credential holds its own service account key, so the key is provided here rather than as a single instance-wide upload. For the Primary Admin Email, use the email of a user that has an Admin role in the Google Workspace with access to the Users > Read and **Groups

Read** privileges. This can either be an existing admin, or a brand new account created specifically for Nexus (e.g. onyx-robot@your-domain.com). Note that this should NOT be the service account email. This can be configured by an admin in the admin panel of the Google Workspace under Account > Admin roles.

Click Create Credential, and then close the dialog. From there, click the Continue button and configure the connector!

You can create more than one Gmail credential on a single Nexus instance, each with its own service account. This lets you index multiple Google Workspaces from one Nexus deployment. Create a separate credential and connector for each workspace you want to index.

Before using this source with students#

Start with approved course material. Check which documents the connector can retrieve and how it maps source permissions. Test with a student account and a teacher account before widening access. A successful sync does not prove that the intended class boundary is correct.

Use source troubleshooting when a document is missing or visible to the wrong audience.