Skip to main content

Netskope Help

Configure Gmail for API Data Protection

Note

API Data Protection supports all editions of Google workspace i.e., basic, business, and enterprise. However, with basic edition, shared drives and Google Drive audit activities are not supported.

Starting release 50, API Data Protection supports Gmail, Google's email service. The Gmail API allows authorized access to a user's mailbox to perform the following actions:

  • Read and send messages

  • Manage labels applied to messages and threads

  • Search specific messages and threads

  • Modify mailbox settings for email forwarding, filters, vacation auto-response, and more

The following capabilities are supported:

  • Identify users belonging to the customer domain and sub-domain, if any

  • Monitor email activity of users in customer organization

  • Scan sent and trash folders for sensitive content in the subject or body 

  • Scan email attachments for sensitive content

  • Alert administrator in case of suspicious activity based on triggered policies

Note

API Data Protection policy for Gmail supports the (ongoing) Alert policy action only. In other words, if there is a violation, API Data Protection will generate an alert and if configured, notify the user about a policy violation.

An authenticated user must authorize all requests to the Gmail API. Gmail uses the OAuth 2.0 protocol for authenticating a Google account and authorizing access to user data.

There are two parts to this procedure:

  • Install Netskope for Google Apps from Google Marketplace

  • Configure Gmail instance in Netskope UI

Install Netskope for Google Apps from Google Marketplace

The administrator should install the Netskope app for API Data Protection with domain-wide delegation to allow access to all users in the organization. The following scopes are required for Gmail access. The scopes are included as part of the the Netskope app.

Scope URL

Usage

https://www.googleapis.com/auth/admin.directory.domain.readonly

List all sub-domains in the organization

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

List users in each sub-domain

https://www.googleapis.com/auth/gmail.readonly

Read all resources and their metadata (no write operations)

To install the Netskope for Google Apps from Google Marketplace:

  1. Access this URL: https://workspace.google.com/marketplace/app/netskope/1055677045599.

  2. Click Install.

  3. Log in using the admin username and password.

  4. Click Install.

  5. In the Domain wide install pop-up window, click CONTINUE.

  6. The following pop-up window is displayed. For the Turn ON for drop-down menu, ensure that you select the primary domain. This ensures that the app is installed for the entire organization. Select the Terms of Service check box. Click Accept.

    Google_Netskope_App_ToS.png

On successful installation of the app, the Netskope has been installed! message is displayed. The Netskope app installation is now complete.

Once the app is installed, ensure the following items:

  • The Netskope app is turned on for the entire organization. Log in to admin.google.com. In the home page, navigate to Apps > Google Workspace Marketplace apps. Look for the Netskope app and ensure that the Distribution is set to On for everyone.

  • The appropriate scopes are granted. You can check the scopes by logging into admin.google.com and on the home page, navigate to Apps > Google Workspace Marketplace apps. Look for the Netskope app and click it. The scopes are as follows:

    Scope Name

    Scope URL

    Usage

    Netskope Use Case

    View customer related information

    https://www.googleapis.com/auth/admin.directory.customer.readonly

    View details (e.g., contact email, organization title etc) of customer

    Not in use. To be deprecated.

    View and manage the provisioning of domains for your customers

    https://www.googleapis.com/auth/admin.directory.domain

    Provision and delete domain aliases for your customers Provision and delete multi-domains (secondary domains) for your customers

    Read all managed domains used in user listing, calculating exposure of the shared file.

    View groups on your domain

    https://www.googleapis.com/auth/admin.directory.group.readonly

    View details (e.g., name, members) and metadata (e.g., login details) of groups on your domain

    If Team Drive has a group, then get active internal member of the group for doing all the API calls.

    View organization units on your domain

    https://www.googleapis.com/auth/admin.directory.orgunit.readonly

    View metadata (e.g., name and description) of organization units

    Not in use. To be deprecated.

    View and manage the provisioning of users on your domain

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

    Provision and delete users on your domain View and modify details (e.g., name, address, and phone number) and metadata (e.g., login details) of users on your domain

    List all users, get details of a user.

    Manage data access permissions for users on your domain

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

    View and manage data access permissions for users on your domain

    Get details of third party apps and plugins installed by users (google app ecosystem).

    View audit reports for your G Suite domain

    https://www.googleapis.com/auth/admin.reports.audit.readonly

    View audit reports of admin and user activity in your G Suite domain (e.g., password change events and document view events)

    Poll audit events of Google Drive, administrator, login, mobile, and calendar. Webhooks subscription for Google Drive events of enterprise Google Suite accounts.

    See, edit, create, and delete all your Google Drive files

    https://www.googleapis.com/auth/drive

    This app wants permission to access everything in your Google Drive. It will be able to do the same things you can do, including see your files , upload and download your files, delete your files, see the names and emails of people you share files with, share and stop sharing your files with others, remove people from your files, organize your drive.

    Get Google Drive events like Team Drive details, file metadata, download, file sharing details etc.

    View and modify but not delete your email

    https://www.googleapis.com/auth/gmail.modify

    View and modify your mail in Gmail. May move mail to Spam/Trash but not instantly delete forever Create, update, and delete labels Compose and send new email View your settings (e.g., filters and labels)

    Not in use. To be deprecated.

    View your email messages and settings

    https://www.googleapis.com/auth/gmail.readonly

    View your email messages Search your email messages View your settings (e.g., filters and labels)

    Read email metadata, email details etc.

    View your email address

    https://www.googleapis.com/auth/userinfo.email

    View the email address associated with your account

    Grant the instance for Gmail, Google Drive.

    See your personal info, including any personal info you've made publicly available

    https://www.googleapis.com/auth/userinfo.profile

    This app wants permission to see your full name, see your profile picture, see your gender, see your preferred languages, and see any other information you have made publicly available.

    Grant the instance for Gmail, Google Drive.

