> For the complete documentation index, see [llms.txt](https://docs.guardware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guardware.com/organisation/integrations/google-workspace.md).

# Google Workspace

GuardWare can scan and monitor Gmail and Google Drive for sensitive data using a Google Cloud service account. GuardWare authenticates with Google's APIs using a service account, a non-human Google account that represents an application rather than a user.

The service account is granted domain-wide delegation, which allows it to access mailboxes and Drive data across your entire Google Workspace organisation on behalf of a super admin.

This page explains how to set up the service account, generate the required credentials, and connect Google Workspace to GuardWare.

## Prerequisites

Before connecting Google Workspace to GuardWare, ensure the following are in place:

* A Google Cloud project with billing enabled
* Google Workspace super admin account
* Google Workspace admin account

## Set Up a Google Cloud Service Account

### Create a Google Cloud project

1. Go to [**Google Cloud Console**](https://console.cloud.google.com) and sign in using an admin account.
2. Click the project dropdown at the top of the page and click **New Project**.<br>

   <div align="left"><figure><img src="/files/9ILrHe9GKy7QAB5sm3sI" alt="" width="563"><figcaption></figcaption></figure></div>
3. Enter a project name and click **Create**.<br>

   <div align="left"><figure><img src="/files/DXhGrejEMrbebLXV79Nw" alt="" width="563"><figcaption></figcaption></figure></div>
4. After creating the project, select it from the project selection dropdown or click **Select Project** in the **Notifications** panel.<br>

   <div align="left"><figure><img src="/files/RZ28dETMLX9qIHAPNPUX" alt="" width="563"><figcaption></figcaption></figure></div>

### Create a Service Account

The service account acts as the identity GuardWare uses to access Google's APIs. The roles assigned here allow it to read organisation-level information during a scan.

1. Click on the <i class="fa-bars">:bars:</i> **menu** and go to **IAM & Admin** > **Service Accounts**.<br>

   <div align="left"><figure><img src="/files/dQvH3NnSyqP5ELLeMLXt" alt="" width="563"><figcaption></figcaption></figure></div>
2. Click **Create Service Account**.<br>

   <div align="left"><figure><img src="/files/gaUeSihVLuTWL4cjjjYA" alt="" width="563"><figcaption></figcaption></figure></div>
3. Enter a name and description for the service account and click **Create and Continue**.<br>

   <div align="left"><figure><img src="/files/DqfEF9fQF6c2wYzxxi89" alt="" width="563"><figcaption></figcaption></figure></div>
4. In the **Permissions (optional)** tab, click on the dropdown and assign the following roles to the service account. Click **+Add another role** each time to add additional roles.<br>

   <div align="left"><figure><img src="/files/m4ig5SUR9SNgN3FmnK09" alt="" width="563"><figcaption></figcaption></figure></div>

   1. Organisation Administrator
   2. Organisation Policy Viewer
   3. Owner
5. Click **Continue**, leave the **Principals with access (optional)** field as is, then click **Done**.<br>

   <div align="left"><figure><img src="/files/5ejxOU5b7zbN4OHviJy7" alt="" width="563"><figcaption></figcaption></figure></div>
6. On the **Service Accounts** page, click the service account you created.<br>

   <div align="left"><figure><img src="/files/OVbhAw4d3ZpXqQqyj6s5" alt="" width="563"><figcaption></figcaption></figure></div>
7. Search for the **Unique ID** shown in the details and store it in a secure location in your device. The Unique ID will be needed in the [**Authorise the service account in Google Workspace**](#authorise-the-service-account-in-google-workspace) section.<br>

   <div align="left"><figure><img src="/files/uhr8rvJnxmUbXG7HsTqC" alt="" width="563"><figcaption></figcaption></figure></div>

### Generate a JSON key

The JSON key is the credential file GuardWare uses to authenticate as the service account. It contains a private key that signs API requests, so it **must be kept secure and not shared with anyone**.

1. In **IAM & Admin > Service Accounts**, click the service account you created and click on the **Keys** tab.
2. Click **Add Key** and select **Create new key** from the dropdown.<br>

   <div align="left"><figure><img src="/files/wCDfuQLAB7vJS7ZoHGmG" alt=""><figcaption></figcaption></figure></div>
3. Select **JSON**, click **Create,** and click **Close**. **The key file downloads automatically.**<br>

   <div align="left"><figure><img src="/files/3CTa9zkLNuBBXY7jUHLD" alt="" width="494"><figcaption></figcaption></figure></div>

{% hint style="info" %}
**Store the JSON key securely**, as you will need to send it to the GuardWare team and use it to add target discovery in DISCOVER.&#x20;
{% endhint %}

### Authorise the service account in Google Workspace

Domain-wide delegation grants the service account permission to impersonate users across the organisation. **This step must be completed by a super admin in Google Workspace Admin Console.**

{% hint style="warning" %}
The Google Workspace super admin authorises the service account to access data across the organisation on behalf of all users.
{% endhint %}

1. Go to [**Google Workspace Admin Console**](https://admin.google.com) with **a super admin account** and navigate to **Security** > **Access and data control** > **API controls**.<br>

   <div align="left"><figure><img src="/files/qK5Qy0ei2SxHedWm6SNU" alt="" width="563"><figcaption></figcaption></figure></div>
2. Click **Manage Domain Wide Delegation**.<br>

   <div align="left"><figure><img src="/files/VCfYDx6I6jYu5zbL7SOD" alt="" width="563"><figcaption></figcaption></figure></div>
3. Click **Add new**.<br>

   <div align="left"><figure><img src="/files/n7eylqf48zxDJvcipPmE" alt="" width="563"><figcaption></figcaption></figure></div>
4. Enter the service account's **Unique ID** in the **Client ID** field.
5. Enter the required OAuth scopes for Gmail and Google Drive as comma-separated values.
   1. `https://www.googleapis.com/auth/admin.directory.user.readonly`
   2. `https://www.googleapis.com/auth/admin.directory.group.readonly`
   3. `https://www.googleapis.com/auth/admin.directory.orgunit.readonly`
   4. `https://www.googleapis.com/auth/admin.reports.audit.readonly`
   5. `https://www.googleapis.com/auth/drive`
   6. `https://www.googleapis.com/auth/gmail.readonly`
   7. `https://www.googleapis.com/auth/gmail.modify`
   8. `https://mail.google.com/`
6. Click **Authorise**.

Changes to domain-wide delegation can take time to propagate across the organisation. If GuardWare cannot authenticate immediately after saving, wait and retry.

## Send details to GuardWare

After configuring everything, send the following details to the GuardWare team:

1. JSON key&#x20;
2. Google Workspace admin email address that is used to create the JSON Key&#x20;

## Scan Gmail and Google Drive in DISCOVER

After you finish the setup here, complete the scan flow in DISCOVER to start scanning Gmail and Google Drive for sensitive data.&#x20;

Use [**Target Discovery**](/discover/scan/target-discovery.md#add-services) to add the Google Workspace service and let GuardWare discover the available Gmail and Google Drive targets. Then create [**scan jobs**](/discover/scan/scans.md#one-time-scan) to scan Gmail and Google Drive for sensitive data.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.guardware.com/organisation/integrations/google-workspace.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.