Below are common questions about using Google Cloud Directory Sync.
- Set up GCDS
- Your Google Account
- Syncing users & organizational units
- Syncing groups
- General
- Google Cloud
Set up GCDS
Expand section | Collapse all & go to top
How do I authorize GCDS on a machine without a GUI?- Make sure you're running GCDS version 4.7.14 or later.
For details, go to Update GCDS.
- Authorize GCDS on a computer that has a GUI.
For details, go to Authorize your Google Account.
- Create and save the XML file.
- On the same computer, use the command line to run the upgrade-config tool using the -exportkeys parameter.
Example: upgrade-config -exportkeys encryption key file [password]
In this example, the keys are exported into a file called encryption key file. Using a password is optional.
- Copy the encryption key file and the configuration file to a computer without a GUI.
- On the computer without a GUI, use the command line to run the upgrade-config tool using the -importkeys parameter.
Example: upgrade-config -importkeys file name
Important: The -importkeys parameter removes any authorized GCDS configurations you might have on your computer.
- If needed, enter the password you set in step 4.
You should get confirmation that the keys were successfully imported.
Tip: For more options, from the command line, enter the upgrade-config -help command.
- 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 by searching for .tsv.
- Install GCDS on the new server. For instructions, go to Download & install GCDS.
- Copy the configuration file to the new server.
- On the new server, in Configuration Manager, open the configuration file.
- Reauthorize GCDS for your Google Account. For instructions, go to Authorize your Google Account.
- On the LDAP Configuration page, update the LDAP password. For instructions, go to LDAP connection settings.
- On the Notifications page, update the SMTP password. For instructions, see Notification attributes.
- Run a simulated sync.
- Review the sync to make sure there are no unexpected changes.
- 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.
If you're experiencing any problems with certificates when running GCDS, see Troubleshoot certificate-related problems.
Your Google Account
Expand section | Collapse all & go to top
What APIs does GCDS use?GCDS uses Google Workspace APIs to sync your directory data to your Google Account. The APIs use OAuth, not an admin's password, to authenticate. This approach allows features like 2-Step Verification (2SV) to remain active without impacting GCDS functionality.
GCDS uses the following APIs:
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.
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. For details, go to Overview: Set up and manage the Directory.
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.
Yes. You can use GCDS to sync from one LDAP directory to multiple Google accounts by using more than one configuration file. If you run multiple syncs 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.
GCDS follows the conflicting accounts management settings that you set up in the Google Admin console. For details, go to Manage conflicting accounts with GCDS.
Syncing users & organizational units
Expand section | Collapse all & go to top
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.
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
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 that the users' mail addresses in your LDAP server match 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 a user alias domain or secondary domain.
Yes, as long as the LDAP server supports wildcards.
LDAP directories don’t support wildcards in distinguished name (DN) attributes when you’re conducting a user search query. For example, you can use (mail=user*), but not (distinguishedName=*,DC=domain,DC=com).
Yes, if you're using an LDAP server that supports memberOf recursive searches. They're supported by Active Directory, but not by OpenLDAP.
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 from suspending this user in Google Workspace.
-
Problem: The user doesn't have a valid email on the LDAP server.
Solution: You should configure an email address for this user or set a Google user exclusion rule to prevent GCDS from suspending the 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.
Syncing groups
Expand section | Collapse all & go to top
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."
You can configure GCDS to exclude a group by defining a Group Email Address exclusion rule in the Google domain configuration. For details, go to Use rules for Google data.
Example:
Exclude Rule
Type: Group Email Address
Match Type: Exact Match
Rule: GCP_Project1@example.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.
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 added members to the corresponding object or entity in LDAP, GCDS adds those members to the group. If you 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, go to Groups administrator FAQ.
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
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.
You want to sync only members that are active users on the LDAP server. For example, you have Group 1 on the LDAP server, which has 2 members, user1 and user2. User1, however, has been suspended on the LDAP server. Following a sync, Group 1 in your Google Account should contain user2 as the only member, while user1 is suspended (or removed, based on your GCDS settings).
To sync valid group members:
- Locate the configuration file. This is the same XML file that you use to load your GCDS configuration.
- Open the configuration file with a text editor.
- Find and delete the option INDEPENDENT_GROUP_SYNC.
- Search for the option ADD_VALID_GROUP_MEMBERS_ONLY.
If it doesn't exist, add it to the file.
- Ensure that the user accounts sync is turned on.
For details, go to Define your user list.
- Run simulation to verify the results before you run a full sync.
General
Expand section | Collapse all & go to top
How do I add an optional feature flag to the GCDS configuration file?Before you begin: Make sure that GCDS supports the feature.
- Locate the configuration file. This is the same XML file that you use to load your GCDS configuration.
- Open the configuration file with a text editor.
- In the XML file, locate the <features> tag, and insert a new line inside the tag.
- In the new line, add a new <optional> tag with the name of the feature inside it.
- Save and close the file.
Example
The following example shows how to add the DONT_RESOLVE_USER_CONFLICT_ACCOUNTS feature.
<features>
<optional>DONT_RESOLVE_USER_CONFLICT_ACCOUNTS</optional>
</features>
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 Google 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.
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.
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.
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
During a sync GCDS considers the current LDAP setup 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:
<schemas>
<schemaDefinitions />
<schemaHistory>
<schemaName>GroupMembership</schemaName>
</schemaHistory>
</schemas>
The symmetric key that 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 the 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 that customers follow best practices to ensure that the key is properly secured by both using an encrypted file system and ensuring restrictive ACLs.
The unique ID (also referred to as the non-address primary key) is used internally by GCDS and isn't synchronized to Google Workspace. GCDS stores the unique ID in a TSV file on the computer on which GCDS is installed. You can find the TSV file name and its full path in the XML configuration file.
If a user is renamed on the LDAP server but not in Google Workspace, GCDS uses the unique ID to prevent the user's details from being deleted or duplicated.
Note: You might cause sync issues if you manually change the user's email addresses on both the LDAP server and Google Workspace. To avoid this issue, remove the corresponding user records from the TSV file before you run GCDS.
Google Cloud
Expand section | Collapse all & go to top
How can I synchronize security groups from Active Directory or my LDAP directory & 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 GoogleCloud. You can then refine the GCDS query to provision only 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:
(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=-2147483648)(mail=*)(extensionAttribute1=GoogleCloud))
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.
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:
(&(memberof=cn=CloudUsers,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 suspended:
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, go to 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, go to Sync licenses.
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.
