How to Sync Google Workspace Users and Groups to Auth0 with Directory Sync

Enabling Directory Sync for your Google Workspace enterprise connection lets you synchronize the user profiles, group structures, and group membership from Google Workspace to Auth0. You can synchronize automatically or manually:

Automatic synchronization runs every 30 minutes after the last sync completes.
Manual synchronization runs when you trigger it.

Enable Directory Sync

You can enable Directory Sync using the Auth0 Dashboard or the Management API.

Auth0 Dashboard
Management API

Prerequisites

Before you begin, you must have:

A Google Workspace enterprise connection in Auth0
Administrator privileges on the Google Workspace organization.

Enable the admin directory API for your enterprise connection

To enable directory sync, the Google access token for your Google Workspace enterprise connection must have the the appropriate scopes to access Google’s APIs.On the Settings tab of an existing Google Workspace enterprise connection (or when creating new connection), in the Identity Provider API section, select Use Admin Directory API and choose:

Users scopes to add scopes only to access users.
Users and Groups scopes to add scopes to access both users and groups.

When using Directory Sync, we also recommend disabling Sync User Profile Attributes at Login in this section to avoid conflicting updates from multiple sync methods.

Click Save Changes.

Verify Google administrator consent

From Auth0 Dashboard > Authentication > Enterprise, open your Google Workspace connection. On the Setup tab, either:

Follow the Continue link if you have admin permissions to configure your Google Workspace settings to use Google’s Admin APIs, or
Provide the given URL to your administrator so that they can adjust the required settings

Enable Directory Sync

On the Provisioning tab of your connection, toggle Provision Users Using Directory Sync. and choose the your configuration options:

In Resources, under Sync. choose whether to sync Users or Users and Groups. If you sync both users and groups, the section expands to show which groups are syncing (Syncing all groups by default). To customize the synced groups, see the next step.
In Schedule, optionally check Enable Automatic Synchronization to automatically sync every 30 minutes. You can trigger a manual synchronization by selecting Synchronize now.
In Attribute Mapping, you can customize the mapping of Google attributes to Auth0 user profile attributes.

Customize synced groups (optional)

When you enable Directory Sync to synchronize both users and groups from Google Workspace, you can choose to sync all groups in your directory or choose only a subset to prevent database bloat and preserve API rate limits.You can customize which groups you synchronize by either selecting them from the paginated list in the Auth0 Dashboard or by uploading a JSON of the group IDs:

Select from list
Upload JSON

On the Provisioning tab of your connection, under the toggled Provision Users Using Directory Sync option, find the Resources section and select the Select Groups… button.
In the Select Groups window that opens, select the Select tab to view the list of available groups. This information is synced live with your Google Workspace groups. You can use the search bar to filter against group name or email.
Check the boxes next to the groups you want to sync, then select Save Groups at the bottom of the window.

First, compose the JSON file. You can get a list of all group IDs using the Google Workspace Directory API.Each group object in the list has the following properties:

string

required

The group ID.

string

The display name of the group.

string

The email for the group.

integer

The number of members in the group.

Create the file in the following format, substituting the actual group IDs and other values for the placeholder example values:

{
    "groups": [
        {
            "id": "example-id-1",
            "name": "Example Group",
            "email": "examplegroup@example.com",
            "direct_members_count": 123
        },
        {
            "id": "example-id-2"
        },
        {
            "id": "example-id-3"
        }
    ]
}

Next, upload the file to Auth0:

On the Provisioning tab of your connection, under the toggled Provision Users Using Directory Sync option, find the Resources section and select the Select Groups… button.
In the Select Groups window that opens, select the Upload tab.
Select + Choose file and upload the JSON file.
After the file uploads, select Save Groups at the bottom of the window.

The Resources section displays Syncing specific groups. To update which groups you synchronize, return to the same Select Groups window and update your choices.If we detect that a synchronized group ID is deleted in Google Workspace Directory, we automatically remove that group ID from the configuration for subsequent job syncs.

Prerequisites

Before you begin, you must have:

A Google Workspace enterprise connection in Auth0
Administrator privileges on the Google Workspace organization.
A Management API access token with the following scopes:
- create:directory_provisionings
- read:directory_provisionings
- update:directory_provisionings
- delete:directory_provisionings
Your Google Workspace connection ID (CONNECTION_ID).

Enable the admin directory API for your enterprise connection

When creating a new Google Workspace enterprise connection using the Create a connection endpoint (POST /v2/connections), or when modifying an existing enterprise connection using the Update a connection endpoint (PATCH /v2/connections/{id}), set the following body parameters:

option.api_enable_users to true to add scopes to access users.
option.api_enable_groups to true to additionally add scopes to access groups. Group access requires user access.

When using Directory Sync, we recommend disabling syncing user profiles on login (setting options.set_user_root_attributes to never_on_login) to avoid conflicting updates from multiple sync methods.

Verify Google administrator consent

From Auth0 Dashboard > Authentication > Enterprise, open your Google Workspace connection. On the Setup tab, either:

Follow the Continue link if you have admin permissions to configure your Google Workspace settings to use Google’s Admin APIs, or
Provide the given URL to your administrator so that they can adjust the required settings

Enable Directory Sync

Enable Directory Sync with the Create a directory provisioning configuration endpoint (POST /v2/connections/{id}/directory-provisioning), or update an existing Directory Sync configuration with the Patch a directory provisioning configuration endpoint (PATCH /v2/connections/{id}/directory-provisioning), and use the following request body parameters:

mapping to define the mapping of Google attributes to Auth0 user profile attributes.
synchronize_automatically set to true to automatically sync every 30 minutes or false to disable automatic synchronization.
synchronize_groups set to one of:
- all to synchronize all groups in addition to users
- selected to synchronize only the groups you specify
- off to synchronize only users

If you choose to synchronize only selected groups, you additionally need to specify the groups to synchronize.First, get a list of group IDs using the Google Workspace Directory API. Then, use the Management API’s Configure groups to synchronize endpoint (PUT /v2/connections/{id}/directory-provisioning/synchronized-groups) with the request body parameter of group IDs for the groups you want to synchronize in the following format:

"groups" [
    {
        "id": "example-id-string",
    },
    {
        "id": "example-id-string-2",
    },
    {
        "id": "example-id-string-3",
    }
]

To trigger a manual sync, use the Create a directory provisioning configuration endpoint.

Monitor Directory Sync activity

You can monitor sync activity in Auth0 tenant logs the under Directory Sync Started and Directory Sync Completed log types (event codes directory_sync_started and directory_sync_completed).

Limits

Synchronizing manually within 30 minutes of the last completed sync returns a 400 error. Wait at least 30 minutes before synchronizing again.
When using user account linking, the sync-provisioned user account must be set as the primary user account. We do not recommend linking Enterprise user accounts to social and personal user accounts.
Group names in Google Workspace Directory must be unique. While Google allows case-insensitive duplicate names, Auth0 enforces unique display names. If you have multiple groups with the same name in Google Workspace Directory, the duplicate groups do not sync and the sync is marked as failed.
Because Google only reports users as deleted within 20 days of deletion, if you delete a user in Google Workspace Directory and do not sync with Auth0 within 20 days, we do not detect that the user has been deletected. We recommend automatic synchronization to avoid this issue.

​Enable Directory Sync

​Monitor Directory Sync activity

​Limits

Enable Directory Sync

Monitor Directory Sync activity

Limits