> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
  const stageTextMap = {
    "beta": "Beta",
    "ea": "Early Access"
  };
  const stageText = stageTextMap[stage] || "a product release stage";
  const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
  const linkify = (text, url) => {
    return <a href={url} target="_blank" rel="noreferrer" class="link">{text}</a>;
  };
  const includeDetails = (plans, contact, terms) => {
    const hasDetails = terms || plans || contact;
    if (!hasDetails) return null;
    return <span data-as="p">
            {plans && <>This feature is available for {linkify(`${plans} plans`, "https://auth0.com/pricing")}. </>}
            {contact && "To participate, contact " + contact + ". "}
            {terms && <>By using this feature, you agree to the applicable Free Trial terms in Okta's {linkify("Master Subscription Agreement", "https://www.okta.com/legal")}.</>}
        </span>;
  };
  return <Warning>
            <span data-as="p">
                <strong>The {feature} feature is in {linkify(stageText, prsLink)}.</strong>
            </span>

            {includeDetails(plans, contact, terms)}
        </Warning>;
};

<ReleaseStageNotice feature="Google Workplace Directory Sync for Groups" stage="ea" terms="true" />

Enabling Directory Sync for your [Google Workspace enterprise connection](/docs/authenticate/identity-providers/enterprise-identity-providers/google-apps) 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.

<Tabs>
  <Tab title="Auth0 Dashboard">
    <Steps>
      <Step title="Prerequisites">
        Before you begin, you must have:

        * [A Google Workspace enterprise connection in Auth0](./google-apps)

        * Administrator privileges on the Google Workspace organization.
      </Step>

      <Step title="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.

        <Tip>
          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.
        </Tip>

        Click **Save Changes**.
      </Step>

      <Step title="Verify Google administrator consent">
        From [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/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
      </Step>

      <Step title="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.
      </Step>

      <Step title="Customize synced groups (optional)">
        When you enable Directory Sync to synchronize both users and groups from Google Workspace, all groups are synchronized by default. You can customize which groups you synchronize by uploading a JSON of the group IDs you want to synchronize.

        First, compose the JSON file. You can [get a list of all group IDs using the Google Workspace Directory API](https://developers.google.com/workspace/admin/directory/reference/rest/v1/groups/list). Create the file in the following format, substituting the actual group IDs for the placeholder example values:

        ```json theme={null}
        {
            "groups": [
                {
                    "id": "example-id-1"
                },
                {
                    "id": "example-id-2"
                },
                {
                    "id": "example-id-3"
                }
            ]
        }
        ```

        Next, upload the file to Auth0:

        1. 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.

        2. In the **Select Groups** window that opens, select **Pick specific groups** to reveal the **Groups JSON file** section.

        3. Select **+ Choose file** and upload the JSON file.

        4. After the file uploads, select **Select 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 either upload a new JSON or choose **Sync all**.

        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.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Management API">
    <Steps>
      <Step title="Prerequisites">
        Before you begin, you must have:

        * [A Google Workspace enterprise connection in Auth0](./google-apps)

        * Administrator privileges on the Google Workspace organization.

        * A [Management API access token](/docs/secure/tokens/access-tokens/management-api-access-tokens#management-api-access-tokens) with the following scopes:
          * `create:directory_provisionings`
          * `read:directory_provisionings`
          * `update:directory_provisionings`
          * `delete:directory_provisionings`

        * Your Google Workspace connection ID (`CONNECTION_ID`).
      </Step>

      <Step title="Enable the admin directory API for your enterprise connection">
        When creating a new Google Workspace enterprise connection using the [Create a connection endpoint](https://auth0.com/docs/api/management/v2/connections/post-connections) (`POST /v2/connections`), or when modifying an existing enterprise connection using the [Update a connection endpoint](https://auth0.com/docs/api/management/v2/connections/patch-connections-by-id) (`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.

        <Tip>
          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.
        </Tip>
      </Step>

      <Step title="Verify Google administrator consent">
        From [Auth0 Dashboard > Authentication > Enterprise](https://manage.auth0.com/#/connections/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
      </Step>

      <Step title="Enable Directory Sync">
        Enable Directory Sync with the [Create a directory provisioning configuration endpoint](https://auth0.com/docs/api/management/v2/connections/post-directory-provisioning) (`POST /v2/connections/{id}/directory-provisioning`), or update an existing Directory Sync configuration with the [Patch a directory provisioning configuration endpoint](https://auth0.com/docs/api/management/v2/connections/patch-directory-provisioning) (`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](https://developers.google.com/workspace/admin/directory/reference/rest/v1/groups/list). Then, use the Management API's [Configure groups to synchronize endpoint](https://auth0.com/docs/api/management/v2/connections/put-synchronized-groups) (`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:

        ```json theme={null}
        "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](https://auth0.com/docs/api/management/v2/connections/post-synchronizations).
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Monitor Directory Sync activity

You can monitor sync activity in [Auth0 tenant logs](/docs/deploy-monitor/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](/docs/manage-users/user-accounts/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.