From 0095c2d045fa2a45540a31a33e516e9ec07e5736 Mon Sep 17 00:00:00 2001 From: leet-c1 <264029741+leet-c1@users.noreply.github.com> Date: Fri, 14 Aug 2026 17:09:50 +0000 Subject: [PATCH 1/4] docs(google-workspace): add gcloud commands and service account key permissions Restructure the Google Workspace connector setup guide to match the Google Cloud project setup guide used by the MCP server docs. - Add a "Before you begin" section listing the required Google Cloud, Workspace, and C1 roles up front - Add gcloud equivalents for every console procedure: project creation, API enablement, service account creation, key creation and listing, and retrieving the service account unique ID - Document service account key creation requirements: the iam.serviceAccountKeys.create permission and the Service Account Key Admin role, plus the iam.disableServiceAccountKeyCreation org policy that is enforced by default for organizations created on or after May 3, 2024, with the check and project-level exception commands - Note iam.serviceAccountKeyExpiryHours, which silently breaks the connector when a capped key lifetime elapses - Clarify that the Admin SDK API covers Directory, Reports, and Data Transfer, so there is no separate Data Transfer API to enable - List API service IDs and promote Cloud Identity to a required API - Convert the scope purpose lists into read-only and read/write tabs with tables - Replace the Editor role grant with no project role, since the connector's access comes from domain-wide delegation rather than Cloud IAM - Add a symptom/cause/fix troubleshooting table - Remove a stale "primary domain from Step 6" cross-reference Co-Authored-By: Claude Opus 5 --- baton/google-workspace.mdx | 372 ++++++++++++++++++++++++++----------- 1 file changed, 261 insertions(+), 111 deletions(-) diff --git a/baton/google-workspace.mdx b/baton/google-workspace.mdx index ab067586..82f7baf9 100644 --- a/baton/google-workspace.mdx +++ b/baton/google-workspace.mdx @@ -42,15 +42,43 @@ Connector actions are custom capabilities that extend C1 automations with app-sp | modify_group_settings | `group_key` (string, required)
`allow_external_members` (boolean, optional)
`allow_web_posting` (boolean, optional)
`who_can_post_message` (string, optional)
`message_moderation_level` (string, optional) | Update settings for an existing Google Group | | update_user_manager | `user_id` (string, required)
`manager_email` (string, required) | Updates the manager relation for a user in Google Workspace. Updates the 'manager' entry in the user's Relations field | -## Gather Google Workspace credentials +## Before you begin -Configuring the connector requires you to pass in credentials generated in Google Workspace. Gather these credentials before you move on. +This connector authenticates with a **service account and domain-wide delegation**, not per-user OAuth. Every call reaches Google as one service account impersonating a Workspace super admin. + +You need: + +- **Google Cloud console access** to a project where you can enable APIs and create a service account: project **Owner**, or **Editor** plus the ability to manage service accounts. +- **Permission to create a service account key** (`iam.serviceAccountKeys.create`), granted by the **Service Account Key Admin** role (`roles/iam.serviceAccountKeyAdmin`). See [Allow service account key creation](#allow-service-account-key-creation). +- **A Google Workspace super admin** to authorize domain-wide delegation and to act as the impersonated administrator. +- Either the **Connector Administrator** or **Super Administrator** role in C1. + + +**Check your organization's key policy first.** Google organizations created on or after May 3, 2024 block service account key creation by default. The connector requires a JSON key, so confirm you can create one before you start. See [Allow service account key creation](#allow-service-account-key-creation). + + +### What the Google Cloud project provides + +| What | Why it matters | +| :--- | :--- | +| **Enabled APIs** | The connector calls the Admin SDK, and optionally the Cloud Identity and Groups Settings APIs. Each must be enabled in your project. | +| **Service account** | The single identity C1 authenticates as. It needs no project IAM role. | +| **JSON key** | The credential you upload to C1. Creating one requires the Service Account Key Admin role and an organization policy that permits key creation. | +| **Domain-wide delegation** | The Workspace-side grant that authorizes the service account's scopes. This is what actually lets the connector read and write directory data. | + + +Domain-wide delegation is configured in the Google Admin console, not in Google Cloud. Granting the service account a Google Cloud IAM role does not give it access to Workspace data, and no project role is required for this connector. + + +## Set up the Google Cloud project A user with the **Super Admin** role in Google Workspace must perform this task. -### Create a new project +Each section below gives the Google Cloud console steps and the equivalent `gcloud` commands. Use whichever you prefer. To use the CLI, [install the gcloud CLI](https://cloud.google.com/sdk/docs/install) and run `gcloud auth login` first. + +### Create or select a project @@ -62,7 +90,7 @@ In the toolbar, open the project select dropdown and click **NEW PROJECT**. Create a new project for your organization: - - **Project Name**: Choose a names, such as "C1 Integration" + - **Project Name**: Choose a name, such as "C1 Integration" - **Organization/Location**: Choose the appropriate Organization/Location @@ -70,31 +98,73 @@ Create a new project for your organization: After the project is created, make sure the correct project is selected in the dropdown in the toolbar at the top of the page. -### Enable the API + +From the command line: + +```bash +gcloud projects create YOUR_PROJECT_ID \ + --name="C1 Integration" \ + --organization=YOUR_ORG_ID +``` + +```bash +gcloud config set project YOUR_PROJECT_ID +``` + + +The Workspace APIs this connector uses don't require a billing account. + + +### Enable the APIs + +Enable the Admin SDK API, plus the Cloud Identity API and, if you use group settings, the Groups Settings API. + +| API | Service ID | Required? | Used for | +| :--- | :--- | :--- | :--- | +| Admin SDK API | `admin.googleapis.com` | Required | Syncing users, groups, roles, and audit events, and running provisioning and data transfer actions | +| Cloud Identity API | `cloudidentity.googleapis.com` | Required | Resolving SAML app IDs to stable identifiers when syncing enterprise applications | +| Groups Settings API | `groupssettings.googleapis.com` | Optional | The `modify_group_settings` connector action | + + +The Admin SDK API covers the Directory, Reports, and Data Transfer APIs. Enabling it once is enough. There is no separate Data Transfer API to enable, even though the connector requests the `admin.datatransfer` scope. + -In the navigation menu, navigate to > **APIs & Services** > **Library**. - - -Search for and select the **Admin SDK API**. +In the navigation menu, navigate to **APIs & Services** > **Library**. -Click **Enable**. +Search for and select the **Admin SDK API**, then click **Enable**. - -**Optional.** If you want to use the group settings connector action, you must also search for, select, and enable the **Groups Settings API**. +Repeat for the **Cloud Identity API**. -You must also search for, select, and enable the **Cloud Identity API** (used for resolving SAML app IDs to stable identifiers). +**Optional.** If you want to use the group settings connector action, repeat for the **Groups Settings API**. + +From the command line: + +```bash +gcloud services enable \ + admin.googleapis.com \ + cloudidentity.googleapis.com \ + groupssettings.googleapis.com \ + --project=YOUR_PROJECT_ID +``` + +To confirm which APIs are enabled on the project: + +```bash +gcloud services list --enabled --project=YOUR_PROJECT_ID +``` + ### Create a service account -In the navigation menu, navigate to > **APIs & Services** > **Credentials**. +In the navigation menu, navigate to **APIs & Services** > **Credentials**. Select **CREATE CREDENTIALS** > **Service Account**. @@ -108,7 +178,7 @@ Under **Service account details**, fill in the following: -Under **Grant this service account access to a project**, grant the **Editor** role. +Under **Grant this service account access to a project**, click **CONTINUE** without selecting a role. The connector's access comes from domain-wide delegation, so no project role is required. Leave **Grant users access to this service account** blank. @@ -118,14 +188,95 @@ Click **DONE**. -### Get credentials +From the command line: + +```bash +gcloud iam service-accounts create c1-integration \ + --project=YOUR_PROJECT_ID \ + --display-name="C1 Integration" \ + --description="Service account for C1 Google Workspace Integration" +``` + + +Earlier versions of this guide granted the service account the **Editor** role. That role is not needed and grants broad access to your Google Cloud project. If you already granted it, you can safely remove it. + + +### Allow service account key creation + +The connector authenticates with a JSON key, so your organization must permit key creation on this service account. + +The `constraints/iam.disableServiceAccountKeyCreation` organization policy blocks key creation. **Google enforces this policy by default for organizations created on or after May 3, 2024**, so new organizations hit it unless an administrator grants an exception. + +If the policy blocks you, key creation fails with: + +```text +ERROR: (gcloud.iam.service-accounts.keys.create) FAILED_PRECONDITION: Key creation +is not allowed on this service account. +``` + +In the console, the **ADD KEY** option is unavailable and Google reports that service account key creation is disabled. + +**Permissions to check:** + +| Requirement | Details | +| :--- | :--- | +| IAM permission | `iam.serviceAccountKeys.create`, granted by the **Service Account Key Admin** role (`roles/iam.serviceAccountKeyAdmin`). The basic **Editor** role also includes it. | +| Organization policy | `constraints/iam.disableServiceAccountKeyCreation` must not be enforced on the project. A managed equivalent, `iam.managed.disableServiceAccountKeyCreation`, controls the same behavior. | +| Related policies | `constraints/iam.serviceAccountKeyExpiryHours` caps how long new keys stay valid. If your organization sets it, plan to rotate the key in C1 before it expires. | + +Grant the key admin role to whoever creates the key: + +```bash +gcloud iam service-accounts add-iam-policy-binding \ + c1-integration@YOUR_PROJECT_ID.iam.gserviceaccount.com \ + --member="user:admin@yourdomain.com" \ + --role="roles/iam.serviceAccountKeyAdmin" \ + --project=YOUR_PROJECT_ID +``` + +Check whether the organization policy is enforced on your project: + +```bash +gcloud org-policies describe iam.disableServiceAccountKeyCreation \ + --project=YOUR_PROJECT_ID \ + --effective +``` + +If it is enforced, a user with the **Organization Policy Administrator** role (`roles/orgpolicy.policyAdmin`) can add a project-level exception. Save this as `policy.yaml`: + +```yaml +name: projects/YOUR_PROJECT_ID/policies/iam.disableServiceAccountKeyCreation +spec: + rules: + - enforce: false +``` + +Then apply it: + +```bash +gcloud org-policies set-policy policy.yaml +``` + + +This exception applies only to the project you name. Enforcement elsewhere in your organization is unchanged. If your organization manages exceptions with tags rather than per-project policies, see Google's [Organization policies and tags](https://cloud.google.com/resource-manager/docs/organization-policy/tags-organization-policy) documentation. + + + +Google recommends against long-lived service account keys and prefers Workload Identity Federation where it's available. This connector requires a JSON key, so treat it as a sensitive credential: store it in a secrets manager, never commit it to source control, and rotate it on a schedule. See Google's [best practices for managing service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys). + + +### Create the key and get the unique ID Navigate back to **APIs & Services** > **Credentials** and select the service account you just created. -Click the service account's email address. Locate and save the **Unique ID**. +Click the service account's email address. Locate and save the **Unique ID**, a numeric string such as `108123456789012345678`. The service account's details page also shows this value as the **OAuth 2 Client ID**. + + + Do not confuse the Unique ID with the service account's email address. Domain-wide delegation requires the numeric ID. + On the **Service account details** page, click **KEYS**. @@ -137,11 +288,35 @@ Click **ADD KEY** > **Create new key**. Choose **JSON** and click **CREATE**. -Keep the downloaded file somewhere safe. +Keep the downloaded file somewhere safe. Google does not let you download it again. - + + +From the command line: + +```bash +gcloud iam service-accounts keys create c1-credentials.json \ + --iam-account=c1-integration@YOUR_PROJECT_ID.iam.gserviceaccount.com +``` + +Retrieve the numeric unique ID you'll use for domain-wide delegation: + +```bash +gcloud iam service-accounts describe \ + c1-integration@YOUR_PROJECT_ID.iam.gserviceaccount.com \ + --format='value(uniqueId)' +``` + +To review the keys that exist on the service account: + +```bash +gcloud iam service-accounts keys list \ + --iam-account=c1-integration@YOUR_PROJECT_ID.iam.gserviceaccount.com +``` + +## Grant domain-wide delegation in Google Workspace -### Add the service account to Google Workspace +Domain-wide delegation authorizes the service account to call Workspace APIs on behalf of your organization. Configure it in the Google Admin console. @@ -156,96 +331,74 @@ Click **MANAGE DOMAIN WIDE DELEGATION**. Click **Add new** and fill out the form: - - **Client ID**: The service account's unique ID - - **OAuth Scopes**: Copy and paste in the relevant scopes - - Use the following scopes to give C1 **READ** access (for syncing access data): - - ```bash - https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.reports.audit.readonly, https://www.googleapis.com/auth/admin.directory.user.security, https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly - ``` - - Here's an explanation of each scope's purpose: - - - Scope: https://www.googleapis.com/auth/admin.directory.domain.readonly
- Purpose: To identify the primary domain of the Google Workspace account. - - - Scope: https://www.googleapis.com/auth/admin.directory.group.readonly
- Purpose: To read and sync Google Groups. - - - Scope: https://www.googleapis.com/auth/admin.directory.group.member.readonly
- Purpose: To read and sync the members of each group. - - - Scope: https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly
- Purpose: To read and sync roles and their assignments. - - - Scope: https://www.googleapis.com/auth/admin.directory.user.readonly
- Purpose: To read and sync users. - - - Scope: https://www.googleapis.com/auth/admin.reports.audit.readonly
- Purpose: To sync usage events and admin events (used in conjunction with incremental sync). - - - Scope: https://www.googleapis.com/auth/admin.directory.user.security
- Purpose: To discover OAuth apps via per-user token listing. - - - Scope: https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly
- Purpose: (Optional) To resolve SAML app IDs to stable identifiers. Without it, SAML app IDs fall back to display names. - - Use the following scopes to give C1 **READ/WRITE** access (for syncing access data and provisioning access): - - ```bash - https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.group.member, https://www.googleapis.com/auth/admin.directory.rolemanagement, https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.reports.audit.readonly, https://www.googleapis.com/auth/admin.datatransfer, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.user.security, https://www.googleapis.com/auth/apps.groups.settings, https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly - ``` - - Here's an explanation of each scope's purpose: + - **Client ID**: The service account's Unique ID + - **OAuth Scopes**: Copy and paste in the relevant scopes from [OAuth scopes](#oauth-scopes) below + + +Click **AUTHORIZE**. + + - - Scope: https://www.googleapis.com/auth/admin.directory.domain.readonly
- Purpose: To identify the primary domain of the Google Workspace account. +### OAuth scopes - - Scope: https://www.googleapis.com/auth/admin.directory.group.readonly
- Purpose: To read and sync Google Groups. +Choose one of the two sets below. Read-only access lets C1 sync access data. Read/write access lets C1 sync access data and provision access. - - Scope: https://www.googleapis.com/auth/admin.directory.group.member
- Purpose: (Write) To manage group memberships (add or remove users from groups). + + +Paste this comma-separated list into the **OAuth Scopes** field: - - Scope: https://www.googleapis.com/auth/admin.directory.rolemanagement
- Purpose: (Write) To manage role assignments (grant or revoke roles). +```bash +https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.reports.audit.readonly, https://www.googleapis.com/auth/admin.directory.user.security, https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly +``` - - Scope: https://www.googleapis.com/auth/admin.directory.user
- Purpose: (Write) To provision/deprovision accounts. +| Scope | Purpose | +| :--- | :--- | +| `admin.directory.domain.readonly` | Identify the primary domain of the Google Workspace account | +| `admin.directory.group.readonly` | Read and sync Google Groups | +| `admin.directory.group.member.readonly` | Read and sync the members of each group | +| `admin.directory.rolemanagement.readonly` | Read and sync roles and their assignments | +| `admin.directory.user.readonly` | Read and sync users | +| `admin.reports.audit.readonly` | Sync usage events and admin events, used with incremental sync | +| `admin.directory.user.security` | Discover OAuth apps through per-user token listing | +| `cloud-identity.inboundsso.readonly` | Optional. Resolve SAML app IDs to stable identifiers. Without it, SAML app IDs fall back to display names | + - - Scope: https://www.googleapis.com/auth/admin.reports.audit.readonly
- Purpose: To sync usage events and admin events (used in conjunction with continuous sync). + +Paste this comma-separated list into the **OAuth Scopes** field: - - Scope: https://www.googleapis.com/auth/admin.datatransfer
- Purpose: (Write) To transfer user data between Google accounts. +```bash +https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.group.member, https://www.googleapis.com/auth/admin.directory.rolemanagement, https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.reports.audit.readonly, https://www.googleapis.com/auth/admin.datatransfer, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.user.security, https://www.googleapis.com/auth/apps.groups.settings, https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly +``` - - Scope: https://www.googleapis.com/auth/admin.directory.group
- Purpose: (Write) To provision groups. +| Scope | Purpose | +| :--- | :--- | +| `admin.directory.domain.readonly` | Identify the primary domain of the Google Workspace account | +| `admin.directory.group.readonly` | Read and sync Google Groups | +| `admin.directory.group.member` | Write. Manage group memberships, adding or removing users from groups | +| `admin.directory.rolemanagement` | Write. Manage role assignments, granting or revoking roles | +| `admin.directory.user` | Write. Provision and deprovision accounts | +| `admin.reports.audit.readonly` | Sync usage events and admin events, used with continuous sync | +| `admin.datatransfer` | Write. Transfer user data between Google accounts | +| `admin.directory.group` | Write. Provision groups | +| `admin.directory.user.security` | Write. Discover OAuth apps and run actions that remove a user's access, such as sign out and deleting auth tokens and app passwords | +| `apps.groups.settings` | Write. Edit group settings. Requires the Groups Settings API | +| `cloud-identity.inboundsso.readonly` | Optional. Resolve SAML app IDs to stable identifiers. Without it, SAML app IDs fall back to display names | + + - - Scope: https://www.googleapis.com/auth/admin.directory.user.security
- Purpose: (Write) To discover OAuth apps and run actions for removing a user's access (sign out, delete auth tokens and app passwords). + +The write scopes let C1 provision and deprovision access. **If you don't want C1 to perform these tasks, use the read-only scope set.** + - - Scope: https://www.googleapis.com/auth/apps.groups.settings
- Purpose: (Write) To edit group settings. +### Find your customer ID and primary domain - - Scope: https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly
- Purpose: (Optional) To resolve SAML app IDs to stable identifiers. Without it, SAML app IDs fall back to display names. - - -Click **AUTHORIZE**. - + -In the navigation menu, select **Account > Account Settings**. +In the Google Admin console, select **Account** > **Account Settings**. Copy the **Customer ID** from this page. - - -### Locate your primary domain - - In the navigation panel on the left, click **Account** > **Domains**. @@ -254,7 +407,7 @@ Click **Manage Domains**. Locate and copy the domain labeled as the **Primary Do -**Done.** Next, move on to the connector configuration instructions. +**Done.** Next, move on to the connector configuration instructions. ## Configure the Google Workspace connector @@ -299,10 +452,10 @@ Find the **Settings** area of the page and click **Edit**. In the **Customer ID** field, enter the Google Workspace customer ID. -**Optional.** If you want to limit which domains C1 syncs, in the **Domain** field, enter the primary domain from Step 6. If you leave this field blank, C1 will sync all available domains. +**Optional.** If you want to limit which domains C1 syncs, in the **Domain** field, enter your primary domain. If you leave this field blank, C1 will sync all available domains. -In the **Administrator email** field, enter the email address associated with your domain or a super admin. +In the **Administrator email** field, enter the email address of a Google Workspace super admin. The service account impersonates this user. In the **Credentials (JSON)** area, click **Choose file** and upload the file. @@ -445,6 +598,15 @@ If Google Workspace is your company's identity provider (meaning that it is used ## Troubleshooting the Google Workspace integration +| Symptom | Cause | Fix | +| :--- | :--- | :--- | +| `FAILED_PRECONDITION: Key creation is not allowed on this service account` | The `iam.disableServiceAccountKeyCreation` organization policy is enforced, or you lack the Service Account Key Admin role. | See [Allow service account key creation](#allow-service-account-key-creation). | +| `Error 403: Request had insufficient authentication scopes` / `ACCESS_TOKEN_SCOPE_INSUFFICIENT` | The domain-wide delegation grant is missing scopes the connector needs. | Remove and re-add the API client with the full scope set. See below. | +| `unauthorized_client` when the connector authenticates | The Client ID in domain-wide delegation doesn't match the service account's Unique ID, or the requested scopes aren't authorized. | Confirm you entered the numeric **Unique ID**, not the service account email, and that the scope list matches exactly. | +| `SERVICE_DISABLED` or "API has not been used in project ... before or it is disabled" | The connector's API isn't enabled in the project. | Enable it. See [Enable the APIs](#enable-the-apis). | +| Authentication succeeds but the sync returns no users or `Not Authorized to access this resource/api` | The **Administrator email** isn't a super admin, or the **Customer ID** is wrong. | Confirm both values. See [Find your customer ID and primary domain](#find-your-customer-id-and-primary-domain). | +| The connector worked and then stopped authenticating | The service account key expired under `constraints/iam.serviceAccountKeyExpiryHours`, or someone deleted it. | Create a new key and upload it to the connector. | + ### When adding permissions to my Google Workspace API Client permissions I get authorization errors **Example error:** @@ -454,6 +616,7 @@ If Google Workspace is your company's identity provider (meaning that it is used **To resolve this issue:** Remove the Google Workspace API Client, then re-add with the correct permissions. + Copy the Client ID. @@ -465,19 +628,6 @@ Delete the API Client. Add a new Client ID. -Re-add the relevant scopes: - - Read-only - - ```bash - https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly, https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.reports.audit.readonly, https://www.googleapis.com/auth/admin.directory.user.security, https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly - ``` - - Read/Write - - ```bash - https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.group.member, https://www.googleapis.com/auth/admin.directory.rolemanagement, https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.reports.audit.readonly, https://www.googleapis.com/auth/admin.datatransfer, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.user.security, https://www.googleapis.com/auth/apps.groups.settings, https://www.googleapis.com/auth/cloud-identity.inboundsso.readonly - ``` +Re-add the relevant scopes from [OAuth scopes](#oauth-scopes). - From 8e94a27ec29fc9a0027b2972d4d471a87aaf65b9 Mon Sep 17 00:00:00 2001 From: leet-c1 <264029741+leet-c1@users.noreply.github.com> Date: Fri, 14 Aug 2026 18:23:45 +0000 Subject: [PATCH 2/4] docs(google-workspace): document using the connector as the C1 directory The page explained how to connect the connector but never how to make Google Workspace the directory C1 creates users from, which is the most common reason to set it up. - Add a "Set Google Workspace as your C1 directory" section covering the Directory > Directory sources designation flow, including that an app is selectable only after its first sync completes - Link to it from What's next - Note that a directory-only deployment needs neither the read/write scopes nor any Google Cloud IAM role - Add a tip in the OAuth scopes section that read-only is sufficient when C1 is not provisioning access Co-Authored-By: Claude Opus 5 --- baton/google-workspace.mdx | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/baton/google-workspace.mdx b/baton/google-workspace.mdx index 82f7baf9..5843c362 100644 --- a/baton/google-workspace.mdx +++ b/baton/google-workspace.mdx @@ -343,6 +343,10 @@ Click **AUTHORIZE**. Choose one of the two sets below. Read-only access lets C1 sync access data. Read/write access lets C1 sync access data and provision access. + +If you're using Google Workspace as your C1 directory and don't want C1 provisioning access, the read-only set is all you need. It syncs users, groups, and roles, and it cannot modify anything in Workspace. + + Paste this comma-separated list into the **OAuth Scopes** field: @@ -594,8 +598,41 @@ Check that the connector data uploaded correctly. In C1, click **Apps**. On the ### What's next? +If Google Workspace holds a record for everyone at your company, designate it as your directory so C1 creates user accounts from it. See [Set Google Workspace as your C1 directory](#set-google-workspace-as-your-c1-directory). + If Google Workspace is your company's identity provider (meaning that it is used to SSO into other software), the integration sync will automatically create applications in C1 for all of your SCIMed software. Before you move on, review the [Create applications](/product/admin/applications) page for important information about how to set up integrations with the SCIMed apps. +## Set Google Workspace as your C1 directory + +If Google Workspace is your source of truth for who works at your company, designate the connector's app as your [directory](/product/admin/directory). C1 then creates a C1 user for each Workspace account it syncs, and accounts from your other connectors attach to those users. + + +Importing users and groups doesn't require provisioning. If all you want is a directory and access reviews, the read-only scope set in [OAuth scopes](#oauth-scopes) is sufficient, and the service account still needs no Google Cloud IAM role. + + + + +Wait for the connector's first sync to finish. An app becomes available to select only after it has synced at least once. + + +In C1, navigate to **Directory** > **Directory sources**. + + +On the **Directories** tab, click **Add directory data source**. + + +Select the app your Google Workspace connector is attached to. + + +**Optional.** [Limit which accounts will be pulled into C1](/product/admin/directory#optional-limit-which-accounts-will-be-pulled-into-c1) or [configure merge matching](/product/admin/directory#configure-merge-matching). You can change both later. + + +Click **Create directory**. + + + +For how directory accounts become C1 users, and how accounts from non-directory apps find an owner, see [Connect a directory](/product/admin/directory). + ## Troubleshooting the Google Workspace integration | Symptom | Cause | Fix | From e7847c204a9331611d8bcfe7f1643359be22ce9f Mon Sep 17 00:00:00 2001 From: leet-c1 <264029741+leet-c1@users.noreply.github.com> Date: Fri, 14 Aug 2026 18:25:28 +0000 Subject: [PATCH 3/4] docs(google-workspace): resolve inconsistencies across the page Reviewed the page as a whole rather than section by section, which surfaced several conflicts introduced or left behind by earlier edits. - Fix a contradiction: the project overview called the Cloud Identity API optional while the API table listed it as required - Correct the Google Cloud sections, which asked for a Google Workspace Super Admin. Those steps need Google Cloud permissions; the Workspace super admin is required only for domain-wide delegation - Merge duplicated read-only scope guidance into the existing warning instead of a second callout saying the same thing - Reorder the closing sections so the directory step precedes What's next, removing a forward reference, and promote What's next to a heading level that no longer nests it under connector configuration - Replace a vague "See below" in the troubleshooting table with a link Co-Authored-By: Claude Opus 5 --- baton/google-workspace.mdx | 26 +++++++++----------------- 1 file changed, 9 insertions(+), 17 deletions(-) diff --git a/baton/google-workspace.mdx b/baton/google-workspace.mdx index 5843c362..819f9ab5 100644 --- a/baton/google-workspace.mdx +++ b/baton/google-workspace.mdx @@ -61,7 +61,7 @@ You need: | What | Why it matters | | :--- | :--- | -| **Enabled APIs** | The connector calls the Admin SDK, and optionally the Cloud Identity and Groups Settings APIs. Each must be enabled in your project. | +| **Enabled APIs** | The connector calls the Admin SDK and Cloud Identity APIs, plus the Groups Settings API if you use group settings. Each must be enabled in your project. | | **Service account** | The single identity C1 authenticates as. It needs no project IAM role. | | **JSON key** | The credential you upload to C1. Creating one requires the Service Account Key Admin role and an organization policy that permits key creation. | | **Domain-wide delegation** | The Workspace-side grant that authorizes the service account's scopes. This is what actually lets the connector read and write directory data. | @@ -72,9 +72,7 @@ Domain-wide delegation is configured in the Google Admin console, not in Google ## Set up the Google Cloud project - -A user with the **Super Admin** role in Google Workspace must perform this task. - +This part happens entirely in Google Cloud and needs the Google Cloud permissions listed in [Before you begin](#before-you-begin). The Workspace super admin isn't needed until [Grant domain-wide delegation in Google Workspace](#grant-domain-wide-delegation-in-google-workspace). Each section below gives the Google Cloud console steps and the equivalent `gcloud` commands. Use whichever you prefer. To use the CLI, [install the gcloud CLI](https://cloud.google.com/sdk/docs/install) and run `gcloud auth login` first. @@ -82,7 +80,7 @@ Each section below gives the Google Cloud console steps and the equivalent `gclo -As a Google Workspace Super Admin, sign in to [https://console.cloud.google.com](https://console.cloud.google.com/). +Sign in to [https://console.cloud.google.com](https://console.cloud.google.com/) with an account that can create projects, enable APIs, and manage service accounts. In the toolbar, open the project select dropdown and click **NEW PROJECT**. @@ -343,10 +341,6 @@ Click **AUTHORIZE**. Choose one of the two sets below. Read-only access lets C1 sync access data. Read/write access lets C1 sync access data and provision access. - -If you're using Google Workspace as your C1 directory and don't want C1 provisioning access, the read-only set is all you need. It syncs users, groups, and roles, and it cannot modify anything in Workspace. - - Paste this comma-separated list into the **OAuth Scopes** field: @@ -391,7 +385,7 @@ https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.goo -The write scopes let C1 provision and deprovision access. **If you don't want C1 to perform these tasks, use the read-only scope set.** +The write scopes let C1 provision and deprovision access. **If you don't want C1 to perform these tasks, use the read-only scope set.** Read-only still syncs users, groups, and roles, so it's sufficient when you use Google Workspace as your [directory](#set-google-workspace-as-your-c1-directory) and run access reviews. ### Find your customer ID and primary domain @@ -596,12 +590,6 @@ Check that the connector data uploaded correctly. In C1, click **Apps**. On the -### What's next? - -If Google Workspace holds a record for everyone at your company, designate it as your directory so C1 creates user accounts from it. See [Set Google Workspace as your C1 directory](#set-google-workspace-as-your-c1-directory). - -If Google Workspace is your company's identity provider (meaning that it is used to SSO into other software), the integration sync will automatically create applications in C1 for all of your SCIMed software. Before you move on, review the [Create applications](/product/admin/applications) page for important information about how to set up integrations with the SCIMed apps. - ## Set Google Workspace as your C1 directory If Google Workspace is your source of truth for who works at your company, designate the connector's app as your [directory](/product/admin/directory). C1 then creates a C1 user for each Workspace account it syncs, and accounts from your other connectors attach to those users. @@ -633,12 +621,16 @@ Click **Create directory**. For how directory accounts become C1 users, and how accounts from non-directory apps find an owner, see [Connect a directory](/product/admin/directory). +## What's next? + +If Google Workspace is your company's identity provider (meaning that it is used to SSO into other software), the integration sync will automatically create applications in C1 for all of your SCIMed software. Before you move on, review the [Create applications](/product/admin/applications) page for important information about how to set up integrations with the SCIMed apps. + ## Troubleshooting the Google Workspace integration | Symptom | Cause | Fix | | :--- | :--- | :--- | | `FAILED_PRECONDITION: Key creation is not allowed on this service account` | The `iam.disableServiceAccountKeyCreation` organization policy is enforced, or you lack the Service Account Key Admin role. | See [Allow service account key creation](#allow-service-account-key-creation). | -| `Error 403: Request had insufficient authentication scopes` / `ACCESS_TOKEN_SCOPE_INSUFFICIENT` | The domain-wide delegation grant is missing scopes the connector needs. | Remove and re-add the API client with the full scope set. See below. | +| `Error 403: Request had insufficient authentication scopes` / `ACCESS_TOKEN_SCOPE_INSUFFICIENT` | The domain-wide delegation grant is missing scopes the connector needs. | Remove and re-add the API client with the full scope set. See [When adding permissions to my Google Workspace API Client permissions I get authorization errors](#when-adding-permissions-to-my-google-workspace-api-client-permissions-i-get-authorization-errors). | | `unauthorized_client` when the connector authenticates | The Client ID in domain-wide delegation doesn't match the service account's Unique ID, or the requested scopes aren't authorized. | Confirm you entered the numeric **Unique ID**, not the service account email, and that the scope list matches exactly. | | `SERVICE_DISABLED` or "API has not been used in project ... before or it is disabled" | The connector's API isn't enabled in the project. | Enable it. See [Enable the APIs](#enable-the-apis). | | Authentication succeeds but the sync returns no users or `Not Authorized to access this resource/api` | The **Administrator email** isn't a super admin, or the **Customer ID** is wrong. | Confirm both values. See [Find your customer ID and primary domain](#find-your-customer-id-and-primary-domain). | From a5688a3b99cad432813d6767cd2c63d28f81eff5 Mon Sep 17 00:00:00 2001 From: Melinda Moreland Date: Fri, 14 Aug 2026 12:15:02 -0700 Subject: [PATCH 4/4] docs: apply style guide fixes Co-Authored-By: Claude Sonnet 5 --- baton/google-workspace.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/baton/google-workspace.mdx b/baton/google-workspace.mdx index 819f9ab5..5a66a938 100644 --- a/baton/google-workspace.mdx +++ b/baton/google-workspace.mdx @@ -78,6 +78,8 @@ Each section below gives the Google Cloud console steps and the equivalent `gclo ### Create or select a project +Create a new Google Cloud project dedicated to this connector, or select an existing one. + Sign in to [https://console.cloud.google.com](https://console.cloud.google.com/) with an account that can create projects, enable APIs, and manage service accounts. @@ -160,6 +162,8 @@ gcloud services list --enabled --project=YOUR_PROJECT_ID ### Create a service account +Create the service account C1 will authenticate as. + In the navigation menu, navigate to **APIs & Services** > **Credentials**. @@ -265,6 +269,8 @@ Google recommends against long-lived service account keys and prefers Workload I ### Create the key and get the unique ID +Generate the service account's JSON key and record its numeric unique ID, which domain-wide delegation requires. + Navigate back to **APIs & Services** > **Credentials** and select the service account you just created. @@ -390,6 +396,8 @@ The write scopes let C1 provision and deprovision access. **If you don't want C1 ### Find your customer ID and primary domain +The connector configuration needs your Google Workspace customer ID and primary domain, both available in the Admin console. + In the Google Admin console, select **Account** > **Account Settings**.