Google Workspace Connector¶

Built-in connector for managing Google Workspace users, group memberships, and shared drive access through Google's Admin SDK and Drive API.

Prerequisites¶

A Google Cloud project with the Admin SDK and Drive API enabled
A service account with domain-wide delegation enabled
The service account must be granted the required OAuth scopes in the Google Workspace Admin Console (Security > API Controls > Domain-wide Delegation)

Required OAuth Scopes¶

Scope	Purpose
`https://www.googleapis.com/auth/admin.directory.user`	User management (`listUsers`, `createUser`, `setPassword`, etc.)
`https://www.googleapis.com/auth/admin.directory.group`	Group and membership management (`listGroups`, `addGroupMember`, etc.)
`https://www.googleapis.com/auth/admin.directory.orgunit.readonly`	Org-unit lookup & validation in the workflow designer (`listOrgUnits`, `getOrgUnit`). Required — without this, the designer cannot populate or validate the `orgUnitPath` field on `createUser` and returns `403 insufficientPermissions`.
`https://www.googleapis.com/auth/drive`	Shared drive and permission management (`listSharedDrives`, `addDrivePermission`, etc.)

All four scopes must be authorized in one Domain-wide Delegation entry for the service account's Client ID. Adding a scope here without re-authorizing it in the Admin Console produces a 403 insufficientPermissions at first call.

Connection Configuration¶

Create a connector instance via the Connectors API or UI with type google-workspace.

Field	Type	Required	Secret	Description
`serviceAccountEmail`	string	Yes	No	Service account email (e.g. `sa@project.iam.gserviceaccount.com`)
`privateKey`	string	Yes	Yes	RSA private key from the service account JSON key file
`adminEmail`	string	Yes	No	Workspace admin email for domain-wide delegation impersonation
`customerId`	string	No	No	Google Workspace customer ID (defaults to `my_customer`)

Example Configuration¶

{
  "serviceAccountEmail": "floh-connector@my-project.iam.gserviceaccount.com",
  "privateKey": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "adminEmail": "admin@example.com",
  "customerId": "C03az79cb"
}

Commands¶

test¶

Validates credentials by acquiring an OAuth2 access token via JWT assertion.

Parameters: none

Output:

tokenObtained (boolean)
adminEmail (string)
customerId (string)

User Management¶

listUsers¶

Lists users in the Google Workspace domain. This command is sync-capable — when called by the sync engine, it returns normalized ConnectorResourceRecord objects instead of raw Google user objects.

Parameter	Type	Required	Default	Description
`query`	string	No	-	Search query (e.g. `email:john*`)
`maxResults`	number	No	100	Maximum users to return
`pageToken`	string	No	-	Pagination token

Output variables: users, count

Sync mode output: resources, nextCursor (when called with resourceType or cursor)

getUser¶

Retrieves a single user by email or user ID.

Parameter	Type	Required	Description
`userKey`	string	Yes	User email address or immutable ID

Output variables: user

createUser¶

Creates a new user account.

Parameter	Type	Required	Default	Description
`primaryEmail`	string	Yes	-	User's primary email
`firstName`	string	Yes	-	Given name
`lastName`	string	Yes	-	Family name
`password`	string	Yes	-	Initial password
`orgUnitPath`	string	No	`/`	Organizational unit path

Output variables: created, userId, primaryEmail

suspendUser¶

Suspends a user account.

Parameter	Type	Required	Description
`userKey`	string	Yes	User email or ID

Output variables: suspended, userKey

deleteUser¶

Permanently deletes a user account.

Parameter	Type	Required	Description
`userKey`	string	Yes	User email or ID

Output variables: deleted, userKey

Password Management¶

The connector exposes three distinct password commands. Pick the one that matches the trust model of the caller:

Command	Password source	`changePasswordAtNextLogin`	Password returned where?	Typical use
`setPassword`	Caller-supplied	Configurable (default `false`)	Nowhere	Self-service reset, set initial password
`resetPassword`	Server-generated random	`true`	`payload.password` only	Admin-driven reset with one-time delivery
`rotatePassword`	Server-generated random	`false`	Nowhere	Offboarding / session invalidation

Security: None of these commands ever return the password value as a variable. Workflow variables flow into downstream steps and are persisted in run logs; secrets must not. resetPassword exposes the generated value in payload.password for one-time delivery (e.g. forwarding to a notification step that sends it directly to the user) — handle that field carefully.

setPassword¶

Sets a caller-supplied password on the account. Use for self-service password reset workflows and "set initial password" flows where the user (or another trusted caller) chooses the value, rather than receiving a server-generated one.

Parameter	Type	Required	Default	Description
`userKey`	string	Yes	-	User email or immutable ID
`password`	string	Yes	-	New password. Must be 8-100 characters and meet Google's policy.
`changePasswordAtNextLogin`	boolean	No	`false`	If `true`, Google forces the user to change the password on next sign-in. Leave `false` for self-service flows where the user just chose the value.

Output variables: userKey, passwordSet, changePasswordAtNextLogin

The password value is never returned in payload or variables. The caller already knows it; echoing it would leak it into run logs and downstream variable interpolation.

