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

# Google Workspace setup

> Connect Google Workspace to Ravenna by creating a Google Cloud service account with domain-wide delegation and authorizing the required scopes.

<Info>Connect to Google Workspace using a service account with domain-wide delegation</Info>

This guide walks you through creating a Google Cloud service account and configuring domain-wide delegation to connect to your Google Workspace organization.

## Prerequisites

Before you begin, ensure you have:

* Google Workspace Super Admin access
* Google Cloud Platform project access (or ability to create one)
* Your Google Workspace primary domain

## Setup guide

### Create service account in Google Cloud

<Steps>
  <Step title="Access Google Cloud Console">
    Navigate to the [Google Cloud Console](https://console.cloud.google.com) and select or create a project for the integration
  </Step>

  <Step title="Enable required APIs">
    Enable the following APIs in your project:

    * Admin SDK API
    * Cloud Identity API
    * Group Settings API

    Navigate to **APIs & Services > Library** and search for each API to enable them
  </Step>

  <Step title="Create service account">
    1. Go to **IAM & Admin > Service Accounts**
    2. Click **Create Service Account**
    3. Enter a name (e.g., "Google Workspace Integration")
    4. Click **Create and Continue**
    5. Skip the optional steps and click **Done**
  </Step>

  <Step title="Create service account key">
    1. Click the newly created service account
    2. Go to the **Keys** tab
    3. Click **Add Key > Create new key**
    4. Select **JSON** format
    5. Click **Create** - the key file will download automatically

    <Warning>
      Store this JSON key file securely. You'll need it to configure the integration.
    </Warning>
  </Step>

  <Step title="Note the client ID">
    On the service account details page, copy the **Client ID** (also called "Unique ID"). You'll need this for domain-wide delegation.
  </Step>
</Steps>

### Configure domain-wide delegation

<Steps>
  <Step title="Access Google Workspace Admin Console">
    Navigate to [admin.google.com](https://admin.google.com) and sign in with your Super Admin account
  </Step>

  <Step title="Navigate to API controls">
    1. Go to **Security > Access and data control > API controls**
    2. Scroll to **Domain-wide delegation**
    3. Click **Manage Domain Wide Delegation**
  </Step>

  <Step title="Add new API client">
    1. Click **Add new**
    2. Enter the **Client ID** from your service account
    3. Add the following OAuth scopes (comma-separated):

    ```text Google OAuth Scopes icon="google" theme={"system"}
    https://www.googleapis.com/auth/admin.directory.user,
    https://www.googleapis.com/auth/admin.directory.user.security,
    https://www.googleapis.com/auth/admin.directory.group,
    https://www.googleapis.com/auth/admin.directory.group.member,
    https://www.googleapis.com/auth/cloud-platform,
    https://www.googleapis.com/auth/apps.groups.settings,
    https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly,
    https://www.googleapis.com/auth/admin.datatransfer,
    https://www.googleapis.com/auth/cloud-identity.groups
    ```

    <Note>
      The `admin.datatransfer` scope is optional and only required if you plan to use the [Transfer User Data](/integrations/google-workspace/workflows#transfer-user-data) workflow action for offboarding.
    </Note>

    <Note>
      The `cloud-identity.groups` scope is optional and only required if you plan to create Google security groups from workflows. See the [Enable security group creation](#enable-security-group-creation-optional) step below.
    </Note>

    4. Click **Authorize**
  </Step>

  <Step title="Verify delegation">
    Confirm the service account appears in the list of authorized API clients with all required scopes
  </Step>
</Steps>

### Add integration

<Steps>
  <Step title="Navigate to integrations">
    1. Go to **Settings > Integrations**
    2. Find **Google Workspace** in the Software Access section
  </Step>

  <Step title="Select Google Workspace">
    Click **Connect** on the Google Workspace integration card
  </Step>

  <Step title="Configure service account credentials">
    Provide the following information from your service account JSON key file:

    <Tip>Upload the JSON key file you recently downloaded from Google to auto-fill these fields. </Tip>

    <ParamField path="serviceAccountClientId" type="string" required>
      The unique 21-digit client ID for your service account (found in Google Cloud Console)
    </ParamField>

    <ParamField path="privateKey" type="string" required>
      The private key from your service account JSON key file (PEM format). Download from Google Cloud Console > IAM & Admin > Service Accounts
    </ParamField>

    <ParamField path="serviceAccountKeyId" type="string" required>
      The key ID for your service account key (found in Google Cloud Console > IAM & Admin > Service Accounts > Keys)
    </ParamField>

    <ParamField path="serviceAccountEmail" type="string" required>
      The email address from your service account JSON key file (`client_email` field)
    </ParamField>
  </Step>

  <Step title="Enter workspace details">
    Provide the following information:

    <ParamField path="primaryDomain" type="string" required>
      Your Google Workspace primary domain (e.g., `company.com`)
    </ParamField>

    <ParamField path="adminEmail" type="string" required>
      Email address of a Google Workspace admin user. Required for domain-wide delegation to access user and group data.

      <Note>
        This admin must have **Super Admin** role, or both **Groups Admin** and **User Management Admin** roles. See [Admin role requirements](#admin-role-requirements) for details.
      </Note>
    </ParamField>
  </Step>

  <Step title="Complete setup">
    Click **Connect** to complete the integration. This will:

    1. Validate the service account credentials
    2. Test API connectivity
    3. Begin initial sync of users, groups, and applications
  </Step>

  <Step title="Enable data transfer (optional)">
    If you plan to use the [Transfer User Data](/integrations/google-workspace/workflows#transfer-user-data) workflow action for offboarding:

    1. Go to **Org Settings > Google Workspace > Settings**
    2. In the settings modal, enable the **Enable User Data Transfer** toggle
    3. Save your changes

    <Note>
      This step also requires the `https://www.googleapis.com/auth/admin.datatransfer` scope configured in Domain Wide Delegation.
    </Note>
  </Step>

  <Step title="Enable security group creation (optional)">
    If you plan to create Google security groups from the **Create Group** workflow action:

    1. Ensure the Cloud Identity API is enabled in your Google Cloud project
    2. Authorize the `https://www.googleapis.com/auth/cloud-identity.groups` scope in Domain Wide Delegation
    3. Go to **Org Settings > Google Workspace > Settings**
    4. Enable the **Enable Security Group Creation** toggle
    5. Save your changes

    <Note>
      When this toggle is off, the Create Group action still works for standard groups. It only fails for inputs that request a security group label.
    </Note>
  </Step>

  <Step title="Enable multi-domain sync (optional)">
    If your Google Workspace account has multiple domains and you need to sync users and groups across all of them:

    1. Go to **Org Settings > Google Workspace > Settings**
    2. Enable the **Sync All Domains** toggle
    3. Save your changes

    <Note>
      See [Multi-domain sync](#multi-domain-sync) for details on default filtering behavior.
    </Note>
  </Step>
</Steps>

## User sync behavior

After setup, Ravenna syncs only active users from Google Workspace. Suspended and archived users are excluded from sync.

* If a user is suspended or archived in Google Workspace and does not exist in Ravenna, no record is created for them.
* If a previously synced user becomes suspended, their status is updated to `Suspended` in Ravenna on the next sync cycle. The Ravenna user record is preserved so existing tickets remain valid.
* If a previously synced user becomes archived, their status is updated to `Deprovisioned` in Ravenna on the next sync cycle. The Ravenna user record is preserved so existing tickets remain valid.

<Callout icon="link" color="#6B7280">
  Learn more about [suspending and restoring users](/integrations/google-workspace/workflows#suspend-user) with workflow actions. Restoring a user in Google Workspace syncs them back into Ravenna on the next cycle.
</Callout>

### Multi-domain sync

By default, Ravenna filters users and groups by your primary domain during sync. If your Google Workspace account includes secondary domains (e.g., `subsidiary.com` alongside `company.com`), users on those domains are not synced unless you enable **Sync All Domains** in the integration settings.

When enabled, Ravenna queries all users and groups across every domain in your Google Workspace account instead of filtering by the primary domain.

## Admin role requirements

The admin email user must have sufficient privileges to manage users and groups in your Google Workspace organization.

### Recommended roles

Use one of the following configurations:

* **Super Admin** role (has all required privileges), OR
* **Both** Groups Admin **AND** User Management Admin roles

### Required privileges

If creating a custom admin role, the following privileges are required:

<AccordionGroup>
  <Accordion title="Users privileges">
    | Privilege  | Sub-privilege         | Used For                               |
    | ---------- | --------------------- | -------------------------------------- |
    | **Create** | -                     | Creating new users                     |
    | **Read**   | -                     | Listing and syncing users              |
    | **Update** | Add/Remove Aliases    | Creating email aliases                 |
    |            | Force Password Change | Requiring password reset on next login |
    |            | Reset Password        | Resetting user passwords               |
    |            | Suspend Users         | Suspending and unsuspending users      |

    <Note>
      The full **Update** permission includes all sub-privileges. If creating a custom role, you need at minimum: Add/Remove Aliases, Force Password Change, Reset Password, and Suspend Users.
    </Note>
  </Accordion>

  <Accordion title="Security privileges">
    | Privilege                    | Used For                          |
    | ---------------------------- | --------------------------------- |
    | **Manage Security Settings** | Resetting MFA/2-Step Verification |
  </Accordion>

  <Accordion title="Groups privileges">
    | Privilege  | Used For                                         |
    | ---------- | ------------------------------------------------ |
    | **Read**   | Listing and syncing groups, viewing members      |
    | **Create** | Creating new groups                              |
    | **Update** | Adding/removing group members, updating settings |
    | **Delete** | Deleting groups                                  |
  </Accordion>
</AccordionGroup>

### Role scope

The admin role must apply to the **entire organization** (Customer scope) or cover all organizational units where users and groups will be managed.

<Warning>
  If Ravenna is configured with a delegated admin user (not a Super Admin), Ravenna will be unable to make updates to any users who have Super Admin privileges. This is a Google Workspace limitation where delegated admins cannot manage Super Admin users.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid credentials error">
    **Cause**: Service account key is invalid or expired.

    **Solution**:

    * Verify the JSON key file is correct and not corrupted
    * Ensure the service account still exists in Google Cloud
    * Create a new key if the current one is expired
  </Accordion>

  <Accordion title="Insufficient admin permissions error">
    **Error message**: `Not Authorized to access this resource/api`

    **Cause**: The admin email user lacks required admin roles or privileges.

    **Solution**:

    * Assign the **Super Admin** role to the admin user, OR
    * Assign both **Groups Admin** and **User Management Admin** roles
    * Ensure the role applies to the entire organization (Customer scope)
    * See [Admin role requirements](#admin-role-requirements) for detailed privilege requirements
  </Accordion>

  <Accordion title="Missing scopes or partial sync">
    **Cause**: Domain-wide delegation is configured with a subset of the required OAuth scopes.

    **Behavior**: Ravenna no longer blocks integration setup when some scopes are missing. The integration is created with the scopes you authorized, and any resource Ravenna can't read (users, groups, or applications) syncs as empty until the missing scope is added.

    **Solution**:

    * Verify all required OAuth scopes are authorized in Google Workspace Admin Console
    * Check that domain-wide delegation is enabled for the service account
    * Ensure the correct Client ID is used for delegation
    * After authorizing the missing scopes, trigger a resync from the integration page — no need to disconnect and reconnect
  </Accordion>

  <Accordion title="Domain not found error">
    **Cause**: Incorrect domain or domain not accessible

    **Solution**:

    * Verify the domain matches your Google Workspace primary domain
    * Ensure the domain is active and not suspended
    * Check for typos in the domain name
  </Accordion>

  <Accordion title="API not enabled error">
    **Cause**: Required APIs not enabled in Google Cloud project

    **Solution**:

    * Enable Admin SDK API in Google Cloud Console
    * Enable Cloud Identity API in Google Cloud Console
    * Enable Group Settings API in Google Cloud Console
    * Wait a few minutes for API enablement to propagate
  </Accordion>
</AccordionGroup>