Skip to content

Configuring a Google Workspace Connector

This guide walks through setting up a Google Workspace connector instance in the Floh admin UI so your workflows can manage Workspace users, group memberships, and shared drive access.

For the full command reference, see Google Workspace Connector. For API-based setup and curl examples, see Google Workspace Setup.

Prerequisites

Before you begin, you need three things from Google:

  1. A GCP service account JSON key file
  2. Admin SDK and Drive API enabled in the GCP project
  3. Domain-wide delegation configured in the Google Admin Console

If you haven't completed these steps yet, follow sections 1–3 of the setup guide and return here once delegation is authorized.

You also need a Floh account with the connector:manage permission (typically the Admin role).

Step 1 — Open the Connectors page

In the sidebar, click Connectors. This shows a table of all connector instances in the system.

Click New Connector in the toolbar. This opens the Create Connector Instance page.

Step 2 — Select the connector type

In the Connector Type dropdown, search for google-workspace and select it. A card appears confirming the type name, version, and description.

The google-workspace type is seeded automatically on server startup. If it doesn't appear in the dropdown, verify the server has started at least once since the type was added.

Step 3 — Name and describe the instance

Fill in:

Field Example value
Instance Name google-workspace-prod
Description Production Google Workspace — acme.com domain

Choose a name that distinguishes this instance from others if you plan to connect multiple Workspace domains.

Step 4 — Enter the connection configuration

A Connection Configuration section appears with four fields. Fill them in using values from your GCP service account JSON key file:

Field Where to find it Notes
serviceAccountEmail client_email in the JSON key file e.g. floh-connector@my-project.iam.gserviceaccount.com
privateKey private_key in the JSON key file Paste the full PEM value. Both literal \n sequences (as they appear in the JSON) and real newlines work.
adminEmail Your Google Workspace super admin account The service account impersonates this user for API calls.
customerId Google Admin Console > Account > Settings Optional. Defaults to my_customer if left blank.

The privateKey field is masked (password input) and encrypted at rest with AES-256-GCM.

Tip: You can skip connection config on this page and fill it in later from the connector's Configuration tab. The page notes this with: You can also configure this later from the connector detail page.

Step 5 — Create the connector

Click Create Connector. You're redirected to the connector detail page.

Step 6 — Test the connection

On the connector detail page, click Test in the header bar (or scroll to the Configuration tab and click Test Connection).

A Test Result dialog appears. A successful test shows:

  • Connection successful
  • tokenObtained: true
  • Your adminEmail and customerId echoed back

If the test fails, see Troubleshooting below.

Step 7 — Verify with a live command

Go to the Commands tab. You'll see the full list of available commands (user management, groups, shared drives). Click Try it on any command to open the Execute Command dialog.

Good commands to start with:

Command What it verifies
listUsers Admin SDK user scope is working
listGroups Admin SDK group scope is working
listSharedDrives Drive API scope is working

Set maxResults to a small number (e.g. 5) for a quick check.

Updating the configuration later

To change connection fields after creation:

  1. Open the connector from the Connectors list
  2. Go to the Configuration tab
  3. Edit the fields under Connection Config
  4. Click Save, then re-run Test Connection

Synchronizing users and groups

The Google Workspace connector supports syncing users and groups from your Workspace domain into Floh. This keeps Floh's user directory in sync with Google Workspace so that new hires, departures, and group changes are reflected automatically.

For general sync concepts (strategies, match outcomes, attribute mappings, post-sync workflows), see Syncing Connectors to User Profiles. This section covers the Google Workspace-specific setup.

Opening the Sync tab

  1. Open your Google Workspace connector from the Connectors list.
  2. Select the Sync tab.
  3. Two resource type tabs appear: Users and Groups.

Configuring user sync

Select the Users tab and configure:

Setting Recommended value Notes
Enabled On Enables scheduled sync.
Strategy Full The Google Directory API does not support modifiedSince filtering, so full sync is the correct choice. Each run fetches all users and marks missing ones as stale.
Cron schedule 0 2 * * * (daily at 2 AM) Adjust based on how often your directory changes.
Stale retention 7d How long to keep records not seen in the latest sync before deleting them.
User match strategy Email Matches synced Google users to Floh users by email address. Use Email + Issuer if your Floh instance has users from multiple identity providers.

