> ## Documentation Index > Fetch the complete documentation index at: https://serval-hannah-docs-custom-access.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Google Workspace ## 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 | Capability | Description | | -------------------- | --------------------------------------------------------------------------------- | | Access Management | Create, update, and manage users and their permissions | | Automation workflows | Manage 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](https://developers.google.com/gmail/api/reference/rest/v1/users.settings.delegates/create)) * 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](http://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 3. 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 required APIs in your Google Cloud project: 1. Navigate to "APIs & Services" → "Library" 2. Search for and enable the following APIs: * **Admin SDK API** (required for user and group management) * **Gmail API** (required for Gmail operations) * **Google Drive API** (required for Drive file operations) * **Google Sheets API** (required for Sheets operations) 3. Click "Enable" for each API **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](#step-5-organization-policies-optional) 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](https://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 the required scopes based on your needs: ```text All Scopes (Recommended) theme={null} 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/drive https://www.googleapis.com/auth/drive.metadata https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/spreadsheets.readonly https://www.googleapis.com/auth/cloud-platform ``` ```text Minimal Directory-Only Scopes theme={null} 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/cloud-platform ``` **All scopes (comma-separated for easy copy/paste):** ``` 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/drive,https://www.googleapis.com/auth/drive.metadata,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/spreadsheets.readonly,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. **Scope capabilities:** **Admin Directory:** * `https://www.googleapis.com/auth/admin.directory.user` - Manage users in your domain ([@https://www.googleapis.com/auth/admin.directory.user](https://www.googleapis.com/auth/admin.directory.user)) * `https://www.googleapis.com/auth/admin.directory.group` - Manage groups in your domain ([@https://www.googleapis.com/auth/admin.directory.group](https://www.googleapis.com/auth/admin.directory.group)) * `https://www.googleapis.com/auth/admin.directory.group.member` - Manage group memberships ([@https://www.googleapis.com/auth/admin.directory.group.member](https://www.googleapis.com/auth/admin.directory.group.member)) **Gmail:** * `https://www.googleapis.com/auth/gmail.settings.basic` - Manage basic Gmail settings ([@https://www.googleapis.com/auth/gmail.settings.basic](https://www.googleapis.com/auth/gmail.settings.basic)) * `https://www.googleapis.com/auth/gmail.settings.sharing` - Manage Gmail delegation settings ([@https://www.googleapis.com/auth/gmail.settings.sharing](https://www.googleapis.com/auth/gmail.settings.sharing)) **Calendar:** * `https://www.googleapis.com/auth/calendar` - Full access to Google Calendar ([@https://www.googleapis.com/auth/calendar](https://www.googleapis.com/auth/calendar)) **Drive:** * `https://www.googleapis.com/auth/drive` - Full access to Google Drive files ([@https://www.googleapis.com/auth/drive](https://www.googleapis.com/auth/drive)) * `https://www.googleapis.com/auth/drive.metadata` - Access to file metadata without file content ([@https://www.googleapis.com/auth/drive.metadata](https://www.googleapis.com/auth/drive.metadata)) **Sheets:** * `https://www.googleapis.com/auth/spreadsheets` - Full access to Google Sheets ([@https://www.googleapis.com/auth/spreadsheets](https://www.googleapis.com/auth/spreadsheets)) ### 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](https://console.cloud.google.com/iam-admin/orgpolicies/list) 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: | Component | Verification | | ------------------------------- | -------------------------------------------------------------------------------------------------------------- | | **APIs Enabled** | Google Cloud Console → APIs & Services → Enabled APIs | | **Service Account Permissions** | Service Account → Permissions → Verify `serval@serval-424322.iam.gserviceaccount.com` has "Token Creator" role | | **Domain-Wide Delegation** | Google 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](#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](#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](#step-4-configure-domain-wide-delegation) #### "Domain restricted sharing policy" **Missing:** Organization policy configuration\ **Fix:** Complete [Step 5: Organization Policies](#step-5-organization-policies-optional) ### 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