WorkOS Docs Homepage
Integrations
API referenceDashboardSign In
Integrations

Google Directory Sync

Learn about syncing your user list with Google Workspace.

Introduction

This guide outlines how to synchronize your application’s Google Workspace directories.

1. Select environment

Login to your WorkOS dashboard and ensure you have the desired environment selected.

Select the desired WorkOS environment from the navigation.

Select “Organizations” in the navigation.

Select the organization that’d like to enable a Google Directory Sync connection.

On the Organization page, under “Invite an admin to set up this organization,” select “Invite Admin.”

Select “Invite Admin” from the organization page.

Select “Directory Sync” and any other features you’d like the organization to be able to onboard.

Select “Directory Sync” and any other features you'd like the organization to be able to onboard.

Enter the email address of the organization admin, or copy the setup link and send it to the organization admin.

Enter the email address of the organization admin, or copy the setup link.

3. Authenticate with admin credentials

Have the organization choose Google as a provider and follow the Google prompts to authenticate with admin credentials.

A screenshot showing the requested permissions in the Google modal.

4. Select which groups to sync to Your Application

The organization admin can then select to filter which groups and memberships are synced to the directory. If groups are being filtered, then only users with a membership within one of the synced groups will be synced.

A screenshot showing the setup screen with how to filter groups to sync.

5. Sync users and groups to Your Application

Changes will appear live in the Directory Sync portal under the “Users” tab:

A screenshot showing users in the "Users" tab of the WorkOS Dashboard.

A detailed guide to integrate the WorkOS API with your application can be found here

Frequently asked questions

Can you selectively sync users and groups from Google Workspace?

Yes, you can select to sync certain groups during setup within the Admin Portal as seen in Step 4.

When do users get removed from a directory?

There are 2 ways a user can be deleted from a Google Workspace directory.

  1. The user is removed or archived on Google and no longer returned by their API.
  2. When the directory is filtering specific groups, if a user is removed from all groups that are being filtered in, the user is removed from the directory as well.

How often do Google Workspace directories perform a sync?

Google Workspace directories are synced approximately every 30 minutes starting from the time of the initial sync

Does Google Directory Sync support nested groups?

Yes, nested groups (groups within groups) are supported in Google Directory Sync. This feature is currently available in a restricted preview. Contact WorkOS support for additional details.