Create a Custom Admin Role for Netskope

If you do not plan to use the Google super admin account, you can create a custom admin role and assign the role to a user to grant access to API Data Protection.

You can grant privileges/scopes for the Netskope app either using the default Google super admin role or by creating a custom admin role exclusively for the Netskope app. This section describes the steps to create a custom admin role for Netskope.

  1. Log in to admin.google.com.

  2. Click the triple bar on the top-left corner of the home page and navigate to Account > Admin roles.

  3. Click Create new role.

  4. Enter a name and description for the role and click CONTINUE.

  5. Select privileges for the role:

    Important

    Netskope does not recommend to remove the following privileges. Any removal may result in failure of API calls and policy processing.

    The admin console privileges are automatically assigned when a new role is created in Google Workspace. The level of access provided to this role in the admin console depends on what permissions are provided for this role. Here is a list of privileges Netskope requires:

    Table 10. Google Admin Console Privileges

    Privileges

    Needed for

    Organizational Units > Read

    This privilege is required to read the organization units (OU) in the Gmail account.

    Users > Read

    This privilege is required to list the users in the Gmail account.

    Domain Settings

    This privilege is required to read domains.



  6. Click CONTINUE, and then click CREATE ROLE.

Once you have created the custom role, you can assign the role to a user. The user can then authorize Netskope to grant access to your Gmail instance. 

Configure Gmail Instance in Netskope UI

To authorize Netskope to access your Gmail instance:

  1. Log in to the Netskope tenant UI: https://<tenant hostname>.goskope.com and go to Settings > API-enabled Protection > SaaS.

  2. Select the Gmail icon, and then click Setup Instance.

    The Setup Instance window opens.

  3. In the INSTANCE NAME, enter the domain name for your Gmail account.

  4. In INSTANCE TYPE, select the following check box:

    • API Data Protection: Select this option to allow Netskope to scan through your SaaS app instance to list files, user, and other enterprise data.

  5. In GOOGLE DIRECTORY ADMIN EMAIL, enter the email address of the super admin or a user with custom role (see Create a Custom Admin Role for Netskope). The email address should have full access privileges to the following APIs:

    • List users in each sub-domain: https://www.googleapis.com/auth/admin.directory.user

    • List all sub-domains in the organization: https://www.googleapis.com/auth/admin.directory.domain

  6. In GOOGLE MAIL ADMIN EMAIL, enter the email address of the super admin or a user with custom role (see Create a Custom Admin Role for Netskope). The email address should have full access privileges to the following API:

    • Read all resources and their metadata (no write operations): https://www.googleapis.com/auth/gmail.readonly

    Note

    If different email addresses are specified for each email address field, ensure that each email address has the appropriate privileges. To know more about the privileges, see Create a Custom Admin Role for Netskope.

  7. Click Save, then click Grant Access for the app instance you just created. You will be prompted to log in using a super admin or user with custom role and password, and then click Grant. When the configuration results page open, click Close.

    Note

    If different email addresses are specified for each email address field, only the Google Directory API email address can grant access.

Refresh your browser and you will see a green check icon next instance name.

The list of internal users associated with your Gmail domain appear once the connection is established between the Netskope API connector and the Gmail API for your domain. Features such as summary, external user, and email listings are not populated in real-time. They are populated if there are policy hits.

Important Points to Remember

  • While composing an email, a user uploads a file as an attachment. Gmail creates a temporary placeholder for the attachment. Post upload, Gmail sends this placeholder to the trash folder. While these messages don't appear in the Gmail UI, API Data Protection receives and processes the notification for this event. Along with entries for valid emails, Netskope UI shows entries in the Trash folder with nobody, subject as Attachment and details of the uploaded file.

  • When you delete a mail from the Sent folder, Gmail moves the mail to the Trash folder. However, in the API Data Protection dashboard, the mail item is displayed as part of the Sent and Trash folder.

  • When you attach a file using Google Drive, note the following behavior:

    • Insert file as a link - DLP policy hit on the body and subject of the sent email.

    • Insert file as an attachment - DLP policy hit on the body and subject of the sent email.

In this section: