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

1. A Google Cloud project with the Admin SDK and Drive API enabled
2. A service account with domain-wide delegation enabled
3. 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
https://www.googleapis.com/auth/admin.directory.group	Group and membership management
https://www.googleapis.com/auth/drive	Shared drive and permission management

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.

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

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

---

Group Membership Management

listGroups

Lists groups in the domain, optionally filtered by user membership.

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

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:

1. Builds a signed JWT assertion using the service account's private key (via jose)
2. Exchanges the JWT for an access token at https://oauth2.googleapis.com/token
3. Uses the sub claim to impersonate the admin user (domain-wide delegation)
4. 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): ...",
  "data": {
    "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.