# Google Workspace (G Suite)

## Introduction 

Google Workspace (G Suite) is a powerful suite of tools that helps teams collaborate and communicate effectively. It can be integrated with a variety of other tools to streamline workflows and improve efficiency. This guide will walk you through the steps required to integrate Google Workspace with Perimeters.

## Available Features

* Misconfiguration Rules
* Identity Rules
* User Inventory
* Shadow Application Inventory
* Devices Inventory
* Shadow Application Rules

## Prerequisites

* A Google Workspace (G Suite) Business Starter subscription or higher.
* A user account within the Google Workspace instance with the required privileges, or a Super Admin account.

<details>

<summary><strong>Follow these steps to create custom role for integration</strong></summary>

1. Login to <https://admin.google.com/ac/users>
2. Click add new user, fill the identity details and primary email -> Select 'Add New User'.
3. Go to <https://admin.google.com/ac/list/roles>
4. Click 'Create new role'
5. Add suitable name and description. eg *Custom Perimeters Integration*&#x20;
6. Search and select following privileges:
   * Reports
   * User Security Management
   * Groups -> Read
   * Organization Units -> Read
   * Users -> Read
   * Services -> Groups for Business -> Groups Service Settings
7. Click 'Save'&#x20;
8. Select new created custom Role eg. *Custom Perimeters Integration*&#x20;
9. Assign User -> Select Newly Created user.

</details>

## Required Scopes

| Scope                                                                      | Use                                                                                |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| <https://www.googleapis.com/auth/userinfo.email>                           | See your primary Google Account email address                                      |
| <https://www.googleapis.com/auth/userinfo.profile>                         | See your personal info, including any personal info you've made publicly available |
| <https://www.googleapis.com/auth/directory.readonly>                       | See your organization's GSuite directory                                           |
| <https://www.googleapis.com/auth/admin.directory.user.readonly>            | See info about users on your domain                                                |
| <https://www.googleapis.com/auth/admin.directory.user.security>            | Read permissions for users on your domain                                          |
| <https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly>  | View delegated admin roles for your domain                                         |
| <https://www.googleapis.com/auth/admin.directory.group.readonly>           | View groups on your domain                                                         |
| <https://www.googleapis.com/auth/admin.directory.device.mobile.readonly>   | View your mobile devices' metadata                                                 |
| <https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly> | View your ChromeOS devices' metadata                                               |
| <https://www.googleapis.com/auth/admin.directory.domain.readonly>          | View domains related to your customers                                             |
| <https://apps-apis.google.com/a/feeds/domain/>                             | View Google Single Sign On information                                             |
| <https://www.googleapis.com/auth/apps.groups.settings>                     | View the settings of a G Suite group                                               |
| <https://www.googleapis.com/auth/admin.reports.audit.readonly>             | View audit reports for your G Suite domain                                         |

## Onboarding Google Workspace (G Suite) in your Perimeters account

1. Go to "Integrations" -> Select "Google Workspace" -> Click "+ Add" -> Click "+ Start Integration".
2. **"OAuth" -**\
   Click "Sign in with Google" -> Check all the scopes checkboxes and click on "Continue".
3. Click "Finish" to complete the onboarding process.

Once you have completed these steps, Google Workspace (G Suite) should be successfully integrated with your Perimeters account.

**Note**: Perimeters uses and transfers information using Google APIs. It does so in accordance with its [privacy policy](https://www.perimeters.io/privacy) and in compliance with the [Google API Services User Data Policy](https://developers.google.com/terms/api-services-user-data-policy).

## **Granting Additional Feature Access**

To allow access to users' data without their explicit consent, add scopes in Domain Wide Delegation. Feature details, required scopes, and steps are outlined below.

&#x20;1\) *Go to* [***Google Workspace Admin Console***](https://admin.google.com/) *-> Security -> Access and data control -> API Controls ->* [*Manage Domain-wide delegation.*](https://admin.google.com/ac/owl/domainwidedelegation)

2\) Click -> Add New Client -> Google Consent form should be presented to you with a request to grant [**required privileges**](https://support.perimeters.io/perimeters-documentation/connecting-perimeters/saas-applications/google-workspace-g-suite#required-privileges). and add clientId as - 101707398122463816262.

3\) Examine the permissions and select 'Continue' to grant authorization for your integration.

4\) Once done, click on th&#x65;**"Validate"** button below to verify the installation.

### Integration Scopes

Following scopes are required **if custom role** is being used for integration.

| Scope                                                                      | Use                       |
| -------------------------------------------------------------------------- | ------------------------- |
| <https://www.googleapis.com/auth/admin.directory.device.mobile.readonly>   | Read Mobile Devices       |
| <https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly> | Read ChromeOS Devices     |
| <https://www.googleapis.com/auth/admin.directory.domain.readonly>          | Read Organization Domains |
| <https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly>  | Read Roles                |
| <https://www.googleapis.com/auth/admin.directory.user.security>            | Read User OAuth Tokens    |

### Misconfiguration Rules

The following scopes give finer misconfiguration insights on an Organization Unit level.

<table><thead><tr><th>Scope</th><th width="246">Use</th></tr></thead><tbody><tr><td>https://www.googleapis.com/auth/cloud-identity.policies.readonly</td><td>Read Configurations</td></tr><tr><td>https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly</td><td>Read Single Sign On Information</td></tr><tr><td>https://www.googleapis.com/auth/admin.directory.orgunit.readonly</td><td>Read Organization Units</td></tr><tr><td>https://www.googleapis.com/auth/apps.licensing</td><td>Read User's License Details</td></tr></tbody></table>

### Shadow Applications

When a user grants Perimeters.io access to read organisational email metadata, our platform scans the metadata across the entire organization to detect and identify SaaS application usage (also known as Shadow IT). Perimeters.io only accesses email metadata, ensuring the security of the email content.

This process provides visibility into third-party applications being used within the organization, helping IT and security teams authorize and manage these based on potential risks and take corrective action.

| Scope                                                           | Use                        |
| --------------------------------------------------------------- | -------------------------- |
| <https://www.googleapis.com/auth/gmail.metadata>                | Read Users' Email Metadata |
| <https://www.googleapis.com/auth/admin.directory.user.readonly> | Read Directory Users       |

### Shared Data

This is essential in identifying user activity and threats related to data transfers.

| Scope                                                        | Use                              |
| ------------------------------------------------------------ | -------------------------------- |
| <p><https://www.googleapis.com/auth/drive.readonly>          |                                  |
| <br></p>                                                     | Read Drive Files Metadata        |
| <p><https://www.googleapis.com/auth/drive>                   |                                  |
| <br></p>                                                     | Modify Files Sharing             |
| <p><https://www.googleapis.com/auth/drive.activity.readonly> |                                  |
| <br></p>                                                     | Read Drive Files Sharing Changes |

Once you have completed these steps, Google Workspace should be successfully integrated with your Perimeters account.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.perimeters.io/perimeters-documentation/connecting-perimeters/integrations-for-security-insights/saas-applications/google-workspace-g-suite.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.