Tuesday, May 15, 2012

Introduction to Google Apps Directory Sync (GADS) by example - a beginners guide


This article is intended to help first time users of Google Apps Directory Sync which allows for the automatic provisioning of user accounts to Google Apps from your directory service. A more detailed explanation of the software is available online in the administration guide but this should be enough to perform a basic sync of users and groups from Microsoft's Active Directory on Windows Server 2000, 2003 or 2008.

This article is published by Gappsconnect, a Google for Work Partner  based in the UK. Please contact us if you have any questions or would like to discuss the use of a specialist to undertake this work on your behalf.


1. Active Directory structure. The job of synchronising user accounts is made much easier if the users and groups that you are planning to sync belong to a common organizational unit (OU). If you have your users spread across multple OUs, consider creating a a parent OU called 'Google users'. It is not possible to sync user accounts unless they are in an OU.

LDAP refresher (skip this part if you know it already)
Before starting, remind yourself about directory services (called Active Directory or AD on windows) and the use of LDAP (Lightweight Directory Access Protocol). GADS uses LDAP queries to extract the required information from your directory. A good understanding of terms and acronyms will help!
DC: Domain Component. This describes your domain. For example, the domain example.com would be described in directory services as dc=example,dc=com
OU: Organization Unit. Organizes your directory into a tree structure (nested folders). Typically, you will have separate OUs for users, computers, etc, but also have OUs to help distinguish types of users. You might for example have a separate OU for power users. These will vary site-to-site depending on the preferences of the domain administrator. This is an excellent way to organize the user accounts that you want to replicate to Google Apps. If they are in a distinct OU, the job of syncing becomes much easier.
CN: Container Name. Think of this as a built in OU. Active directory has a CN called users for system user accounts for example. These are usually not replicated to Google Apps. 
DN: Distinguished Name. The path of tree containing the objects that you are interested in. (Example ou=visitors,ou=2012,dc=example,dc=com is the DN to use if you are only interested in objects held in the OU called visitors which in part of the OU called 2012). 
object class: Object classes describe the objects stored in directory services. The most commonly used objects in active directory (and relevant to GADS) are users and groups.
Attributes. Each object will have any number of attributes. For example a user will typically have sn for surname and givenName for their given name. 
A typical LDAP query:
This query would find all users who are in the OU called 2011 at example.com. Several good articles are available if you type 'LDAP query language' into your search engine and these may come in handy as you build your GADS config file, although variations on the given example above should suffice for a straightforward sync.

2. Active Directory user account. Create a separate, empty, top level OU in your directory called 'Google sync' and add a standard user account to it called ldap_user. This will be used to look up your directory during the sync. Set it to have a non-expiring password so that you can run scheduled syncs. The account does not require admin privilege as it is only performing directory look ups.

3. Google Apps admin account. Create an account in your Google Apps domain called ldap_sync and give it admin rights so that it can create and delete accounts in the domain.

4. Provisioning API. Switch on the provisioning API in your Google Apps domain control panel. This is found in 'domain settings > user settings'

Configuring Google Apps Directory Sync

5. Install GADS. Download the program and install it to a directory that you have write access to (not program files). http://support.google.com/a/bin/answer.py?hl=en&answer=106368

6. Open the Configuration Manager. This is a GUI that helps you build the XML configuration file that will be used to carry out the synchronization. Each menu item has multiple tabs that you should review before saving. The first menu item, General Settings, is where you declare what you plan to synchronize. I recommend you only start with the first three options.

7. Configure Google Apps connection. Use the ldap_sync account created in step 3 to connect. Use OAuth token for secure authentication in preference to the username and password.

Tick 'replace domain names' if the domain name of your AD is different to your Google Apps domain.

Use second tab if you have a proxy server. You can use the third tab to protect any Google Apps users from deletion when the sync takes place (if they are not present in AD).

8. Configure LDAP connection. Use the account created in step 2 to connect to your AD. This step will only work if you have a Base DN that includes an organizational unit; If you have created a parent OU this should be your Base DN.

9a. Configure Organizational Units (mapping). Use the distinguished name (DN) of the parent OU container that you have created for your users and groups and map it to the Organizational Unit name that you would like to use in Google Apps (it will create this for you).

