GCDS FAQ

Google Cloud Directory Sync

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

Set up GCDS

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

To set up GCDS on a server without a GUI environment:

  1. Open a command prompt and to set your LDAP credentials, enter:

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

  2. Authorize your Google domain, by entering: 

    ./upgrade-config -Oauth Google_domain_name -c config_file_name

  3. To test the LDAP connection, enter:

    ./upgrade-config -testldap -c config_file_name

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

↑ 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 G Suite account at the same time?

Yes. You can use GCDS to sync from one LDAP directory to multiple G Suite 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.

Example:

User Query
(&(memberof=cn=appsUsers,cn=users,dc=corp,dc=domain,dc=com)(objectCategory=person)(objectClass=user)(mail=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

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

Example:

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.

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

Example:

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.

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. 

In some situations, 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 might not have posting permission to send the message to the nested groups. 

Related topics

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

↑ back to top

Google Cloud Platform

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:

(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=-2147483648)(mail=*))

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 GoogleCloudPlatform. 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 GoogleCloudPlatform attribute:

(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=-2147483648)(mail=*)(extensionAttribute1=GoogleCloudPlatform))

Important:

  • 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 Platform projects?

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

(&(memberof=cn=CloudPlatformUsers,cn=users,dc=corp,dc=domain,dc=com)(objectCategory=person)(objectClass=user)(mail=*)(!(userAccountControl:1.2.840.113556.1.4.803:=2)))

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=CloudPlatformUsers,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 Platform 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 Platform 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

General

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 as G Suite 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 domain (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

↑ back to top

Google, G Suite, 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?