Tuesday, February 7, 2012

Google Apps Directory Sync - a beginners guide

A more up to date version of this article is now available, this copy here for reference only.

As a Google Apps provider, I've been working a lot with Google Apps Directory Sync (GADS) of late. The tool is intended to help institutions provision their accounts in Google Apps by automatically syncing data from the local directory servers (normally AD, but it can be other LDAP compliant directories too).

It's a tool that comes with a fair whack of documentation, and does require a good understanding of LDAP to make most of it, but once configured it leaves you with a highly automated process for maintaining your Google Apps domain accounts. More detailed information if required is found at: http://www.google.com/support/enterprise/static/gapps/docs/admin/en/gads/2.1.6/admin/toc.html

For less complex sites I've put together this quick guide. It assumes you are using Active Directory on a Windows based server and are happy to make changes to your directory. For more complex sites or if you'd prefer not to make these changes, GAPPSCONNECT can set this up on your behalf (remotely or onsite). Call 0843 289 0462 (UK local rates) or fill in our contact form if this is an option you'd like to discuss.
LDAP basics

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.

A more up to date version of this article is now available, this copy here for reference only.

Active Directory server preparation.

1. Create a basic user account on your directory service. Create an account with the username 'gads' (description Google Apps Directory Service). This can have the lowest privilege but must be able to read your directory tree (which most normal accounts will). The password should be complex but set to never expire. A good place for this account is in the users CN.

2. Prepare your directory service. Organize the objects that you want to replicate. A good approach is to create a new OU called 'google accounts' and place the existing OUs that hold the relevant user accounts, groups etc under this tree. Try to avoid a structure that is too deep if you can. This guide assumes you have created a new OU called 'google accounts' which contains the users that you want created on your Apps domain.

Google Apps Directory Sync (GADS) service.

3. Host computer. Find a host computer to execute the sync on a routine basis with. Google advise that you use a separate machine from the domain controller. The operating system can be any recent version of windows or linux, but the hardware should be reliable enough to be left on at all times.

4. Required software. Install Softerra LDAP browser (free) to test connectivity to your directory service and browse the folder structure (this will come in handy during configuration). You can use this to identify object classes and attribute names. The process of syncing involves writing log files to the installation directory. so be sure to install the GADS software to a folder that your account has write access to! If you install it to 'program files' then you will need to run the program as an administrator which you may not want to do.

GADS configuration.

GADS allows you to build up a sync config file using a graphical interface. You will need to define the general settings (where your AD is for example) and explicitly state which parts of the directory you want to replicate to Google Apps.

5. General Settings. If you have an OU called 'google accounts' you can choose to sync LDAP org units and have all subunits sync too. This saves you having to change settings at a later date and will allow you to create or remove OUs within google accounts and have them replicated to Google. Start off by only syncing users and groups. Once you've got that working, you can choose the other options.

6. Google Apps. Use this screen to tell GADS about your Google Apps domain. This screen should be self-explanatory, but refer to the learn more link if not.

7. LDAP. Connect to your directory server using the gads account created in step 1. Set the base DN to the lowest level of unit that you plan to sync from. Be careful not just to specify the top level domain because the sync will try to replicate system accounts and will have permission issues connecting. If you have followed the suggestion and created an OU called 'Google Accounts', then the configuration will be as follows:

GADS - LDAP connection screen

8. Org units. This is where you define the org units that you want to replicate. Note: you are defining just the unit names (not the objects within them) that you are replicating. Use a separate entry for each OU that you want to replicate. If you have a 'google accounts' OU you can choose to replicate the base DN (indicated in step 7) and not worry about an over-ride or multiple lines. You will need to define a mapping too, also shown below.

GADS - LDAP org search rules

GADS - LDAP org unit mappings

9 Users. The mail address attribute in AD is normally 'mail'. The aliases are normally defined by 'proxyAddress'. givenName and sn are also used. Be sure to tick the 'do not suspend or delete admin accounts'. This is very important to avoid you deleting your domain admin account on Google Apps when they do not exist on AD!

GADS - user attributes

9a. Add two search rules. One to match all users and have them replicate, the other to suspend those who are suspended. Make sure they are in the order shown. The filter for suspended accounts in AD is:


10. Groups. The groups search rules requires you to map to group attributes and filter for the objectClass 'groups'

11. Simulate. At this stage you should be able to define notifications, sync limits, and log file parameters in preparation for a simulated sync. If successful, move on to syncing contacts and calendar resources by following the same approach.

A more up to date version of this article is now available, this copy here for reference only.


  1. This comment has been removed by the author.

  2. Thanks for your blog post!

    I'm provisioning a group of users via GADS and the forest is relatively flat where the domain components(dc=example,dc=com) had all the OUs right under it. I pointed GADS at the Base DN for the Domain Components (dc=example,dc=com) and I kept receiving an "exception while processing" error.

    Unfortunately the log (even in TRACE level) didn't give me much to go on besides the following:
    [FATAL] [page.general.AbstractSimulateSyncWorker$WorkerStatusLogger] Exception while attempting to retrieve results
    java.lang.RuntimeException: javax.naming.PartialResultException [Root exception is javax.naming.CommunicationException: example.com:389 [Root exception is java.net.UnknownHostException: example.com]".

    Usually we use two top level orgs 1) Google and 2) Legacy, but in this case we were just doing provisioning without any thoughts on mail routing so we didn't see a need to create these top level orgs.

    Thanks! The Google documentation doesn't call this out super clear and your blog came right to the top on this issue.

    1. Thanks for this. Really pleased it helped!

  3. I sync an OU called Medical the users status IN GOOGLE APPS was newly created but when i sync the other OU then the status of Medical OU users got Suspened . Why ? please reply

  4. Hi Syed,
    Your new search rule does not include Medical OU users so directory sync has decided they don't exist and applied the suspend user rule that you applied. You need a separate search rule (in the same config file) for each OU. The alternative is to create a parent OU for both Medical OU and the other OU. Hope this helps,

    1. ps. A more up to date version of this document is now available at: http://thirdwayit.blogspot.co.uk/2012/05/introduction-to-google-apps-directory.html


Thanks for your comment!