Google Cloud Directory Sync

Set up GCDS  |  Your Google Account  |  Syncing users & organizational units  |  Syncing groups |  Google Cloud  |  General

Open all   |   Close all

Set up GCDS

How do I authorize GCDS on a machine without a graphical user interface (GUI)?

To install, configure, and run GCDS on a Linux server without a GUI environment:

  1. Create the XML file by running Configuration Manager on a machine with a GUI.

    It is recommended that you use a Linux machine so that the file paths match, however, a Windows machine will also work once the correct file path is used in the configuration file.

  2. Copy the XML file to the new machine without the GUI.

  3. Remove the following elements from the XML file if they are present:
    • smtpAuthPasswordEncrypted
    • oAuth2RefreshToken
    • encryptedSslProxyPassword
  4. Open a command prompt and to set your LDAP credentials, enter:

    ./upgrade-config -ldapuser LDAP_username -ldappassword LDAP_password -c config_file_name

  5. Authorize your Google domain, by entering: 

    ./upgrade-config -Oauth Google_domain_name -c config_file_name

  6.  Follow the prompt and copy the URL into a web browser to obtain the OAuth token.

  7. Copy the OAuth token into the command prompt to set it.

  8. To test the LDAP connection, enter:

    ./upgrade-config -testldap -c config_file_name

  9. To test the Google connection, enter:

    ./upgrade-config -testgoogleapps -c config_file_name

How do I change my GCDS server?

Follow these steps if you need to move GCDS to a different server:

  1. If you think you have or you’re not sure if you have pending user email address changes (user renames), choose an option:
    • Run a synchronization on the old server.
    • Copy the tab-separated values (TSV) files to the new server.

      You can find the name and location of the TSV files in the configuration file. In the configuration file, search for .tsv to locate this information.

  2. Install GCDS on the new server. For instructions, see Download and install GCDS.
  3. Copy the configuration file to the new server.
  4. On the new server, in Configuration Manager, open the configuration file. 
  5. Reauthorize GCDS for your Google Account. For instructions, see Authorize your Google Account
  6. On the LDAP Configuration page, update the LDAP password. For instructions, see LDAP connection settings
  7. On the Notifications page, update the SMTP password. For instructions, see Notification attributes.
  8. Run a simulated sync.
  9. Review the sync to make sure there are no unexpected changes.
  10. Run a full sync.

    After the sync, the TSV files from the old server are updated. If you didn’t transfer the TSV files, new files are created.

What can I do if I'm having problems with certificates?

If you're experiencing any problems with certificates when running GCDS, see Troubleshoot certificate-related problems.

↑ back to top

Your Google Account

What APIs does GCDS use?

GCDS uses APIs to upload data and make requests to your Google Account. GCDS uses OAuth to authenticate the APIs. It also uses SMTP to send the sync reports. GCDS uses the following APIs:

Why am I not seeing the expected changes in my Google Account?

It can take up to 8 days for you to see a change in your Google Account. To understand why, you need to understand how GCDS caches data.

GCDS keeps a cache of data for your Google Account for a maximum of 8 days. GCDS can clear the cache more frequently, depending on the cached data size. However, if the cache isn't cleared, it might take up to 8 days to see changes that were made directly on your Google Account (using the Admin console or another API client). 

Once the cache is cleared, GCDS identifies the change in the Google Account and compares that with the source data in the LDAP directory. If the data doesn't match, GCDS undoes the change made in the Google Account. 

To manually clear the cache:

  • Run a sync from Configuration Manager and select to clear the cache when performing a sync.
  • Use the command line flag -f to force a flush of the cache.
  • Modify the XML config file to set the maxCacheLifetime value to 0.

Important: Flushing the cache can significantly increase synchronization time.

How does GCDS access user profile data in my Google Account?

User profiles, including additional user attributes, are written to the Google user account and are visible in the account’s Directory. GCDS accesses the Directory in Google Contacts. 

How does GCDS determine what alias email addresses are added to a Google Account?

