Gmail OAuth

This section walks through setting up the Gmail connector using a OAuth-enabled Google App. Anyone can do this (even without a paid Google Workspace)!

If you're an organization with a Google Workspace, and you'd rather use a Service Account to access Gmail, checkout the section here.

Authorization#

Create Google Cloud Project#

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

Enable Gmail API#

• 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

Set up OAuth consent screen#

• Under APIs & services, select the OAuth consent screen tab

• If you don't have a Google Organization select External for User Type

• Call the app Nexus (or whatever you want)

• For the required emails, use any email of your choice or founders@onyx.app if you wish for the Nexus team to help handle issues.

• Click SAVE AND CONTINUE

Set up scopes#

• Add the scope .../auth/gmail.readonly for Gmail API

To enable permission syncing for this connector:

* Enable the **Admin SDK API** (visit this link: [https://console.cloud.google.com/flows/enableapi?apiid=admin.googleapis.com](https://console.cloud.google.com/flows/enableapi?apiid=admin.googleapis.com)) and enable it for your project.
* Add the scope `.../auth/admins.directory.user.readonly` for `Admin SDK API`.
* Add the scope `.../auth/admins.directory.group.readonly` for `Admin SDK API`.
* The account performing the OAuth flow must have an Admin role in the Google Workspace that
  has access to the "Groups > Read" privilege.
  This can be set in the Google Admin Console under Account > Admin roles.

Set up test users#

• This is only applicable for users without a Google Organization.

• Add at least one test user email. Only the email accounts added here will be allowed to run the OAuth flow to index new emails.

• Click SAVE AND CONTINUE, review the changes and click BACK TO DASHBOARD

Create OAuth credentials#

• Go to the Credentials tab and select + CREATE CREDENTIALS -> OAuth client ID

• Choose Web application and give it some name like NexusConnector

• Add an Authorized JavaScript origins

• http://localhost:3000 if self-hosting

• https://<INTERNAL_DEPLOYMENT_URL> if you have setup Nexus for production use

• https://school.narb.cc when configuring the school workspace

• Add an Authorized redirect URIs

• http://localhost:3000/admin/connectors/gmail/auth/callback if self-hosting

• https://<INTERNAL_DEPLOYMENT_URL>/admin/connectors/gmail/auth/callback if you have setup Nexus for production use

• https://school.narb.cc/admin/connectors/gmail/auth/callback when configuring the school workspace

• Click create and on the right hand side next to Client secret, there is an option to download the credentials as a JSON. Download the JSON for use in the next step.

Indexing#

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

Then, click Create New. Under Option 1: OAuth app, upload (or paste) the OAuth app JSON you downloaded above, then click Authenticate with Gmail, then continue with the account you want to use to index Gmail.

Once complete, select the newly created credential, and click the Continue button to configure the connector!

The app JSON is stored on the credential it creates, so each OAuth credential carries its own app. To add more connectors for the same account, select the existing credential from the list instead of creating a new one. An instance can hold multiple Gmail credentials.

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.