# Google Workspace

> Connect Google Workspace to Tidal Control so compliance tests read your users, groups and admin settings. Read-only, and also usable to import personnel.

Source: https://tidalcontrol.com/docs/integrations/google-workspace

Tidal Control's Google Workspace integration monitors your organisation's users, groups, and admin settings for compliance purposes.

## What this integration monitors

- **Users:** Account status, permissions, and security settings
- **Groups:** Membership and access controls
- **Admin settings:** Security policies and configurations
- **Devices:** Security configurations of mobile devices and ChromeOS devices via Endpoint Verification (optional)

## Requirements

- Super User role in Tidal Control
- Google Workspace super admin rights
- Access to Google Cloud Console and Google Admin Console (admin.google.com)

## Configuration step-by-step plan

We'll create a **Google service account** with domain-wide delegation and the necessary permissions to access your Google Workspace admin data through secure APIs. If you also want to set up Google Drive, we'll add the required configuration at each step.

**Configuration steps:**

1. **Create service account**
2. **Generate JSON key**
3. **Set up domain-wide delegation**
4. **Configure API scopes**
5. **Enable APIs**
6. **Configure integrations**

## Required permissions

Tidal Control uses read-only OAuth scopes (via domain-wide delegation) to access your Google Workspace admin data. All access is read-only. Tidal Control never writes, modifies, or deletes anything in your Google Workspace or Drive environment.

> **info:**

**Partial configuration works:** You only need to configure the scopes for the features you want to use. For example, if you only configure the Workspace scopes, the Workspace tests will run normally. Drive and device tests will simply not be available. You can always add additional scopes later.

<table>
<thead>
<tr><th>Feature</th><th>OAuth scope</th><th>Why we need access</th></tr>
</thead>
<tbody>
<tr><td><strong>Users</strong></td><td><code>admin.directory.user.readonly</code></td><td>We check user account status, security settings, and admin privilege levels.</td></tr>
<tr><td><strong>Groups</strong></td><td><code>admin.directory.group.readonly</code>, <code>admin.directory.group.member.readonly</code></td><td>We verify group memberships and access controls to check who has access to what.</td></tr>
<tr><td><strong>Admin roles</strong></td><td><code>admin.directory.rolemanagement.readonly</code></td><td>We check which admin roles are assigned and to whom, to verify privilege management.</td></tr>
<tr><td><strong>Google Drive</strong> (optional)</td><td><code>drive.readonly</code></td><td>We check file sharing settings and external access configurations of Drive files and folders.</td></tr>
<tr><td><strong>Mobile devices</strong> (optional)</td><td><code>admin.directory.device.mobile.readonly</code></td><td>We verify security configurations of managed mobile devices via Endpoint Verification.</td></tr>
<tr><td><strong>ChromeOS devices</strong> (optional)</td><td><code>admin.directory.device.chromeos.readonly</code></td><td>We verify security configurations of ChromeOS devices via Endpoint Verification.</td></tr>
</tbody>
</table>

## Step 1: Create service account

- Go to **Google Cloud Console** at https://console.cloud.google.com
- Log in with account that has **project access**
- Select your **Google Cloud project** in project selector
- Navigate to **IAM & Admin → Service Accounts**
- Click **"+ CREATE SERVICE ACCOUNT"**
- Fill in service account details:
  - **Service account name:** `Tidal Control Workspace`
  - **Service account ID:** `tidal-control-workspace`
  - **Description:** `Service account for Tidal Control Google Workspace monitoring`

## Step 2: Generate JSON key

- **Skip role assignment** by clicking **"Continue"** twice
- Click **"Done"** to create service account
- **Select new service account** from list
- Go to **"KEYS"** tab
- Click **"ADD KEY"** → **"Create new key"**
- Select **JSON** format
- **Download JSON file** automatically to computer
- **Store file securely** - needed for integration setup

## Step 3: Set up domain-wide delegation

- Go back to **service account details** in Google Cloud Console
- Click **"Advanced settings"** section to expand
- **Copy Client ID** (save for next step)
- Go to **Google Admin Console** at https://admin.google.com
- Navigate to **Security → Access and data control → API controls → Domain-wide delegation**
- Ensure you have **super admin rights** in Google Workspace

## Step 4: Configure API scopes

- Click **"Add new"** in the domain-wide delegation screen
- **Paste Client ID** of the service account (from step 3)
- Enter the **OAuth Scopes** you need (comma separated):

