Skip to main content

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.

Connect to Google Workspace using a service account with domain-wide delegation
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

1

Access Google Cloud Console

Navigate to the Google Cloud Console and select or create a project for the integration
2

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
3

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
4

Create service account key

  1. Click on 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
Store this JSON key file securely. You’ll need it to configure the integration.
5

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.

​
Configure domain-wide delegation

1

Access Google Workspace Admin Console

Navigate to admin.google.com and sign in with your Super Admin account
2

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
3

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):
Google OAuth Scopes
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
The admin.datatransfer scope is optional and only required if you plan to use the Transfer User Data workflow action for offboarding.
  1. Click Authorize
4

Verify delegation

Confirm the service account appears in the list of authorized API clients with all required scopes

​
Add integration

1

Navigate to integrations

  1. Go to Settings > Integrations
  2. Find Google Workspace in the Software Access section
2

Select Google Workspace

Click Connect on the Google Workspace integration card
3

Configure service account credentials

Provide the following information from your service account JSON key file:
Upload the JSON key file you recently downloaded from Google to auto-fill these fields.
​
serviceAccountClientId
string
required
The unique 21-digit client ID for your service account (found in Google Cloud Console)
​
privateKey
string
required
The private key from your service account JSON key file (PEM format). Download from Google Cloud Console > IAM & Admin > Service Accounts
​
serviceAccountKeyId
string
required
The key ID for your service account key (found in Google Cloud Console > IAM & Admin > Service Accounts > Keys)
​
serviceAccountEmail
string
required
The email address from your service account JSON key file (client_email field)
4

Enter workspace details

Provide the following information:
​
primaryDomain
string
required
Your Google Workspace primary domain (e.g., company.com)
​
adminEmail
string
required
Email address of a Google Workspace admin user. Required for domain-wide delegation to access user and group data.
This admin must have Super Admin role, or both Groups Admin and User Management Admin roles. See Admin role requirements for details.
5

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
6

Enable data transfer (optional)

If you plan to use the 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
This step also requires the https://www.googleapis.com/auth/admin.datatransfer scope configured in Domain Wide Delegation.
7

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
See Multi-domain sync for details on default filtering behavior.

​
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.
Learn more about suspending and restoring users with workflow actions. Restoring a user in Google Workspace syncs them back into Ravenna on the next cycle.

​
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. 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:
PrivilegeSub-privilegeUsed For
Create-Creating new users
Read-Listing and syncing users
UpdateAdd/Remove AliasesCreating email aliases
Force Password ChangeRequiring password reset on next login
Reset PasswordResetting user passwords
Suspend UsersSuspending and unsuspending users
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.
PrivilegeUsed For
Manage Security SettingsResetting MFA/2-Step Verification
PrivilegeUsed For
ReadListing and syncing groups, viewing members
CreateCreating new groups
UpdateAdding/removing group members, updating settings
DeleteDeleting groups

​
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.
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.

​
Troubleshooting

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
Error message: Not Authorized to access this resource/apiCause: 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 for detailed privilege requirements
Cause: Domain-wide delegation not configured or missing scopes.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
Cause: Incorrect domain or domain not accessibleSolution:
  • Verify the domain matches your Google Workspace primary domain
  • Ensure the domain is active and not suspended
  • Check for typos in the domain name
Cause: Required APIs not enabled in Google Cloud projectSolution:
  • 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