Skip to content

Home

Jump to bottom
Erick Cheng edited this page Jul 30, 2018 · 14 revisions

Introduction

Guide to begin reviewing and enforcing GSuite third-party apps via OAuth permissions. This guide is for anyone looking to gain visibility and control into how third-party applications are accessing their organization's GSuite data.

It will also protect against phishing attacks like the Google Docs worm that affected roughly 1 million Gmail users in 2017: https://www.theverge.com/2017/5/3/15534768/google-docs-phishing-attack-share-this-document-with-you-spam

Enabling allow lists in GSuite for my organization was unexpectedly complex and time consuming.

It required us to establish new processes, coordinate across orgs, and break things.

I hope this guide will simplify that process for you.

Through it, you will gain a better understanding of which apps have access to your data, implement a process to control it, and you may even find a few malicious apps along the way.

OAuth Scopes

More about OAuth restrictions in GSuite: https://www.blog.google/products/g-suite/manage-access-third-party-apps-new-g-suite-security-controls/

OAuth apps allow list helps keep your data safe by letting admins specifically select which third-party apps are allowed to access users’ G Suite data. Once an app is part of a allow list, users can choose to grant authorized access to their G Suite apps data. This prevents malicious apps from tricking users into accidentally granting access to their corporate data.

G Suite gives admins the ability to choose which of their core services to disable API access to: Gmail, Drive, Calendar, Contacts, Admin, Vault & Cloud.

Disabling API access will block all existing and future third-party apps not on the allow list.

For Gmail and Drive APIs, G Suite provides a greater level of access control called "high risk access" - scopes are deemed "high risk" if they would allow a third-party app to send emails on a user's behalf, or access to sensitive data. Enabling the "high risk access" feature allows users the freedom to install low risk apps, while prohibiting them from authorizing apps with high risk scopes.

This guide is primarily focused on helping you enable "high risk access", but the same methodology could be applied to Google's other APIs.

High Risk Access

The specific OAuth scopes blocked by enabling this feature are not publicly documented. According to G Suite support, they are:

Gmail

Source: https://developers.google.com/identity/protocols/googlescopes#gmailv1

Scope Description
https://mail.google.com/ Read, send, delete, and manage your email
https://www.googleapis.com/auth/gmail.compose Manage drafts and send emails
https://www.googleapis.com/auth/gmail.insert Insert mail into your mailbox
https://www.googleapis.com/auth/gmail.labels Manage mailbox labels
https://www.googleapis.com/auth/gmail.modify View and modify but not delete your email
https://www.googleapis.com/auth/gmail.readonly View your email messages and settings
https://www.googleapis.com/auth/gmail.send Send email on your behalf
https://www.googleapis.com/auth/gmail.settings.basic Manage your basic mail settings
https://www.googleapis.com/auth/gmail.settings.sharing Manage your sensitive mail settings, including who can manage your mail

Drive

Source: https://developers.google.com/identity/protocols/googlescopes#drivev3

Scope Description
https://www.googleapis.com/auth/drive View and manage the files in your Google Drive
https://www.googleapis.com/auth/drive.file View and manage Google Drive files and folders that you have
https://www.googleapis.com/auth/drive.metadata View and manage metadata of files in your Google Drive
https://www.googleapis.com/auth/drive.photos.readonly View the photos, videos and albums in your Google Photos
https://www.googleapis.com/auth/drive.readonly View the files in your Google Drive
https://www.googleapis.com/auth/drive.scripts Modify your Google Apps Script scripts' behavior

Step 1. Generate Report of Third-Party Apps

Prerequisites

  1. Step 1 may timeout if your G Suite organization has more than 800 users. Instead, please skip straight to: Alternative Utilizing GAM_
  2. G Suite API access enabled https://support.google.com/a/answer/60757?hl=en
  3. G Suite admin role “Group Admin” https://support.google.com/a/answer/2405986

Install

