> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cimento.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Google Workspace

> Import your Google Workspace directory and place phishing simulations directly in Gmail inboxes, step by step, using domain-wide delegation.

Cimento uses Google Workspace for two things, each with its own setup wizard: importing your employee directory, and placing phishing simulations directly in Gmail inboxes. Both work through domain-wide delegation to a service account Cimento creates for your organization. You never create credentials or share a password.

## Before you start

* A Google Workspace Super Admin. Only a Super Admin can authorize domain-wide delegation.
* For the directory, an administrator contact on file with Cimento who is a Google Workspace admin able to view users and groups. Cimento reads the directory as that account. Your Cimento contact can tell you which address is on file.
* For the directory, your organization's email domains registered with Cimento. Only people in those domains are imported.

<Tip>
  Both setups use the same client ID, and Google keeps one list of scopes per client ID. If you set up both, the second time you'll find the client ID already listed. Edit that entry and add the new scopes to it; don't replace it.
</Tip>

## Import your directory

In Cimento this is **Google Workspace User Provisioning**. Cimento reads users, groups and group memberships with read-only access, and never changes your directory.

<Note>
  Your organization connects one directory, and switching to another later needs Cimento support. As soon as you click **Begin Setup**, employees come from Google: you can no longer add or upload employees in Cimento, or edit their names, email addresses, status or departments.
</Note>

<Steps>
  <Step title="Start setup in Cimento">
    Go to **Admin → Integrations → Employee data**. Under **Directory provider**, choose **Google Workspace User Provisioning** and click **Begin Setup**.
  </Step>

  <Step title="Open domain-wide delegation">
    Sign in to [admin.google.com](https://admin.google.com) as a Super Admin. Go to **Security › Access and data control › API controls**, click **Manage Domain Wide Delegation** near the bottom of the page, then **Add new**. If Cimento's client ID is already listed, point to it and click **Edit** instead.
  </Step>

  <Step title="Authorize Cimento">
    In Cimento's **Service Account** step, click **Copy** next to **Client ID** and paste it into Google. Do the same with **OAuth scopes**; Google accepts them comma-separated. The three scopes are listed below. Click **Authorize**.
  </Step>

  <Step title="Test the connection">
    In Cimento's **Review** step, click **Test connection**. Cimento lists one user from your directory, acting as your administrator contact. Google can take up to 24 hours to apply a delegation change, so if the test fails straight away, try again later. Once the test passes, Cimento imports your directory immediately and then every 24 hours.
  </Step>
</Steps>

| Scope | Purpose |
| - | - |
| `https://www.googleapis.com/auth/admin.directory.user.readonly` | Reads user accounts so Cimento's employee list stays in sync. |
| `https://www.googleapis.com/auth/admin.directory.group.readonly` | Reads groups so Cimento can mirror them for targeting and reporting. |
| `https://www.googleapis.com/auth/admin.directory.group.member.readonly` | Reads group memberships so Cimento knows who belongs to which group. |

See [What Cimento imports from Google Workspace](/getting-started/employee-directory#what-cimento-imports-from-google-workspace) for which fields are used and what happens when someone leaves.

## Deliver phishing simulations

In Cimento this is **Google Workspace Email**. Cimento places each simulation straight into the employee's Gmail inbox through the Gmail API, so nothing crosses your mail gateway and there's nothing to allowlist.

<Steps>
  <Step title="Start setup in Cimento">
    Go to **Admin → Integrations → Phishing**, choose **Google Workspace Email** and click **Begin Setup**. Your organization can have one email provider active at a time.
  </Step>

  <Step title="Open domain-wide delegation">
    Sign in to [admin.google.com](https://admin.google.com) as a Super Admin. Go to **Security › Access and data control › API controls**, click **Manage Domain Wide Delegation**, then **Add new**. If Cimento's client ID is already listed because you imported your directory, point to it and click **Edit** instead.
  </Step>

  <Step title="Authorize Cimento">
    In Cimento's **Service Account** step, copy the **Client ID** and the **OAuth scopes** into Google, and click **Authorize**. If you're editing an existing entry, add these scopes after the ones already there.
  </Step>

  <Step title="Test the connection">
    In Cimento's **Review** step, click **Test connection**. Cimento reads the Gmail profile of your administrator contact using `gmail.readonly`. The test doesn't use the other scopes, so before your first campaign, point to Cimento's client ID in Google, click **View details**, and check that every scope is listed.
  </Step>
</Steps>

| Scope | Purpose |
| - | - |
| `https://www.googleapis.com/auth/gmail.insert` | Places simulations, and follow-up messages in multi-turn simulations, in the Inbox. |
| `https://www.googleapis.com/auth/gmail.readonly` | Checks whether a simulation was opened and looks for replies in the simulation's own thread. |
| `https://www.googleapis.com/auth/gmail.modify` | Not used by email delivery. Cimento's Gmail report add-on uses it. |

[Mailbox permissions](/phishing/mailbox-permissions#google-workspace) explains exactly what Cimento does with each scope, and what it never does.

## Revoke access

* **To remove one setup,** open **Manage Domain Wide Delegation**, point to Cimento's client ID, click **Edit**, and delete that setup's scopes.
* **To remove everything,** point to Cimento's client ID and click **Delete**. Google says apps that depend on it stop working immediately.
* **Disconnecting in Cimento** doesn't change anything in Google, so remove the delegation there too.