resetPassword¶

Generates a random password for the user, applies it via the Directory API, and forces a change at next login.

Parameter	Type	Required	Default	Description
`userKey`	string	Yes	-	User email or immutable ID
`passwordLength`	integer	No	`24`	Length of the generated password (8-128).

Output variables: userKey, changePasswordAtNextLogin

payload shape: { userKey, password, changePasswordAtNextLogin } — payload.password holds the generated value for one-time delivery (e.g. a follow-up notification step). It is not promoted to a workflow variable.

rotatePassword¶

Generates a random password and applies it without forcing a change at next login. Use to invalidate active sessions during offboarding or after a suspected credential compromise — the user is not expected to ever know this password.

Parameter	Type	Required	Description
`userKey`	string	Yes	User email or immutable ID

Output variables: rotated, userKey

The generated password is intentionally not returned anywhere.

Group Membership Management¶

listGroups¶

Lists groups in the domain, optionally filtered by user membership. This command is sync-capable — when called by the sync engine, it returns normalized ConnectorResourceRecord objects instead of raw Google group objects.

Parameter	Type	Required	Default	Description
`userKey`	string	No	-	Filter groups by this user's membership
`domain`	string	No	-	Filter by domain
`maxResults`	number	No	200	Maximum groups to return
`pageToken`	string	No	-	Pagination token

Output variables: groups, count

Sync mode output: resources, nextCursor (when called with resourceType or cursor)

listGroupMembers¶

Lists members of a group.

Parameter	Type	Required	Default	Description
`groupKey`	string	Yes	-	Group email or ID
`maxResults`	number	No	200	Maximum members to return
`pageToken`	string	No	-	Pagination token

Output variables: members, count

addGroupMember¶

Adds a user to a group.

Parameter	Type	Required	Default	Description
`groupKey`	string	Yes	-	Group email or ID
`email`	string	Yes	-	User email to add
`role`	string	No	`MEMBER`	Role: `MEMBER`, `MANAGER`, or `OWNER`

Output variables: added, groupKey, email, role

removeGroupMember¶

Removes a user from a group.

Parameter	Type	Required	Description
`groupKey`	string	Yes	Group email or ID
`memberKey`	string	Yes	Member email or ID to remove

Output variables: removed, groupKey, memberKey

checkGroupMembership¶

Checks whether a user is a member of a group.

Parameter	Type	Required	Description
`groupKey`	string	Yes	Group email or ID
`memberKey`	string	Yes	User email or ID

Output variables: isMember, groupKey, memberKey

Shared Drive Access Management¶

listSharedDrives¶

Lists shared drives in the domain.

Parameter	Type	Required	Default	Description
`query`	string	No	-	Search query
`maxResults`	number	No	100	Maximum drives to return
`pageToken`	string	No	-	Pagination token

Output variables: drives, count

addDrivePermission¶

Grants a user or group access to a shared drive.

Parameter	Type	Required	Default	Description
`driveId`	string	Yes	-	Shared drive ID
`email`	string	Yes	-	Email of user or group to grant access
`role`	string	No	`reader`	Permission role: `reader`, `commenter`, `writer`, `fileOrganizer`, `organizer`
`type`	string	No	`user`	Grantee type: `user` or `group`

Output variables: granted, driveId, email, role, permissionId

removeDrivePermission¶

Revokes a permission from a shared drive.

Parameter	Type	Required	Description
`driveId`	string	Yes	Shared drive ID
`permissionId`	string	Yes	Permission ID to revoke

Output variables: revoked, driveId, permissionId

listDrivePermissions¶

Lists all permissions on a shared drive.

Parameter	Type	Required	Default	Description
`driveId`	string	Yes	-	Shared drive ID
`maxResults`	number	No	100	Maximum permissions to return
`pageToken`	string	No	-	Pagination token

Output variables: permissions, count

Authentication Flow¶

The connector authenticates using the Google OAuth 2.0 service account flow:

Builds a signed JWT assertion using the service account's private key (via jose)
Exchanges the JWT for an access token at https://oauth2.googleapis.com/token
Uses the sub claim to impersonate the admin user (domain-wide delegation)
Caches the token and refreshes automatically before expiry

No additional npm dependencies are required -- the connector uses native fetch() for HTTP and the existing jose package for JWT signing.

Error Handling¶

All commands return structured error responses when the Google API returns a non-2xx status:

{
  "success": false,
  "error": "Google API error (403): ...",
  "diagnostics": {
    "statusCode": 403,
    "responseBody": { "error": { "message": "Insufficient permissions" } }
  }
}

Workflow Usage Example¶

{
  "type": "connector",
  "connector": "google-workspace",
  "command": "addGroupMember",
  "config": {
    "groupKey": "engineering@example.com",
    "email": "{{requestor.email}}",
    "role": "MEMBER"
  }
}

Debugging¶

Enable debug logging for this connector by setting the CONNECTOR_DEBUG environment variable:

CONNECTOR_DEBUG=google-workspace

This logs JWT token requests, API calls, and response details to stdout in structured JSON format.