**For Google Workspace:**
```
https://www.googleapis.com/auth/admin.directory.user.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/admin.directory.rolemanagement.readonly
```

**For Google Drive, add this scope:**
```
https://www.googleapis.com/auth/drive.readonly
```

**For Endpoint Verification (device security monitoring), add these scopes:**
```
https://www.googleapis.com/auth/admin.directory.device.mobile.readonly,https://www.googleapis.com/auth/admin.directory.device.chromeos.readonly
```

> **warning:**

**Endpoint Verification requires additional admin rights:** The impersonation user must have the **Mobile Device Management** admin privilege (or be a Super Admin) in Google Workspace. Without this, device monitoring tests will return a permission error.

> **tip:**

**Combining scopes:** If you are setting up multiple features, combine all scopes in a single comma-separated entry.

- Click **"AUTHORISE"** to assign permissions

## Step 5: Enable APIs

- Return to **Google Cloud Console**
- Navigate to **APIs & Services → Library**
- **Search and enable** the following API:
  - **Admin SDK API**
- **Click "ENABLE"** for the API

**For Google Drive, also enable:**
- **Google Drive API**

## Step 6: Configure integrations

- Go to **Settings → Integrations** in Tidal Control
- Click the **plus icon** next to **Google Workspace**
- Fill in configuration:
  - **Name:** `Google Workspace`
  - **Service Account JSON:** Upload or paste contents of JSON file
  - **Impersonation user email:** Email of a Google Workspace admin user (e.g. `admin@company.com`)
- Click **"Create"** to save integration

> **warning:**

**The impersonation user email must be a real Google Workspace admin user** (e.g. `admin@company.com`). This is not the service account email (which ends in `@project.iam.gserviceaccount.com`). The service account uses this email to impersonate a Workspace admin and access admin APIs.

**For Google Drive, add this:**
- Click the **plus icon** next to **Google Drive**
- Fill in configuration:
  - **Name:** `Google Drive`
  - **Service Account JSON:** Upload same JSON file
  - **Impersonation user email:** Same Workspace admin email (e.g. `admin@company.com`)
- Click **"Create"** to save integration

> **tip:**

**One service account, multiple integrations:** You can use the same JSON key file for both Google Workspace and Google Drive integrations.

## Configuration fields explained

The integration dialog asks for the following values:

**Name:**
- A descriptive name for this integration
- For example: `Google Workspace`, `Google Drive`

**Service Account JSON:**
- Contains authentication credentials for your service account
- Downloaded in step 2 during service account creation
- Keep this file secure - it provides access to your Google environment

**Impersonation user email:**
- Email of a Google Workspace admin user that the service account will impersonate
- This user must have **super admin rights** in Google Workspace
- For example: `admin@company.com`, `it-admin@organisation.org`
- Required for access to Workspace admin APIs and Drive

> **info:**

**This is not the service account email.** The impersonation user email is a real person's Workspace account with admin rights, not the technical service account address (name@project.iam.gserviceaccount.com).

## Verification

The integration is working when all of the following are true:

- Settings → Integrations shows Google Workspace under **Configured Integrations**
- Google Workspace test available in Tests section
- Test refresh delivers results without authentication errors

> **warning:**

**JSON key security:** Store the JSON key file securely - it provides access to your Google environment and cannot be downloaded again

## Frequently asked questions

**Can I use the same service account for multiple Tidal Control environments?**
Yes, you can reuse the same service account JSON key across different Tidal Control instances.

**What happens if I disable domain-wide delegation?**
The integration will stop working immediately as Tidal Control won't be able to access Workspace admin APIs.

**How often does Tidal Control sync Workspace data?**
Data is synchronized according to your configured test schedule, typically every few hours.

## Common problems

**"Authentication failed" errors**
- Verify the JSON key file is correctly uploaded
- Check that domain-wide delegation is configured with the correct Client ID
- Confirm the impersonation user email belongs to a user with super admin rights

**"API not enabled" errors**
- Ensure Admin SDK API is enabled in your Google Cloud project
- Wait a few minutes after enabling APIs before testing the integration

**"Permission denied" errors**
- Verify OAuth scopes are correctly configured in domain-wide delegation
- Check that the impersonation user email is a real Workspace admin user, not the service account email

### Still can't figure it out?

Send an email to support@tidalcontrol.com, and we'll get back to you as soon as possible.

> **info:**

**Gather support info:** Note which browser you're using, exact error messages, and which steps you've already tried. This speeds up the solution considerably.