> For the complete documentation index, see [llms.txt](https://help.datadefender.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.datadefender.io/getting-started/linking-google-workspace/connecting-google-workspace-to-datadefender.md).

# Connecting Google Workspace to DataDefender

Connect your Google Workspace environment to DataDefender to enable automated Google Drive inventorying and data classification.

### Who Needs to Be Involved?

Setup requires administrative access in both Google Cloud (GCP) and Google Workspace.\
Depending on your team structure, one person can perform all steps, or a Cloud Engineer can complete Steps 1–2 while a Workspace Super Admin completes Steps 3–5.<br>

| Role                  | Steps       | Tools & Access Required                                                                                                                                                                  |
| --------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GCP Project Admin     | Steps 1 & 2 | <p>• Target GCP Project</p><p>• gcloud CLI & Terraform 1.5+</p><p>• DataDefender Terraform package (downloaded from app)</p><p>• AWS Account ID</p><p>• DataDefender Organization ID</p> |
| Workspace Super Admin | Steps 3–5   | • Access to Google Workspace Admin Console (admin.google.com)                                                                                                                            |

### Setup Instructions

**Step 1: Authenticate to Your GCP Project**

Open your terminal, authenticate the gcloud CLI, and set your target Google Cloud project:

```bash
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
```

**Step 2: Apply the Infrastructure via Terraform**

<img src="https://3802454275-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FobDf5vJfItiNrkno1uJc%2Fuploads%2FlrZczbZwiQ8EvXv0YLR4%2Funknown.png?alt=media&amp;token=e16e2bbd-7629-4633-b9fc-ef1f76a8152a" alt="" height="116" width="417">

Download the DataDefender Terraform ZIP file from the Connect Google Drive page. This is accessed through Settings -> Cloud Connectivity -> Add New Connection -> Google Drive.\
\
Once you have the ZIP file downloaded, navigate to its directory in your terminal, and run:

```bash
terraform init
terraform apply \
  -var "project_id=YOUR_PROJECT_ID" \
  -var "scanning_aws_account_id=YOUR_AWS_ACCOUNT_ID" \
  -var "organization_id=YOUR_DATADEFENDER_ORGANIZATION_ID"
```

Optional: If you customized your AWS Agent Role Name during onboarding, append `-var "agent_aws_role_name=YOUR_ROLE_NAME"` to the command above (default is `CloudStorageSecAgentRole`).

Review the plan, type `yes` when prompted, and then retrieve the values required for the next step:

```bash
terraform output dwd_authorization_table
```

Note on Terraform State: By default, local execution stores state files locally in your working directory. We strongly recommend persisting state using a[ remote backend](https://developer.hashicorp.com/terraform/language/state/remote) configured with a[ backend block](https://developer.hashicorp.com/terraform/language/backend) (such as Google Cloud Storage) to manage state securely across your team.

**Step 3: Authorize Domain-Wide Delegation**

Because Google requires explicit administrative approval for high-privilege API scopes, a Workspace Super Admin must grant delegation manually in the Admin Console.

1. Log in to[ admin.google.com](https://admin.google.com).
2. Navigate to Security -> Access and data control -> API controls.
3. Under Domain-wide delegation, click Manage Domain Wide Delegation.
4. Click Add new for each of the two entries in your `terraform output` table and enter the corresponding Client ID and OAuth Scopes:

| Service Account | Required OAuth Scopes                                                                                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Backend         | <https://www.googleapis.com/auth/drive,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/cloud-identity.policies.readonly> |
| Agent           | <https://www.googleapis.com/auth/drive.readonly>                                                                                                                       |

1. Click Authorize and verify both entries appear in your list with active status.

**Step 4: Create the Impersonation Admin User**

DataDefender uses this identity as its "impersonation subject." When our backend inventories your environment, lists users, or manages Shared Drive access rules, it acts as this specific identity under the Domain-Wide Delegation scopes authorized in Step 3.

We strongly recommend creating a dedicated service user (e.g., `datadefender-admin@yourdomain.com`) rather than linking an existing person’s admin account.

How to Set Up:

1. In the Admin Console, go to Directory -> Users -> Add new user (e.g., `datadefender-admin@yourdomain.com`).
2. Go to Account -> Admin roles -> Create new role.
3. Name the role DataDefender Administrator and check only the Drive and Docs Administrator privilege.
4. Assign this custom role to `datadefender-admin@yourdomain.com`.
5. Record the full email address to submit during onboarding.

Why a Dedicated Account is Recommended:

* Clear Audit Trail: Every API management action performed by DataDefender is isolated to this single identity in your Workspace audit logs.
* Least Privilege: Existing admin accounts are usually over-privileged. A dedicated account constrains DataDefender strictly to Drive and Docs Administrator rights.
* Continuity & Revocation: Access remains unaffected by staff changes, and can be suspended in a single click without impacting real users.

**Step 5: Create the Crawler User**

This account is distinct from the Impersonation Admin in Step 4. While Step 4 handles administrative discovery and setup, the Crawler User is a standard account used during automated scanning runs to safely inspect file contents.

When DataDefender scans a Shared Drive, our backend dynamically grants this Crawler account Reader access to the drive.

How to Set Up:

1. In the Admin Console, go to Directory -> Users -> Add new user (e.g., `datadefender-crawler@yourdomain.com`).
2. Do not grant this account any admin roles or administrative privileges.
3. Record the full email address to submit during onboarding.

Why Two Separate Accounts?

* Separation of Duties: Administrative operations (listing users, mapping drives) are isolated from content reading.
* Security & Minimal Access: The Crawler User operates as a basic Workspace user with zero admin rights. It only sees content in Shared Drives where it has been explicitly assigned read access during an active scan.

### Onboarding Completion Checklist

Verify the following before submitting details to DataDefender:

* `terraform plan` returns No changes (confirming idempotent configuration).
* Both Client IDs are authorized under Domain-Wide Delegation in the Workspace Admin Console.
* Dedicated Impersonation Admin user exists with the Drive and Docs Administrator role.
* Dedicated Crawler User exists as a standard user account.

Final Step: Provide the email addresses for the Impersonation Admin (`datadefender-admin@...`) and Crawler User (`datadefender-crawler@...`) to your DataDefender account manager. These values will be required to complete the Google Drive connection within Settings -> Cloud Connectivity.

### Disconnecting & Teardown

To completely remove DataDefender's access from your environment:

1. Destroy GCP Infrastructure: Open your terminal in the Terraform directory and run:

   ```bash
   terraform destroy
   ```
2. (Note: This removes service accounts and WIF bindings, but leaves GCP APIs enabled so other workloads in your project are not impacted).\
   Remove Domain-Wide Delegation: In the Workspace Admin Console (Security -> Access and data control -> API Controls -> Domain Wide Delegation), delete both authorization entries.
3. Remove User Accounts: Delete or suspend the `datadefender-admin` and `datadefender-crawler` user accounts.
4. If you want to fully unlink this Google Drive workspace from DataDefender, you will also want to login to the DataDefender application, navigate to Settings > Cloud Connectivity, and remove the provider connection.

### Appendix: Security Architecture

Architecture & Security Overview

* Keyless Authentication (Federation): No service account keys, secrets, or long-lived passwords are ever generated or stored. Authentication occurs dynamically over short-lived Google tokens using Workload Identity Federation (WIF).
* Explicit Grants: Federation only verifies identity—it does not grant access to data. Access is strictly constrained through Domain-Wide Delegation (scoped to specific, minimal OAuth permissions) and the dedicated impersonation identity.
* Instant Revocation: You retain 100% control over your data. You can completely revoke DataDefender’s access at any time by removing the delegation entries or suspending the service user accounts in Google Workspace.