> For the complete documentation index, see [llms.txt](https://docs.docontrol.io/docontrol-user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docontrol.io/docontrol-user-guide/integrations/integrations-google-drive/define-scopes.md).

# Define scopes

To assign permission scopes to your service account for accessing APIs, you need to complete these steps in Google Admin console and DoControl:

1. [Create new API client](#id-1.-create-new-api-client)
2. [Apply permissions](#id-2.-apply-permissions)
3. [Copy and paste snippet](#id-3.-copy-and-paste-snippet)
4. [Optional: Select organizational unit or Google group](#id-4.-select-organizational-unit-or-google-group-optional)

{% hint style="info" %}
If you are an existing customer and want to leverage Google Drive labels in workflows, you need to add the updated snippet in [Copy and paste snippet](#id-3.-copy-and-paste-snippet).
{% endhint %}

<figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FksWVRGduSXBVWVZ7ZZVP%2FGoogle%20Wizard%20define%20scopes.png?alt=media&amp;token=224b69e2-6903-4ccd-ad52-53a8d9fe4f94" alt=""><figcaption></figcaption></figure>

## 1. Create new API client

In Google Admin console, create a dedicated API client for configuring granular permissions.

1. Login to the [Google Admin](https://admin.google.com/u/1/ac/owl/domainwidedelegation?pli=1) console. &#x20;
2. Navigate to Security > API Controls > [Domain-wide delegation](https://admin.google.com/u/2/ac/owl/domainwidedelegation?pli=1).
3. From the top menu, click **Add new**.
4. In the **Client ID** field, paste the client ID that you copied in the previous step: [Copy client ID](https://docs.docontrol.io/docontrol-user-guide/integrations/integrations-google-drive/pages/vNMbzw8IFZMSpBJkCGBg#id-5.-copy-client-id).

## 2. Apply permissions

In the DoControl integration wizard, select the relevant **Read** or **Write** permissions.

1. Go to **Apply permissions.**
2. Select the relevant **Read** or **Write** permissions, or both:
   * **Read** - Monitor file sharing and metadata of Google Drive assets, and detect risky shadow apps (Premium)
   * **Write** - Remediate Google assets for overexposure, and delete risky shadow apps (Premium)<br>

     <figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2Fpp7JmBLS4bHE9HWjye4i%2FGoogle%20Wizard%20permissions.png?alt=media&amp;token=676cc6d9-d92a-4608-ad99-1091c96acf33" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}

* If you are integrating the Shadow App module, the relevant Shadow App permissions are displayed.
* For a detailed description of all permission types, see [Read-only vs write permissions](#read-only-vs-write-permissions).
  {% endhint %}

## 3. Copy and paste snippet

The snippet in the DoControl integration wizard contains all the relevant permissions you need for your API client, depending on your selected use cases. You need to copy the snippet from DoControl, and paste it into the Google Admin console.

<figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FUKFVNiZR5dlIAMgAY4RK%2Fcopy%20and%20paste%20snippet.png?alt=media&amp;token=1bc3e9e0-ef3f-489e-af1e-3374196bbf3c" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
To learn more about the different scopes, see [Read only vs write permissions](#read-only-vs-write-permissions).
{% endhint %}

1. In the DoControl wizard, click **Copy** **snippet**. Depending if you are installing the Shadow App module or not, the snippet contains these permissions:\
   \
   **Read and write with Shadow Apps**\
   `https://www.googleapis.com/auth/admin.reports.audit.readonly,`\
   `https://www.googleapis.com/auth/admin.directory.user.readonly,`\
   `https://www.googleapis.com/auth/drive.readonly,`\
   `https://www.googleapis.com/auth/admin.directory.domain.readonly,`\
   `https://www.googleapis.com/auth/admin.directory.group.readonly,`\
   `https://www.googleapis.com/auth/admin.directory.group.member.readonly,`\
   `https://www.googleapis.com/auth/drive.apps.readonly`\
   `https://www.googleapis.com/auth/admin.directory.orgunit.readonly,`\
   `https://www.googleapis.com/auth/drive.admin.labels.readonly,`\
   `https://www.googleapis.com/auth/drive,`\
   `https://www.googleapis.com/auth/admin.directory.user.security`\
   \
   **Read and write without Shadow Apps**\
   `https://www.googleapis.com/auth/admin.reports.audit.readonly,`\
   `https://www.googleapis.com/auth/admin.directory.user.readonly,`\
   `https://www.googleapis.com/auth/drive.readonly,`\
   `https://www.googleapis.com/auth/admin.directory.domain.readonly,`\
   `https://www.googleapis.com/auth/admin.directory.group.readonly,`\
   `https://www.googleapis.com/auth/admin.directory.group.member.readonly,`\
   `https://www.googleapis.com/auth/drive.apps.readonly,`\
   `https://www.googleapis.com/auth/admin.directory.orgunit.readonly,`\
   `https://www.googleapis.com/auth/drive.admin.labels.readonly,`\
   `https://www.googleapis.com/auth/drive`<br>
2. Login to the [Google Admin console](https://admin.google.com/u/1/ac/owl/domainwidedelegation?pli=1).
3. Select [Domain-wide delegation](https://admin.google.com/u/2/ac/owl/domainwidedelegation?pli=1) > **Add a new client ID.**
4. Paste the snippet into the first line of the **OAuth scopes** field. Do **not** add any extra lines in the OAuth scopes.\
   \
   ![](https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2Fd4KmnnZY512GKOjdaTNb%2Fimage.png?alt=media\&token=40b48d28-1379-4197-8b28-a11d87f6a312)
5. Click **Authorise**.\
   The Google Admin console organizes the snippet content into the relevant scopes.
6. Make sure all your scopes are displayed.
7. Continue to the next optional step: [Select one organizational unit](#id-4.-select-organizational-unit-optional) **OR** continue to: [Upload key file](/docontrol-user-guide/integrations/integrations-google-drive/upload-key-file.md).

## 4. Select organizational unit or Google group (optional)

You can choose to monitor file sharing, access patterns and identities of members in a single organizational unit or up to 5 Google groups, instead of monitoring your entire organization.&#x20;

When you select one organizational unit or several Google groups, such as a business unit, DoControl scans for:

* Events and files **owned by the users** in the organizational unit/ Google groups, or&#x20;
* Files that are found in the **shared drives** connected to the organizational unit/ Google groups&#x20;
* **Access patterns and risky identities** of users in the organizational unit/ Google groups

Other files and users that are outside the selected organizational unit or Google groups are not monitored at all.

{% hint style="success" %}

* This feature is provided on-demand. To enable monitoring of only one organization unit or up to 5 Google groups in your Google Workspace, contact Customer Success.
* If your Google Workspace is already integrated with DoControl, and you decide to narrow your integration to **one organizational unit** or **several Google groups**, you need to disconnect and re-integrate. See [Troubleshooting](#troubleshooting).
  {% endhint %}

### Monitor one organizational unit

The scope for monitoring one organizational unit includes:

* If a user moves outside the organizational unit, then that user won’t be deleted from the DoControl user inventory.&#x20;
* If a file moves from the selected organizational unit user to another user or shared drive that is not connected to DoControl, then that file won’t be deleted from the DoControl asset inventory.
* DoControl alerts are based on the monitored files belonging to the users or shared drives in the organizational unit.
* Access patterns and risky identities of users in the organizational unit

{% hint style="warning" %}
The org unit is defined using the [org unit path](https://admin.google.com/ac/orgunits) in Google Workspace.
{% endhint %}

#### To monitor one organizational unit:

1. To extract the organizational unit path, visit the [org unit settings](https://admin.google.com/ac/orgunits) in the Google Workspace admin console.
2. Select the **Monitor one org unit** checkbox.<br>

   <div align="left"><figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2Fr3JeSGL8AZmC5rgp63hS%2Fselect%20org%20unit.png?alt=media&amp;token=f77f129e-0ee9-4136-ba50-222f6c142521" alt=""><figcaption></figcaption></figure></div>
3. Enter the organizational unit using this syntax:\
   `/sub_ou/sub_sub_ou/user_orgunit`
4. Continue to the next step: [Upload key file](/docontrol-user-guide/integrations/integrations-google-drive/upload-key-file.md).

### Monitor Google groups

DoControl can monitor up to 5 Google groups. The scope for monitoring one or more Google groups includes:

* If a user moves outside the defined Google groups, then that user won’t be deleted from the DoControl user inventory.&#x20;
* If a file moves from a user in a monitored Google group to a user or shared drive that is not monitored by DoControl, then that file won’t be deleted from the DoControl asset inventory.
* DoControl alerts are based on the monitored files belonging to the users or shared drives in the selected Google groups.
* Access patterns and risky identities of users in the monitored Google groups

{% hint style="warning" %}
Google Groups are defined in your [Google Workspace admin console](https://admin.google.com/ac/groups).
{% endhint %}

#### To monitor Google groups:

1. Select the **Monitor** **Google Groups** checkbox.<br>

   <figure><img src="https://3236294211-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MesrnyDMZGYg1V-tOBo%2Fuploads%2FVBlkyZUoeO1qaRdlNacf%2FGoogle%20groups.png?alt=media&amp;token=6acaa27d-6a77-4ca7-9159-a02e4942dbcc" alt=""><figcaption></figcaption></figure>
2. In the Google Workspace admin console, go to [Directory > Groups](https://admin.google.com/ac/groups).&#x20;
3. Copy the email address of the Google group you wish to monitor.
4. Paste the email in the integration wizard.
5. Click **Enter** to add another group. You can add up to 5 Google groups.
6. Continue to the next step: [Upload key file](/docontrol-user-guide/integrations/integrations-google-drive/upload-key-file.md).

## Read only vs write permissions

Depending if you select **read** **only** or **write** scopes, these permissions are applied to your API client:

| **Read only permission**                                                |
| ----------------------------------------------------------------------- |
| `https://www.googleapis.com/auth/admin.reports.audit.readonly`          |
| `https://www.googleapis.com/auth/admin.directory.user.readonly`         |
| `https://www.googleapis.com/auth/drive.readonly`                        |
| `https://www.googleapis.com/auth/admin.directory.domain.readonly`       |
| `https://www.googleapis.com/auth/admin.directory.group.readonly`        |
| `https://www.googleapis.com/auth/admin.directory.group.member.readonly` |
| `https://www.googleapis.com/auth/drive.apps.readonly`                   |
| `https://www.googleapis.com/auth/drive.admin.labels.readonly`           |
|                                                                         |
| **Write permission**                                                    |
| `https://www.googleapis.com/auth/drive`                                 |
| `https://www.googleapis.com/auth/admin.directory.user.security`         |

{% hint style="info" %}
The permissions required for the **Shadow App** module are:

`https://www.googleapis.com/auth/drive.apps.readonly`

`https://www.googleapis.com/auth/admin.directory.user.security`
{% endhint %}

Detailed descriptions of all permission types are:

<table><thead><tr><th width="338">Permission type</th><th>Description</th></tr></thead><tbody><tr><td><strong>Read</strong></td><td></td></tr><tr><td>Events </td><td>Monitor and detect real-time actions in Google Drive </td></tr><tr><td>Inventory data</td><td>Monitor assets, drives, users, domains, groups, and group members</td></tr><tr><td>Shadow App module (premium)</td><td>Detect all internal and 3rd party apps installed in your Google Workspace</td></tr><tr><td>Google Drive file labels</td><td>Detect all Google Drive assets with Google labels</td></tr><tr><td></td><td></td></tr><tr><td><strong>Write</strong> </td><td></td></tr><tr><td>Enforcement</td><td>Remediate Google Drive assets: change asset owner, delete file, remove collaborators, remove sharing links, remove web publishing, prevent malware propagation  </td></tr><tr><td>Shadow app enforcement (premium)</td><td>Revoke user tokens from apps</td></tr></tbody></table>

## Troubleshooting

If your entire Google Workspace was originally integrated with DoControl, and you decide to filter your data to view **one organizational unit** or **several Google groups**, your legacy data still remains in the DoControl platform.

To maintain data integrity when transitioning from a full integration to a single organizational unit or several Google groups, you need to disconnect and re-integrate. Follow these steps:

1. In DoControl, navigate to **Integrations > Data governance**.
2. Select **Google Workspace > Disconnect and delete**.\
   All data related to the Google Workspace integration is removed.
3. Select **Google Workspace > Connect.**
4. Follow the integration wizard to re-integrate DoControl with Google Workspace.
5. Under **Define scopes,** select the relevant organizational unit or Google group.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.docontrol.io/docontrol-user-guide/integrations/integrations-google-drive/define-scopes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.