Gmail (OAuth flow)

Enabling Enprivacy to read a user’s Gmail — Google Workspace admin guide

Audience: Google Workspace / Google Cloud administrator
Privileges required: Project owner/editor on a Google Cloud project in your organisation (to create the OAuth client) and the Service Settings administrator privilege in the Admin console (to allow the app)
What this enables: A dedicated, single-tenant Enprivacy instance running for your organisation can read a specific user’s Gmail. Read-only. No sending, deleting, or modifying.

In this deployment you create the OAuth client in your own Google Cloud project and hand the resulting client_id and client_secret to Enprivacy. Because the client lives in your project and is configured as Internal, it is internal to your organisation — which means it does not require Google’s restricted-scope verification or CASA security assessment.

1. What is being granted, and what you exchange with Enprivacy

Enprivacy uses standard Google OAuth 2.0 per-user consent. Nothing is read from any mailbox until that mailbox’s owner signs in and grants access. You are creating and authorising the app; the user grants the actual access; the user can revoke it at any time. Under this configuration, we deliberately do not use domain-wide delegation, which would authorise access to every mailbox in your organisation.

The single scope requested

Scope	Permits	Does not permit
`https://www.googleapis.com/auth/gmail.readonly`	Read messages, threads, labels and settings	Send, delete, or modify mail; access to Drive, Calendar, Contacts, or admin data

This is the narrowest scope that allows reading full message content. (gmail.metadata returns only headers and labels with no message body, which is insufficient.) gmail.readonly grants read of the whole mailbox at the API level; Enprivacy confines its own queries to the Inbox in application logic.

What Enprivacy provides to you (before you start)

Authorised redirect URI for your dedicated instance:
```
https://{{yourorg}}.enprivacy.app/auth/google/callback
```
This must be entered exactly when you create the client (scheme, host, and path), or the user will hit a redirect_uri_mismatch error.

What you return to Enprivacy (at the end)

The client_id and client_secret from the client you create in section 2, transmitted securely (see section 4).

2. Create the OAuth client (Google Cloud Console)

The Cloud Console now groups OAuth setup under Google Auth Platform (Branding / Audience / Data Access / Clients). The steps below follow that current layout.

2a. Select or create a project owned by your organisation

Sign in to the Google Cloud Console with an account in your Workspace organisation.
In the top project selector, either choose an existing project that sits under your organisation (not a personal project) or click New project and ensure the Location/Organisation is set to your organisation. This ownership is what makes the app “internal.”

2b. Enable the Gmail API

Go to APIs & Services → Library.
Search for Gmail API, open it, and click Enable. (Without this, tokens are valid but every Gmail call fails.)

Go to APIs & Services → OAuth consent screen (this opens the Google Auth Platform overview). Click Get started.
App Information: enter an App name (e.g. “Enprivacy Mailbox Access”) and a User support email.
Audience: select Internal.

⚠ This choice is permanent for the project — you cannot switch between Internal and External later without creating a new project. Internal restricts the app to users in your organisation and removes the Google verification requirement for the restricted Gmail scope.
Contact information: enter an email for Google policy notifications.
Finish the wizard.

2d. Declare the Gmail scope

In Google Auth Platform → Data Access, click Add or remove scopes.
Add https://www.googleapis.com/auth/gmail.readonly (you can paste it into the manual scope box). Save.

2e. Create the OAuth client and credentials

Go to Google Auth Platform → Clients (or APIs & Services → Credentials), and click Create client / Create credentials → OAuth client ID.
Application type: select Web application.
Name: e.g. “Enprivacy instance — {{yourorg}}”.
Under Authorised redirect URIs, click Add URI and paste the exact redirect URI Enprivacy gave you (section 1).
Click Create.
A dialog shows the Client ID and Client secret. Copy both now.

The full client secret is shown only at creation — afterwards the console displays just the last four characters. Treat it like a password: never email it in plain text, never commit it to source control, and store it in a secret manager.

3. Allow the internal app to use the Gmail scope (API controls)

Whether this step is required depends on your organisation’s posture:

If the Gmail API is unrestricted in your API controls, the user consent flow in section 5 will work with no further action.
If the Gmail API is restricted (recommended for most organisations), an internal app must be explicitly allowed, or the user will see Access blocked: admin_policy_enforced.

To allow it, in the Admin console (Service Settings administrator privilege):

Go to Menu → Security → Access and data control → API controls.
Either:
- Narrow (recommended): click Manage App Access → Configure new app, search by the Client ID you created, select it, scope it to the OU containing the user who will connect, and set access to Specific Google data / specific scopes, selecting only gmail.readonly. This guarantees the app can never silently gain a broader scope. (On older tenants offering only Trusted/Limited/Blocked, you must use Trusted — “Limited” grants only unrestricted scopes and will not cover gmail.readonly.)
- Broad: in the API controls Settings, enable Trust internal apps. This trusts every app your organisation owns and is simpler but wider than necessary.

4. Hand the credentials to Enprivacy

Transmit the client_id and client_secret from step 2e to Enprivacy over a secure channel — a shared secret manager entry, an encrypted vault link, or another agreed secure method. Do not send the secret by plain email or chat. Enprivacy stores it encrypted within your dedicated instance.

If a secret is ever exposed, you can rotate it in Google Auth Platform → Clients → (your client) → Add secret / reset, then provide the new value to Enprivacy.

In the Enprivacy instance, the user clicks Connect Gmail.
Google shows a consent screen for the read-only Gmail permission.
The user approves. Enprivacy receives a token scoped to that user’s mailbox only.

6. Verify

In Google Auth Platform → Clients, confirm your OAuth client exists with the correct redirect URI.
In Admin console → API controls, if you used section 3, confirm the app shows Type: Internal with access limited to gmail.readonly.
After a user connects, the Accessed apps list shows the user count and the Gmail scope in use.

7. Ongoing controls — monitoring and revocation

Revoke for the organisation: In API controls → Manage App Access, set the app to Blocked; or in Google Auth Platform → Clients, delete the client (this invalidates all its tokens).

Revoke for one user: The user removes it at myaccount.google.com/permissions. You can also revoke a specific user’s OAuth grant from the Admin console.

Audit grants (Enterprise / Education Standard / Education Plus): Security → Security center → Investigation tool, data source OAuth log events, with conditions Event = Authorize/Grant and Scope = gmail.readonly. Create an activity rule / alert to be notified whenever this scope is granted.

8. Security checklist

Questions about this configuration can be directed to Enprivacy support at <>.