Configure Gmail for API Data Protection
Configure Gmail for API Data Protection
- the Gmail app will be available under Configure App Access > Next Gen > CASB API.
- classic policies will be automatically migrated to Next Generation API Data Protection and will be available under Policies > API Data Protection > SAAS > Next Gen.
- the Gmail dashboard page will be available under API-enabled Protection > SAAS (Next Gen) > Dashboard.
- you can view the Inventory page under API-enabled Protection > SAAS (Next Gen) > Inventory.
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:
- Access this URL: https://workspace.google.com/marketplace/app/netskope/1055677045599.
- Click Install.
- Log in using the admin username and password.
- Click Install.
- In the Domain wide install pop-up window, click CONTINUE.
- 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.
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.
- Log in to admin.google.com.
- Click the triple bar on the top-left corner of the home page and navigate to Account > Admin roles.
- Click Create new role.
- Enter a name and description for the role and click CONTINUE.
- 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 PrivilegesPrivileges 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. - 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:
- Log in to the Netskope tenant UI and go to Settings > Configure App Access > Classic > SaaS.
- Select the Gmail icon, and then click Setup Instance.
The Setup Instance window opens.
- In the INSTANCE NAME, enter the domain name for your Gmail account.
- 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.
- 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
- List users in each sub-domain:
- 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.
- Read all resources and their metadata (no write operations):
- 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.
