Connect Google Workspace

Create a Google Cloud OAuth client, enable the Gmail, Calendar, Drive, Docs and Sheets APIs, and add it to Workforce Intelligence as a connection.

For: Administrators (the admin ability) · Last updated

This page walks through connecting Google Workspace end to end. Workforce Intelligence (WI) uses an OAuth client you create in a Google Cloud project, so people sign in with Google and WI acts with their access. The general connection form, the Allow, Ask and Block defaults and who may use a connection are covered in Connecting outside systems; this page covers what is specific to Google.

You need the admin ability in WI and permission to create or edit a project in Google Cloud.

Create or choose a Google Cloud project#

Open the Google Cloud console and select an existing project or create a new one. The project owns the OAuth client and the list of enabled APIs, so use one your organization controls rather than a personal one.

Enable each API you will use#

Turn on every Google API your Coworkers will call, in the same project. Open the navigation menu, then APIs & Services > Library, find the API, select it and select Enable. Repeat for each:

WI service API to enable
Gmail Gmail API
Google Calendar Google Calendar API
Google Drive Google Drive API
Google Docs Google Docs API
Google Sheets Google Sheets API

This step is easy to miss and it matters. A sign-in and a granted permission do not turn an API on. Until the API is enabled in your project, Google refuses every call to it, even for a person who signed in successfully. Each service needs its own API.

Google shows people a consent screen when they connect. In the Google Cloud console open Google Auth platform (under the navigation menu) and, if it says it is not configured, select Get started. Then:

  1. Under Branding, enter an app name and a support email.
  2. Under Audience, choose the user type:
    • Internal limits sign-in to people in your Google Workspace organization. It is the simplest choice for company use, and Google does not require review of the app.
    • External allows any Google account, which you need for people outside your organization.
  3. Enter a contact email and accept the policy, then create the configuration.
  4. Under Data Access, add the scopes you plan to tick in WI (listed below). Add only the ones you need.

External apps: testing, test users and verification#

A new External app starts in Testing. While it is in Testing:

  • Only people listed under Audience > Test users can connect, up to 100. Add each person by email and save. Anyone else is refused by Google.
  • Google expires the sign-in of an app in Testing after seven days, so people must connect again weekly.
  • People see an "unverified app" warning on the consent screen and must choose to continue.

To lift those limits, publish the app (Audience > Publish app). Gmail and broad Drive permissions are classed by Google as sensitive or restricted, so an External app that uses them can need Google's verification, and sometimes a security assessment, before it can serve more than 100 new people. An Internal app avoids this for people inside your organization. Google's Google Auth platform help covers the current verification rules.

Create the OAuth client#

  1. In Google Auth platform, open Clients and select Create client.
  2. For Application type choose Web application and give it a name (it is shown only in the console).
  3. Under Authorized redirect URIs, select Add URI and paste the redirect URI WI shows on its form (Redirect URI to register), exactly as written.
  4. Select Create, then copy the Client ID and the client secret. If the console does not show a secret on creation, open the client from the list to find it.

Add the connection in WI#

  1. Open Settings, select Review on the Connectors card, then Add a connection, and pick Google.
  2. Enter a Display name, the Client id and the Client secret. The Authorize URL already asks Google for a long-lived sign-in, so connections stay active without signing in again.
  3. Tick the permissions you want in the Permissions checklist, and add the same scopes under Data Access in Google. A new connection starts with these read-only permissions: sign in, see email address, read Gmail, read Drive files and read calendars.
  4. Select Add connection, then Connect on the new card and sign in with your own Google account.
Permission to tick Unlocks
Read Gmail Search and read messages, threads and labels
Draft and send Gmail Saving drafts, sending a draft, sending and replying
Send Gmail Sending a new email or reply only
Read and change Gmail Labels, archiving and moving to trash
Read calendars Listing calendars and events, reading an event
Read and change calendar events Creating, changing and deleting events
See when you are busy Free/busy lookups
Read Drive files Listing and searching files, reading details, exporting Docs and Sheets as text, reading plain-text files
Full Drive access or Files the app opens or creates Creating folders and small text files, moving a file to the trash
Read Google Docs / Read and change Google Docs Reading a document / creating and appending to documents
Read Google Sheets / Read and change Google Sheets Listing tabs and reading ranges / overwriting a range and appending rows

Start with read-only permissions and add compose, send or change permissions only when Coworkers need them. Sending goes out immediately as the person, so most administrators set it to Ask.

Attach the services#

Gmail, Google Calendar, Google Drive, Google Docs and Google Sheets share the one connection, and each has its own Attach tools button and its own functions. Attach the ones you need, tick the functions to turn on and choose Allow, Ask or Block, as described in Connecting outside systems. A function the connection's permissions do not cover stays greyed under Needs more permissions.

People connect their own accounts#

A Supervisor turns the connection on for each Coworker that should use it. Each person then connects their own Google account under Connected accounts (in Settings > My API keys). A Coworker acts with the access of the person it is working for.

Troubleshooting#

What you see What it means and what to do
A Coworker reports that a Google service "isn't turned on", or calls are refused with an access-denied message after a successful sign-in The API is not enabled in your Google Cloud project. Open APIs & Services > Library, enable it, and ask the Coworker to try again. People do not need to connect again.
People see an "unverified app" warning Normal for an External app that is not published or verified. Choose to continue, or switch to Internal or complete verification.
Google says the app has not completed verification or access is blocked for one person In Testing, add that person under Audience > Test users.
Google returns redirect_uri_mismatch The redirect URI in the OAuth client differs from the one WI shows. Copy it again, exactly.
People are signed out every week An External app in Testing expires sign-ins after seven days. Publish the app or use Internal.
A person sees "Needs new access — connect again" under Settings You changed the connection's permissions after they connected. They select Connect again.
A function is greyed with "Needs the … permission" Tick the permission in the connection's checklist (select Go to permissions), add the scope under Data Access in Google, then Refresh functions.