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.