Skip to content
Roster Roster Roster Docs

Google Workspace Connector

The Google Workspace connector reads users, groups, and group membership through the Admin SDK Directory API.

Provider Path

Section titled “Provider Path”
Admin SDK Directory API v1

Typical resources:

/users
/groups
/groups/{groupKey}/members

Roster uses Google Workspace live when an admin searches users or groups from the Platform participant picker. When the admin adds a selected user or group to a participant, Roster caches that selected record in directory_records and directory_record_sources. When the selected record is a group, Roster also caches the selected group’s direct members and membership edges for participant resolution.

MCP and REST directory-record search uses only Roster’s cached/materialized directory records. It does not call Google Workspace live.

Production Requirements

Section titled “Production Requirements”
  • Google Workspace customer ID, usually my_customer
  • delegated admin email in the Workspace domain
  • service account email
  • service account private key stored in the runtime environment or secret manager
  • domain-wide delegation for the service account
  • refresh schedule for selected users, groups, and group memberships
  • stable Google user and group IDs

The connector uses service-account domain-wide delegation, not interactive OAuth. Enable the Admin SDK API in the Google Cloud project, then authorize the service account client ID for the Directory API scopes needed by Roster.

Default scopes:

https://www.googleapis.com/auth/admin.directory.group.readonly
https://www.googleapis.com/auth/admin.directory.user.readonly

Secret Kinds

Section titled “Secret Kinds”

Supported secret kind:

private_key

Store the PEM private key outside Roster, then reference it from the connector:

env:GOOGLE_WORKSPACE_PRIVATE_KEY

Normalized Data

Section titled “Normalized Data”

The connector normalizes Google Workspace records into Roster directory users and groups:

queryUsers(query)
getUser(externalId)
queryGroups(query)
getGroup(externalId)
getGroupMembers(externalId, query)

Users are normalized from Google id, primaryEmail, and name.fullName or name.givenName plus name.familyName. Groups are normalized from Google id, email, name, and description.

Live search supports query text, exact external ID lookup, and paginated results. Page size is capped at 200 records, and Directory API nextPageToken values are carried as the next cursor.

Use participant membership to map Google Workspace users or groups to Roster participants.