​
About Google Workspace

Google Workspace (formerly G Suite) provides email, calendar, drive and directory services for organisations. Connecting Google Workspace to Serval lets you automate common admin tasks, enforce security policies and modify user data directly inside Serval workflows.

​
What the Google Workspace integration enables

CapabilityDescription
Access ManagementCreate, update, and manage users and their permissions
Automation workflowsManage groups, and organizational data. Create aliases, manage settings, and more

​
Choose your connection method

We offer two different configuration mechanisms for Google Workspace:
  • Standard OAuth integration:
    • Simple integration process
    • Suitable for basic user and group management
    • No domain-wide delegation required
  • Service Account integration:
    • More manual configuration required
    • Full control over scopes and permissions
    • Required for advanced APIs (e.g., Gmail delegation APIs)
    • Enables domain-wide delegation
To get started, navigate to the “Apps” page and click “Connect to Google Workspace”: Image(10) Pn Select “Authorize with Google” for standard OAuth or “Use Service Account” for service account integration.

​
4. Service Account Integration Setup

​
Step 1: Create Google Cloud Project and Service Account

  1. Navigate to console.cloud.google.com and login
  2. Create a new project:
    • Click “Select Project” → “New Project”
    • Choose any name for your project
Image(12) Pn Image(13) Pn
  1. Create a service account:
    • Navigate to “Credentials” → “Create Credentials” → “Service Account”
    • Name your service account and create it (other fields optional)
Image(16) Pn

​
Step 2: Enable Required APIs

Critical: Enable the Admin SDK API in your Google Cloud project:
  1. Navigate to “APIs & Services” → “Library”
  2. Search for “Admin SDK API” and “Gmail API”
  3. Click “Enable” for both APIs
Note: API enablement takes 5-10 minutes to propagate. If you encounter 403 errors initially, wait and try again.

​
Step 3: Configure Service Account Permissions

Grant Serval permission to impersonate your service account:
  1. Go to your service account → “Permissions” tab → “Grant Access”
  2. Add principal: serval@serval-424322.iam.gserviceaccount.com
  3. Assign role: “Service Account Token Creator”
Image(17) Pn Image(18) Pn Note: If you encounter domain restriction errors, complete Step 5: Organization Policies first.

​
Step 4: Configure Domain-Wide Delegation

  1. Get your service account’s Client ID:
    • Go to your service account → “Details” page
    • Copy the “Client ID” (long numeric string, e.g., 116634191637610572786)
  2. Configure in Google Workspace Admin Console:
    • Navigate to admin.google.com → “Security” → “Access and data control” → “API controls” → “Manage Domain Wide Delegation”
    • Click “Add New”
    • Enter your service account’s Client ID
    • Add these scopes: 
      https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.group.member,https://www.googleapis.com/auth/gmail.settings.basic,https://www.googleapis.com/auth/gmail.settings.sharing,https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/cloud-platform
    • Click “Authorize”
Image(20) Pn Image(21) Pn Important: The https://www.googleapis.com/auth/cloud-platform scope is required for impersonation.

​
Step 5: Organization Policies (Optional)

Only complete this step if you received domain restriction errors in Step 3.
  1. Navigate to Google Cloud Console → Organization Policies
  2. Search for iam.allowedPolicyMemberDomains
  3. Select “Domain Restricted Sharing” → “Manage Policy”
  4. Select “Override Parent’s Policy” and “Merge with Parent”
  5. Click “Add a rule” → “Custom” → “Allow”
  6. Enter C04gvbkuc as the custom value
  7. Save the policy
Image(23) Pn Image(24) Pn Image(25) Pn If you don’t have Organization Policy access:
  • Request access from your Organization Administrator
  • Contact your Google Cloud Administrator
  • Use a different Google Cloud project where you have admin rights

​
5. Complete Integration Setup

After completing the service account setup:
  1. Return to Serval → “Apps” → “Available” → “Google Workspace” → “Connect”
  2. Enter the required information:
    • Google Workspace domain: Your organization’s domain (e.g., company.com)
    • Service Account email: Your service account’s email address
    • Default subject: An admin user in your domain (e.g., admin@company.com)
    • Scopes: The comma-separated list from Step 4
  3. Click “Save”
Your integration is now ready to use!

​
6. Troubleshooting

​
Common Setup Issues

If you encounter errors during setup, verify these configurations:
ComponentVerification
APIs EnabledGoogle Cloud Console → APIs & Services → Enabled APIs
Service Account PermissionsService Account → Permissions → Verify serval@serval-424322.iam.gserviceaccount.com has “Token Creator” role
Domain-Wide DelegationGoogle Workspace Admin Console → Security → API Controls → Verify Client ID is listed

​
Error Messages and Solutions

​
”impersonate: status code 401: unauthorized_client”

Missing: Service account permissions
Fix: Complete Step 3: Configure Service Account Permissions

​
”Admin SDK API has not been used in project [PROJECT_ID] before or it is disabled”

Missing: API enablement
Fix: Complete Step 2: Enable Required APIs

​
”Client is unauthorized to retrieve access tokens using this method”

Missing: Domain-wide delegation
Fix: Complete Step 4: Configure Domain-Wide Delegation

​
”Domain restricted sharing policy”

Missing: Organization policy configuration
Fix: Complete Step 5: Organization Policies

​
Getting Help

If you continue to experience issues:
  1. Verify all steps in the setup process are complete
  2. Wait 10-15 minutes for Google services to propagate changes
  3. Check that your default subject user has admin privileges in Google Workspace