Step 1: Create Sheet & Script

  1. Log into G Suite using your admin account.
  2. Navigate to Google Drive (drive.google.com) and create a new Sheet.
  3. On the Sheet's toolbar, click Tools > Script Editor....
  4. In the Apps Script editor, copy and paste third-party-app-report.gs
  5. (Optional) Update the variable 'domain' on line 55 of third-party-app-report.gs if your organization has multiple domains.
  6. Save (ctrl+s)

Step 2: Enable Directory API

  1. In the Apps Script editor, click Resources > Advanced Google Services.
  2. Locate Admin Directory API in the dialog and click the corresponding toggle, setting it to on.
  3. Click the Google API Console link at the bottom.
  4. Enter "Admin SDK" into the search box and click on the corresponding entry in the results.
  5. Click the Enable API button.
  6. Return to the Apps Script editor and click the OK button on the Advanced Google Services dialog.

Step 3: Run Function and Authorize Access

  1. In App Script editor, click Run > step1.
    1. Authorize access if you're running this for the first time.
    2. Function step1 will create a new tab named "OAuth Tokens" in your original Sheet. "OAuth Tokens" will contain a list of all third-party apps your active users have installed. If step1 times out (5 minutes with Apps Script), check out: Alternative Utilizing GAM
  2. In App Script editor, click Run > step2.
    1. Function step2 will create a new tab named "Counts" in your original Sheet. "Counts" will contain data extrapolated from the "OAuth Tokens" tab; notably number of installs and high risk scopes.

Alternative Utilizing GAM

  1. Install GAM by jay0lee: https://github.com/jay0lee/GAM
  2. Run the command:

gam all users print tokens todrive

  1. Navigate to Google Drive (drive.google.com) and open the new sheet generated by GAM
  2. On the Sheet's toolbar, click Tools > Script Editor....
  3. In the Apps Script editor, copy and paste third-party-app-report.gs
  4. Save (ctrl+s)
  5. Click Run > step2. Allow access to Sheets
  6. Function step2 will create a new tab named "Counts" in your original Sheet. "Counts" will contain data extrapolated from the "OAuth Tokens" tab; notably number of installs and high risk scopes.

Step 2. Review Third-Party Apps

Existing Apps

With your shiny new report in hand, you can now venture forth and tackle the security risk assessment of third-party apps. Risk assessment is beyond the scope of this guide, but some advice would be to prioritize the most installed apps that are categorized as high risk.

Future Apps

Before you enable blocking of API scopes, you will want to setup a procedure for users to request access to third-party apps. You may also want to communicate the change ahead of time so that users will know what to expect after you enable the allow list. Luckily, G Suite lets you to display a custom message when users try to add or access unapproved apps with disabled permissions. You should come up with your own procedure here that will best suit your organization.

Just to give you some ideas, the process I came up with involves a combination of Google Forms for app requests, and Slack's email integration for questions/discussion. When users are blocked from adding an app, a custom message will ask the users to fill out a Google Form. The Google Form responses are then dropped into the original Sheet from Step 1, and also dropped into our Slack channel via Email Integration.

Here is an example of what the user will see:

To setup a custom message in G Suite:

  1. Navigate to https://admin.google.com
  2. Click Security > API Permissions.
  3. Click Display message when users try to access apps with disabled permissions to create a new message containing:
    1. Google Form URL
    2. Slack channel

Step 3. Create the Allow List

Google documents how to allow list in Step 2 of their article - https://support.google.com/a/answer/7281227?hl=en

Step 4. Enable the Allow List

Yay, you have made it! Only after completing all the previous steps should you enable blocking - otherwise you run the risk of disrupting your users.

Google documents how to block scopes in Step 3 of their article - https://support.google.com/a/answer/7281227?hl=en

Step 5. Aftermath

Make yourself available for the next few days as you are bound to get a questions or app approval requests. Adding the app to the allow list should immediately fix the issue without users having to re-auth.

Acknowledgments

Clone this wiki locally