Optionally enable:

  • Create users — automatically create Floh accounts for Google Workspace users that don't match an existing Floh user.
  • Deactivate users — soft-delete Floh users whose Google Workspace account is no longer present (only when no other connector still has an active match).

User attribute mappings

Add mappings to copy Google Workspace user fields into Floh user profiles. The source paths correspond to the synced resource's attributes object:

Source path Target field Description
attributes.orgUnitPath department Google org unit (e.g. /Engineering)
attributes.givenName (display name — auto-mapped) First name
attributes.familyName (display name — auto-mapped) Last name
attributes.suspended (no direct target) Available for workflow conditions
attributes.isAdmin (no direct target) Available for workflow conditions
attributes.lastLoginTime (no direct target) Available for workflow conditions
attributes.creationTime startDate Account creation date
email (auto-matched) Primary Google email

For each mapping, choose a write mode:

  • Overwrite always — always replace the profile value.
  • Overwrite if empty — only write when the profile field is currently blank.
  • Never overwrite — keep the mapping defined but dormant.

Configuring group sync

Select the Groups tab and configure the same settings (enabled, strategy, cron, stale retention). Group sync fetches all Google Workspace groups and stores them as connector resources.

Synced group attributes:

Source path Description
email Group email address
attributes.description Group description
attributes.directMembersCount Number of direct members

Group sync does not directly create or deactivate Floh users — those lifecycle options apply only to user sync. Group resources are available for entitlement definitions, workflow conditions, and reporting.

Running the first sync

  1. Click Save configuration after setting up each resource type.
  2. Click Sync now to trigger an immediate sync.
  3. Review results:
  4. Sync status card shows success/failure and statistics (added, updated, stale, unchanged).
  5. Synced resources table lists all fetched records with display name, email, external ID, and sync timestamp.
  6. Match reconciliation review (users only) shows how each synced user was matched to a Floh account.

Resolving unmatched users

After the first sync, some Google Workspace users may not match existing Floh accounts. In the Match reconciliation review section:

  • Link — manually associate a synced resource with a specific Floh user.
  • Skip — mark a record as intentionally skipped (e.g. service accounts, room resources).
  • Create user — create a new Floh user from the resource.

Manually resolved matches persist across future sync runs.

Sync troubleshooting

Symptom Cause Fix
Sync tab does not appear Connector type seed is outdated Restart the server to re-seed the google-workspace type with syncCapable commands.
Sync completes with 0 resources Connection test fails silently during sync Verify the connector passes the Test Connection check before configuring sync.
All users show as "unmatched" Users haven't logged into Floh yet Enable Create users to auto-create accounts, or switch to Email match strategy if using a stricter strategy.
Incremental strategy fetches all records Google Directory API does not support delta queries Use Full strategy instead.

Troubleshooting

Symptom Likely cause Fix
"pkcs8" must be PKCS#8 formatted string privateKey is missing or malformed Paste the full private_key value from the JSON file, not the private_key_id. Both literal \n and real newlines are accepted.
Not a valid email or user ID Typo in serviceAccountEmail or adminEmail, or delegation not configured Verify serviceAccountEmail matches client_email exactly, adminEmail is a real super admin, and the delegation entry exists in Admin Console.
403 Forbidden from Google Scopes not authorized in domain-wide delegation In Admin Console > Security > API controls > Domain-wide Delegation, confirm the Client ID has all four full-URI scopes: https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.orgunit.readonly, and https://www.googleapis.com/auth/drive. The Admin Console requires the full URI form — shorthand names are not accepted.
403 insufficientPermissions only on orgUnitPath lookup in the designer DWD entry pre-dates the admin.directory.orgunit.readonly scope Edit the DWD entry for this connector's Client ID and add https://www.googleapis.com/auth/admin.directory.orgunit.readonly. The change takes effect immediately — no connector restart needed.
Test passes but listUsers returns empty customerId mismatch Try leaving customerId blank (defaults to my_customer), or look up your actual customer ID in Admin Console > Account > Account settings.
Invalid or missing CSRF token (API/curl only) Write request missing CSRF headers Not applicable when using the admin UI — the app handles CSRF automatically.

What's next