All child organizational units will be synchronized.

9b. Configure Organizational Unit (search rule). The rule for finding all organizational units within the base DN is 'objectclass=organizationalunit'

10a. Configure user accounts (attributes). You need to map user attributes in AD with those required to create accounts in Google Apps.

Because some users may not have an email address defined, the 'userPrincipalName' attribute is useful for defining the mail address in Google Apps. The domain name will be substituted in Google Apps if you ticked the box in step 7.

If you plan to use AD to manage your user accounts, you will want accounts that are deleted from AD, deleted from the Google Apps domain too.

10b. Configure user accounts (additional attributes). You will need to know the given name and surname attributes to create Google Apps accounts. These are usually givenName and sn. Note that it is not normally possible to sync AD passwords using GADS, but a separate product called Google Apps Password Sync is available now to do this.

10c. Configure user accounts (search rule for active accounts). The first rule will find all active (non-suspended) user accounts. This can be achieved with the search rule:


10d. Configure user accounts (search rule for suspended accounts). The second rule will find all suspended user accounts and can be used to ensure Google Apps accounts are suspended if marked as such in Active Directory. The rule syntax is:


Make sure you tick the 'Suspend these users' box!

10e. Review search rules. You should have two rules, one for active accounts, one for suspended accounts.

11. Define group search rules. The search rule to find defined groups in your AD is:

objectclass=group. You will also need to declare the member reference attribute (normally member), group email address attribute (normally mail), display name (normally name), description (normally description) and the owner (normally managedBy)

12. Finally. Define your notifications, sync limits and logging preferences.

Congratulations. You have configured Google Apps Directory Sync and you should be able to perform a test sync to ensure the appropriate changes will be made. Once this has been done you will want to consider synchronizing other information and performing scheduled synchronization. This is documented in the administration guide.

Ray Allen. All rights reserved. Please use comments to let me know how you find this guide, or contact me at GAPPSCONNECT with any questions.


  1. Great how-to article on Google Apps sync. It helped me out greatly where the instructions and examples supplied by Google were pathetic.
    However a major problem for me that is not discussed or explained anywhere is how to sync MS Exchange Query-based distribution groups...aka Dynamic Distribution Groups. How do you import these into Google Apps with their members?

    1. Thanks for your comment - I'm pleased the article helped. I've not performed a sync on dynamic distribution groups using GADS, so I'm not sure if it's possible. An alternative approach would be to script a separate query to return the dynamic group data and upload it using the Google Apps provisioning API. See: https://developers.google.com/google-apps/provisioning/#methods_for_groups

  2. I see that update 3.1.3 now includes support for dynamic groups. http://googleappsupdates.blogspot.co.uk/2012/07/google-apps-directory-sync-313-update.html

  3. Just wanted to send a note to say thanks for a great troubleshooting article. Your notes related to configuring user accounts was invaluable for our environment. Will certainly bookmark your site for other great articles.

  4. j missing from obectclass=organizationalunit, if you, like me, copy and paste, it'll fail

  5. Great Article - One question I have is how do I prevent accounts from being suspended. I have a few accounts in my Google apps that I use for generic use. Do I need to create an AD Account for these?

  6. Thanks. You can specify exceptions which will enable you to create accounts on Google Apps that won't be touched by the GADS sync. In addition to this you can specify that GAPS doesn't include administrative accounts in the sync.

  7. I have many ex-students user accounts no longer in AD at our college and we allow the students to keep their Google mail account. My problem is that when the sync runs it wants to either delete or suspend those accounts not found in AD is there a way to stop this?

    1. You should suspend the account on AD rather than delete it and configure GADS to keep the account. Hope this helps.

  8. Thanks for the article, as a GADS newbie this has really helped to explain things. One question though, how do you configure GADS to keep the account? I have only seen options to delete or suspend accounts not found in LDAP query results.

  9. You mentioned above to "[not install GADS] program files", yet page 48 of the Admin Guide shows that directory. What is the issue you see here?


    1. In the past I've had problems with permissions and GADS not executing properly unless the user has admin rights. I've found the best way round this to not install to program files but use a different directory altogether. Maybe Google have fixed this issue now.


Thanks for your comment!