In the GCDS configuration, you can specify the attributes that GCDS evaluates. GCDS evaluates the data stored in the attribute only if it matches a valid SMTP address.

When using Microsoft Active Directory proxyAddresses, GCDS strips off the smtp: prefix during the sync so the prefix doesn't show on your Google domain. 

Can I sync to more than one Google account at the same time?

Yes. You can use GCDS to sync from one LDAP directory to multiple Google accounts by using more than one configuration file. If multiple syncs are run at the same time, make sure the configuration files are saved with unique names.

To clone an existing configuration file, use the Save as option in Configuration Manager and save the file with a new name.

↑ back to top

Syncing users & organizational units

How do I configure GCDS to provision only a subset of users? 

If you want to sync a subset of users to your Google Account you can use a single Active Directory or LDAP directory group as your source. Using a group limits the number of users that get provisioned in your Google Account.


User Query

This query returns all users who are members of the group identified by the group DN, have email addresses, and whose accounts aren't disabled.

How can I exclude an organizational unit in my Google Account from a sync?

You can configure GCDS to exclude an organizational unit that has been set up in your Google Account by defining an Organization Complete Path exclusion rule in the Google Domain configuration.


Exclude Rule
Type: Organization Complete Path
Match Type: Exact Match
Rule: /OUPath/MyExcludedOU

Can I sync users to a secondary domain?

If you have added an additional (secondary) domain, you can use GCDS to sync users to that domain. To sync users to your secondary domain, ensure the users' mail address in your LDAP server matches your secondary domain name. GCDS creates the users in your Google Account using your secondary domain as the primary mail address.

If you don't want to make changes to your existing LDAP mail attribute, assign another attribute to sync your secondary domain users' email addresses. For details about secondary domains, see Add multiple domains or domain aliases.

Can I use wildcards with LDAP user search queries?

Yes, as long as the LDAP server supports wildcards.

LDAP directories don’t support wildcards in DN attributes when you’re conducting a user search query. For example, you can use (mail=user*), but not (distinguishedName=*,DC=domain,DC=com).

Can I use a memberOf recursive search for user search queries?

Yes, if you're using an LDAP server that supports memberOf recursive searches. They're supported by Active Directory, but not by OpenLDAP.

Why is my Google Workspace user account being suspended after I run GCDS?

If a Google Workspace user account is suspended after running GCDS, you will receive an error explaining why this happened. In order to avoid repeating the particular error on any subsequent syncs, you can implement one of the following solutions depending on the cause of the problem:

  • Problem: The user doesn't exist on the LDAP server.

    Solution: Since the user doesn't exist on the LDAP server, the customer should set a Google user exclusion rule to prevent GCDS suspending this user in Google Workspace.

  • Problem: The user doesn't have a valid email on the LDAP server.

    Solution: Since the user doesn't have a valid email on the LDAP server, you should configure an email address for this user or set a Google user exclusion rule to prevent GCDS suspending this user in Google Workspace.

    You can also change the GCDS configuration so that it uses the user’s email address attribute that is on the LDAP server. For example, use the attribute userPrincipalName (UPN) instead of the attribute mail.

  • Problem: The user is being skipped by exclusion rules on the LDAP server.

    Solution: You should correct the exclusion rules if you don't want to suspend this user.

  • Problem: The user is being found and suspended in the search rules because the Suspend these users in the Google Domain option is checked.

    Solution: The user might need to be suspended.

  • Problem: The user has been suspended on the LDAP server.

    Solution: The user might need to be suspended.

↑ back to top

Syncing groups

Can GCDS sync cyclic group memberships?

In a cyclic group membership, 2 (or more) groups are members of each other. For example, Group A is a member of Group B and Group B is a member of Group A.

Cyclic group memberships are supported by LDAP and Microsoft Active Directory. However, they aren't supported by Google Groups. If you try to synchronize a cyclic membership, you'll see the error "Cyclic memberships not allowed."

How can I ensure GCDS won't delete or modify existing groups that I have created? 

You can configure GCDS to exclude a group by defining a Group Email Address exclusion rule in the Google domain configuration. For details, see Use rules for Google data.


