Setup - Ravenna Docs

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

Access Google Cloud Console

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

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

Create service account

Go to IAM & Admin > Service Accounts
Click Create Service Account
Enter a name (e.g., “Google Workspace Integration”)
Click Create and Continue
Skip the optional steps and click Done

Create service account key

Click on the newly created service account
Go to the Keys tab
Click Add Key > Create new key
Select JSON format
Click Create - the key file will download automatically

Store this JSON key file securely. You’ll need it to configure the integration.

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

Access Google Workspace Admin Console

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

Navigate to API controls

Go to Security > Access and data control > API controls
Scroll to Domain-wide delegation
Click Manage Domain Wide Delegation

Add new API client

Click Add new
Enter the Client ID from your service account
Add the following OAuth scopes (comma-separated):

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

Click Authorize

Verify delegation

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

Add integration

Navigate to integrations

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

Select Google Workspace

Click Connect on the Google Workspace integration card

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)

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.

Complete setup

Click Connect to complete the integration. This will:

Validate the service account credentials
Test API connectivity
Begin initial sync of users, groups, and applications

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:

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

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.

Security privileges

Privilege	Used For
Manage Security Settings	Resetting MFA/2-Step Verification

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

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

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

Insufficient admin permissions error

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

Insufficient permissions error

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

Domain not found error

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

API not enabled error

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

Features

Once connected, you can use Google Workspace actions in workflows:

Google Workspace Actions

Manage user group memberships, create groups, check group membership, and reset MFA/passwords

​Prerequisites

​Setup guide

​Create service account in Google Cloud

​Configure domain-wide delegation

​Add integration

​Admin role requirements

​Recommended roles

​Required privileges

​Role scope

​Troubleshooting

​Features

Google Workspace Actions

Prerequisites

Setup guide

Create service account in Google Cloud

Configure domain-wide delegation

Add integration

Admin role requirements

Recommended roles

Required privileges

Role scope

Troubleshooting

Features