Exclude Rule
Type: Group Email Address
Match Type: Exact Match
Rule: GCP_Project1@domain.com

Note: We recommend you create and manage these groups in your LDAP directory. Group memberships are kept up-to-date in your Google Account when GCDS synchronizes data.

To keep existing groups that aren't in LDAP, you can turn on the Don’t delete Google Groups not found in LDAP setting. For details, see Google Group deletion policy.

Does GCDS synchronize user-created groups?

A user-created group is a group created in Google Groups for Business. If an LDAP group matches a user-created group, GCDS ignores the group as though there is a GCDS exclusion rule in place for that specific group. It won't remove the group if it doesn't match the LDAP data. 

If you have added members to the corresponding object/entity in LDAP, GCDS adds those members to the group. If you have added users to the Google Group that don't match your LDAP data, those members won't be removed during the sync process. 

For more information on user-created groups, see Groups administrator FAQ

Can GCDS sync nested group memberships?

Yes, GCDS syncs nested group memberships. However, there are some limitations regarding nested groups and email delivery with Google Groups for Business. Not all nested group members receive email content that's sent to the group when:

  • Moderation permission is enabled. An email won't automatically flow to group members or other nested groups until the moderator of the group gives approval.
  • A parent group doesn't have posting permission to send the message to the nested groups.

Related topics

Can GCDS search nested group memberships?

Yes. GCDS syncs members of groups, regardless of whether the member is a user or a group. However, GCDS doesn’t support a search rule to expand members of nested groups if that search rule isn’t supported by your LDAP server.

↑ back to top


Why does GCDS keep returning an error when the cache is cleared?

The error might be caused by a configuration issue, such as an exclusion rule misconfiguration. The misconfiguration can be hidden by GCDS caching.

GCDS keeps a cache of data for your Google service (such asGoogle Workspace or Cloud Identity) for a maximum of 8 days. GCDS can clear the cache more frequently, depending on the cached data size. However, if the cache isn't cleared, it might take up to 8 days to see changes that were made directly on your Google Account (using the Admin console or another API client). 

To manually clear the cache:

  • Run a sync from Configuration Manager and select to clear the cache when performing a sync.
  • Use the command line flag -f to force a flush of the cache.
  • Modify the XML config file to set the maxCacheLifetime value to 0.

Important: Flushing the cache can significantly increase synchronization time.

Example: You have a group that exists on both your LDAP server and your Google Account. You create a Google exclusion rule for this group, hoping to prevent GCDS from changing the group during a sync.

However, this rule actually causes GCDS to behave as if the group doesn't exist on your Google Account. GCDS tries to create the group but, because the group already exists, you see an error and GCDS adds it to the cache. Subsequent syncs use the cache and GCDS recognizes that the group already exists. Then, once the cache is cleared, GCDS again behaves as if the group doesn't exist.

Why do I have to configure GCDS to sync passwords?

The default password sync settings in GCDS are used to define how GCDS creates passwords for new user accounts. If you don’t want to customize an initial account password, no action is required. Just use the default settings.

If you're using Active Directory you can use Password Sync to sync user passwords from Active Directory to your Google domain. 

How does GCDS resolve conflicts when multiple sync rules apply?

GCDS considers the rules in order, from the highest to lowest. 

For example, you configure a User Accounts sync rule to create users in the root organizational unit or /. You then create a lower rule to create users in the /Exceptions organizational unit. After a sync, users matching both rules are created in the root organizational unit because that rule has higher precedence. 

To ensure that users are correctly placed in /Exceptions, make sure the rule is listed higher than any other conflicting rule. Or, ensure that it's the first rule in the ordered list.

How can I audit and review a GCDS synchronization? 

GCDS uses 3-legged OAuth 2.0 for authorization. This process grants GCDS an OAuth 2.0 token. The token allows GCDS to take action on behalf of the administrator who performed the authorization.

All audit events are listed by the administrator who authorized GCDS. Consider creating a dedicated GCDS administrator account so that you can clearly see the changes and audits performed by GCDS. 

Related topic

Authorize your Google Account

Will GCDS delete my schemas if I enable schema sync?

During a sync GCDS considers the current LDAP set up to determine if a custom schema should be retained or deleted in your Google Account. 

Additionally, the GCDS configuration file has a schemaHistory setting that contains information on custom schemas that have been synced before. If a custom schema has been synced by GCDS, it’s automatically added to the schemaHistory. If you manually delete the schemaHistory settings in the configuration file, and if the custom schema doesn’t exist in your LDAP directory, GCDS skips and doesn’t delete the custom schema in your Google Account.

To manually delete your schemaHistory in your configuration file, look for: 

   <schemaDefinitions />

Can I sync GCDS from multiple LDAP directories?
GCDS can only sync from a single LDAP directory. If you have multiple LDAP directories, it is recommended that you consolidate your LDAP server data into a single directory. For details, see Step 2 in Prepare your LDAP directory.
How does GCDS generate and securely store the symmetric key?

The symmetric key which encrypts the GCDS refresh token is generated by the default Java crypto KeyGenerator using AES 128. 

The symmetric key storage is handled by the userNodeForPackage method in Preferences class in Java. The exact location of the key is not controlled by GCDS and is OS dependent.

On Windows, the preference data is stored in the registry hive for the user. On Linux it is stored in the user’s home directory.

We recommend customers follow best practices to ensure that the key is properly secured by using an encrypted file system and ensuring restrictive ACLs.

What is the Unique ID?

The unique ID is used internally by GCDS and it can also be referred to as the non-address primary key. This does not get synchronized to Google Workspace and GCDS stores the unique ID in a .tsv file on the machine on which GCDS is installed. You can find the file name and its full path in the XML configuration file.

If a user is renamed on the LDAP server but not on Google Workspace, GCDS uses the Unique ID to prevent this user’s details from being deleted or duplicated which could also lead to data loss.

Note: If you manually change the user's email addresses on both the LDAP server and Google Workspace, you may cause an incorrect sync. In order to avoid this, you can remove the corresponding user records from the .tsv file before you run GCDS.

↑ back to top

Google Cloud

How can I synchronize security groups from Active Directory or my LDAP directory and use them in Cloud IAM? 

You can configure GCDS to sync security groups using LDAP search rules. 

Example 1: Search for all security groups

This example shows an LDAP search for all security groups that have an email address:


Example 2: Search for a subset of security groups

If you want to sync a subset of security groups, consider using extensionAttribute1 and set a specific value, such as GoogleCloud. You can then refine the GCDS query to only provision the specific subset of security groups:

This example shows an LDAP search for all security groups that have an email address and the GoogleCloud attribute:



  • All groups in a Google domain are referenced by an email address. You must ensure that all the security groups you want to synchronize have a valid mail attribute defined.
  • A group created in a Google domain doesn't automatically have an explicit Google Cloud Identity and Access Management (IAM) role. After a group is created, you need to use Cloud IAM to assign a group to specific roles.
How can I add users who only need an account for Google Cloud projects?

You can configure GCDS by adding a user sync rule for Google Cloud users. The simplest way is to create a new query based on the users being a member of a group. For example:


Then, you can use the following  search filter to return users who are members of the group, have an email address, and whose accounts aren’t disabled: 

group cn=CloudUsers,cn=users,dc=corp,dc=domain,dc=com

Consider placing these users into a single organizational unit. To do this, define an Org Unit Name (for example, Cloud Users) in the rule. Create the organizational unit if it doesn't already exist. 

Licensing issues

Consider how your domain is configured so that you can appropriately assign product licenses to user accounts. If automatic licensing is enabled, you may want to exclude the Cloud Users organizational unit from being assigned a product license. For details, see Set automatic licensing options for an organization.

For more complex licensing requirements, you can configure GCDS to sync and manage all your user license assignments. For detail, see Sync licences

↑ back to top

Google, Google Workspace, and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.

Was this helpful?
How can we improve it?
Clear search
Close search
Google apps
Main menu
Search Help Center