User Provisioning and Syncing (LDAP - Google Apps)

1. Google Apps Directory Sync
Administration Guide
Release 3.0.6

2. Google, Inc.
1600 Amphitheatre Parkway
Mountain View, CA 94043
www.google.com
Part number: GADS_3.0_36
March 21, 2012
© Copyright 2012 Google, Inc. All rights reserved.
Google, the Google logo, Google Message Filtering, Google Message Security, Google Message Discovery, Postini, the
Postini logo, Postini Perimeter Manager, Postini Threat Identification Network (PTIN), Postini Industry Heuristics, and
PREEMPT are trademarks, registered trademarks, or service marks of Google, Inc. All other trademarks are the property of
their respective owners.
Use of any Google solution is governed by the license agreement included in your original contract. Any intellectual property
rights relating to the Google services are and shall remain the exclusive property of Google, Inc. and/or its subsidiaries
(“Google”). You may not attempt to decipher, decompile, or develop source code for any Google product or service offering,
or knowingly allow others to do so.
Google documentation may not be sold, resold, licensed or sublicensed and may not be transferred without the prior written
consent of Google. Your right to copy this manual is limited by copyright law. Making copies, adaptations, or compilation works,
without prior written authorization of Google. is prohibited by law and constitutes a punishable violation of the law. No part of
this manual may be reproduced in whole or in part without the express written consent of Google. Copyright © by Google, Inc.
Google, Inc. provides this publication “as is” without warranty of any either express or implied, including but not limited to the
implied warranties of merchantability or fitness for a particular purpose. Google, Inc. may revise this publication from time to
time without notice. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions;
therefore, this statement may not apply to you.
This software uses the JGoodies Forms, JGoodies Validation, and JGoodies Looks.
Copyright (c) 2002-2008 JGoodies Karsten Lentzsch. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
conditions are met:
o Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the distribution.
o Neither the name of JGoodies Karsten Lentzsch nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL Release 3.0.6DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
This software uses Apache Derby.
Apache Derby
Copyright 2004-2007 The Apache Software Foundation
2 Release 3.0.6

3. This product includes software developed by
The Apache Software Foundation (http://www.apache.org/).
Portions of Derby were originally developed by International Business Machines Corporation and are licensed to the Apache
Software Foundation under the “Software Grant and Corporate Contribution License Agreement”, informally known as the
“Derby CLA”.
The following copyright notice(s) were affixed to portions of the code with which this file is now or was at one time distributed
and are placed here unaltered.
(C) Copyright 1997,2004 International Business Machines Corporation. All rights reserved.
(C) Copyright IBM Corp. 2003.
The portion of the functionTests under 'nist' was originally developed by the National Institute of Standards and Technology
(NIST), an agency of the United States Department of Commerce, and adapted by International Business Machines
Corporation in accordance with the NIST Software Acknowledgment and Redistribution document at
http://www.itl.nist.gov/div897/ctg/sql_form.htm
3

4. 4 Release 3.0.6

5. Contents
About This Guide 9
What This Guide Contains 9
Related Documentation 9
How to Send Comments About This Guide 10
Chapter 2: Overview of Google Apps Directory Sync 11
What Is Google Apps Directory Sync? 11
How Directory Sync Works 12
What Is Synchronized 13
Directory Sync and Deployment 15
System Requirements 19
Chapter 3: Getting Started 23
Overview 23
Step One: Install LDAP Browser 24
Step Two: Collect LDAP Inventory 25
Step Three: Decide What to Synchronize 29
Step Four: Prepare Google Apps for Synchronization 41
Step Five: Prepare Your Servers for Synchronization 42
Further Steps 43
Chapter 4: LDAP Queries 45
About LDAP Queries 45
Syntax 45
Common LDAP Queries 46
Chapter 5: Installation 49
About Installation 49
Install Google Apps Directory Sync 49
Upgrade Google Apps Directory Sync 51
Uninstall Google Apps Directory Sync 51
Chapter 6: Configuration 53
About Configuration 53
Configuration Files 54
Contents 5

6. General Settings 55
Google Apps Configuration 57
Google Apps Connection Settings 58
Google Apps Proxy Settings 61
Google Apps Exclusion Rules 63
LDAP Configuration 69
LDAP Connection Settings 70
LDAP Org Units 71
Org Unit Mappings 72
Org Unit Search Rules 75
Org Unit Exclusion Rules 77
User Accounts 81
User Attributes 82
Additional User Attributes 83
User Search Rules 88
User Exclusion Rules 92
Groups 96
Group Search Rules 96
Group Exclusion Rules 101
User Profiles 104
User Profile Attributes 104
User Profile Search Rules 106
User Profile Exclusion Rules 109
Shared Contacts 112
Shared Contact Attributes 114
Shared Contact Search Rules 116
Shared Contact Exclusion Rules 118
LDAP Calendar Resources 121
Calendar Resource Attributes 122
Calendar Resource Search Rules 124
Calendar Resource Exclusion Rules 126
Notifications 130
Sync Limits 132
Logging Settings 134
Sync 135
Chapter 7: Synchronization 139
About Synchronization 139
Synchronizing from the Configuration Manager 139
Command Line Synchronization 139
Scheduling Synchronization 141
Monitoring 143
Chapter 8: Troubleshooting 145
About Troubleshooting 145
Troubleshooting With Log Files 145
Common Issues 145
System Tests 149
6 Release 3.0.6

7. Escalating Problems 150
Contents 7

8. 8 Release 3.0.6

9. About This Guide
What This Guide Contains
The Google Apps Directory Sync Administration Guide provides information
about:
• Google Apps Directory Sync features
• Basic steps for installing Directory Sync on your server
• Configuration for Directory Sync
• Synchronizing users, groups, and shared contacts
• Troubleshooting Directory Sync
This guide is intended for administrators who are already familiar with Google
Apps and with LDAP directory servers.
Related Documentation
For additional information about Google Apps and about related products, refer to
the following documents.
Document Description
Directory Sync Admin Help Central page for Google Apps Directory Sync.
Page Includes a description of the product, as well
as available downloads. Get the latest
download here.
Google Apps Admin Help Help Center for Google Apps. This includes
documentation and support for the entire
Google Apps suite, including Google Apps,
Mail, and Google Apps Directory Sync.
9

10. Document Description
Google Apps Directory Sync Release Notes for Google Apps Directory
Release Notes Sync. This is kept up to date with the changes
in the latest version, including release
schedules, new features, resolved issues, and
known behavior changes.
Google Apps Directory Sync Another version of Google Apps Directory
for Email Security Sync. Google Apps Directory Sync for Email
Security synchronizes with Message Security
and Delivery (powered by Postini) instead of
Google Apps.
How to Send Comments About This Guide
Google values your feedback. Please send comments about this guide to:
enterprise-apps-doc-feedback@google.com
Please specify in your message the section to which your comment applies.
10 Release 3.0.6

11. Chapter 2
Overview of Google Apps Directory Sync Chapter 2
What Is Google Apps Directory Sync?
Google Apps Directory Sync (also called Directory Sync or GADS) is a utility that
adds, modifies, and deletes your users, OUs, groups, shared contacts, and
calendar resources in Google Apps to match your LDAP directory server. When
you synchronize, Google Apps changes to match your LDAP directory.
Use GADS to synchronize information so that your Google Apps organizations,
users, groups, and shared contacts are automatically kept up to date with your
LDAP directory server.
GADS runs on your server, and updates Google Apps to match your LDAP
directory. Directory Sync never updates or changes your LDAP directory
information.
Important Notice
Before you enable GADS for your organization, please keep a few things in mind:
If Google Profiles is enabled for your organization, the data synced from your
institution’s directory will be auto-populated into the Google Profile, which your
end user may then choose to publish publicly on the web. Your use of Google
Apps Directory Sync may in some cases override the user’s edits to their own
profile fields -- please communicate this to your end users if you have enabled
Google Profiles for your organization or if you do so in the future.
Customer acknowledges and agrees that Customer is solely responsible for
complying with all laws and regulations that might be applicable to Customer’s
provision of Google Profiles to Customer’s end users, such as the U.S. Family
Educational Rights and Privacy Act of 1974 (FERPA), Children’s Internet
Protection Act (CIPA), and the Children’s Online Privacy Protection Act of 1998
(COPPA).
Overview of Google Apps Directory Sync 11

12. How Directory Sync Works
This section discusses how GADS synchronizes your LDAP data into Google
Apps.
Technical Overview
GADS includes two connected tools: Configuration Manager and the sync-cmd
synchronization command line utility.
Configuration Manager is a GUI-based wizard that walks through the steps of
configuring a synchronization. In Configuration Manager, you set up what data to
synchronize, specify LDAP query rules, list which attributes contain the
information you want to synchronize, specify server connections, and note any
exclusion rules. The Configuration Manager utility allows you to test your settings,
and stores information in an XML file that is then used by the sync-cmd utility.
The sync-cmd is a command-line utility that performs the actual synchronization.
You can use the sync-cmd utility to update Google Apps data. The utility is
designed to be run from a command line so that you can use your server’s task
scheduling to run a scheduled synchronization.
Data Flow
The following steps describe how the data flow of GADS works.
1. GADS connects to your LDAP server and generates a list of users, groups,
and shared contacts on your directory. You can set up rules to specify how
this list is generated.
2. GADS connects to Google Apps and generates a list of users, groups, and
shared contacts in Google Apps. You can set up rules to specify how this list
is generated.
3. GADS compares these lists, and generates a list of changes.
4. GADS then updates Google Apps to match your LDAP server settings.
After GADS has finished synchronization, it sends a report of results to email
addresses that you specify.
12 Release 3.0.6

13. Security
GADS has the following security features:
• It runs inside your network, on a machine you control.
• It connects to your LDAP server inside your network through Standard LDAP
or secure LDAP + SSL. This connection occurs on any port you specify, but
defaults to standard LDAP ports.
• It connects to Google Apps through the Internet via HTTPS on port 443. This
connection can also run through a proxy host in your network.
• It connects to a mail server inside your network using standard (non-TLS)
SMTP.
• It does not store LDAP data on the Directory Sync machine. Directory Sync
stores connection details, configuration files, and event logs on the Directory
Sync server, but does not store any LDAP data. All LDAP data is
synchronized with Google Apps and stored as user information on Google
Apps secure servers.
• It caches some Google Apps information locally on your Directory Sync
server.
What Is Synchronized
The chart below details what gets synchronized by GADS, the equivalent terms
between LDAP and Google Apps, and notes on what is and is not synchronized.
.
LDAP Google Apps Synchronizes Notes
Org Units (OU) Organizations Organizations in Google Apps contain multiple
users. Organizations can be used to structure
users by department, location, or other
categories. You can synchronize org structure
automatically, or manually by each
organization.
Mailing Lists Groups Mailing lists in LDAP correspond to public
groups in Google Apps. Groups can also be
used to control access to sites and
documents.
Google Apps users can also create private,
user-managed Groups. These are not altered
or synchronized by Google Apps Directory
Sync.
User Users In Google Apps, users are organized by email
address, not LDAP Distinguished Name.
Overview of Google Apps Directory Sync 13

14. LDAP Google Apps Synchronizes Notes
User Aliases Nicknames Other email addresses also used by a given
primary address. Each user can have multiple
nicknames in Google Apps, and these can
come from multiple LDAP alias attributes.
Passwords Passwords GADS can only synchronize passwords that
are stored in SHA-1 or MD-5 format with no
salted hashes. Alternatively, passwords can
be managed separately, or authentication can
be handled by SSO (Single Sign-On).
For more information on Passwords, see
“Passwords” on page 34.
Messages and Messages and calendar data are not migrated
Calendar Data with GADS. If you need to migrate your legacy
messages and calendar data, use a migration
tool, such as Google Apps Migration for Lotus
Notes, or Google Apps Migration for Microsoft
Exchange (which also migrates data for other
IMAP servers.)
Rooms Calendar Calendar resources, like rooms and
Resources projectors, can be synchronized from your
LDAP directory into Google Apps.
Contacts Shared An LDAP Contacts list corresponds to Google
Contacts Apps Shared Contacts. Shared Contacts are
visible as autocomplete options when users in
Gmail start typing an email address. Personal
contacts are not synchronized. Shared
Contacts appear in autocomplete about 24
hours after synchronization.
Personal Contacts Personal GADS does not synchronize personal
Contacts contacts. If your users wish to import personal
contact information, they can use client-based
migration tools like Google Apps Migration for
Microsoft Outlook.
Extended User User Profiles Extended LDAP information, like phone
Information numbers and addresses, can be synchronized
into Google Apps as rich User Profiles.
Shared Folders None Google Apps does not include an equivalent
to shared folders. Users typically share
information in Google Apps by sharing Google
Docs or through Groups.
14 Release 3.0.6

15. Directory Sync and Deployment
GADS can be used during different stages of the Google Apps deployment cycle.
This section discusses the three-phase deployment model recommended for
implementing Google Apps, and how Directory Sync fits into this model.
For a tutorial on the three-phase deployment model, see the video Planning Your
Google Apps Deployment.
The Three-Phase Deployment Model
The methodology described in this section is based on field studies and real-world
deployment experience with Google Apps. The goal of this model is to accomplish
a Google Apps deployment quickly and give users the best possible customer
experience.
Deployment is typically divided into three phases, plus planning beforehand and
maintenance afterward.
The following steps are described in more detail below.
• Plan: Before you begin with your Core IT phase, take time to learn about
Google Apps, plan for your deployment, and secure resources.
• First Phase: Core IT: Core IT department users are activated on Google
Apps.
• Second Phase: Early Adopter: A small number of early adopters are
activated with Google Apps and use it for regular business functions.
• Third Phase: Global Go Live: All users are activated in Google Apps.
• Maintenance: After your Global Go Live date, ongoing maintenance involves
keeping up services, monitoring to detect any issues, and updating for
changes to your organization such as departing users, new hires, and name
changes.
Variations for Different Organizations
These steps may vary for your environment. If you are administering an
organization with fewer than 500 users, you may decide to add your Core IT and
Early Adopter users at the same time, and combine these two phases.
Overview of Google Apps Directory Sync 15

16. If you have already added users through another method, and begin using GADS
afterwards, you may move directly to Global Go Live and continue through
maintenance. In this case, you would not set up a Core IT or Early Adopter phase,
and you would set up GADS to synchronize your users and maintain Google Apps
to match your LDAP data going forward.
Plan
Users: No users added yet.
Before you begin with the Core IT phase, there’s a period of preparation and
planning. During the Plan step, the goal is to understand the services available,
learn technical details, decide what tools to use, identify any need for outside
consulting or support, and set a plan for implementing Google Apps.
Directory Sync: During this phase, begin making preparations for Google Apps.
Specific preparations you can make at this stage include the following.
• Prepare a provisioning strategy.
• Secure LDAP resources.
• Clean up your LDAP directory.
• Prepare your firewall/proxy settings and network ports to ensure that Directory
Sync has a connection to your LDAP directory and to Google Apps.
Fore more information on these preparations, see “Getting Started” on page 23.
Core IT
16 Release 3.0.6

17. Users: A small number of manually added users.
In the Core IT phase, a small number of IT users activate in Google Apps and
begin learning and configuring Google Apps. The goal of the Core IT phase is to
learn how to use the applications and utilities, to configure services, and to
prepare for Early Adopters.
Directory Sync: During this phase, continue preparation and testing to be ready
for Directory Sync implementation by the Early Adopter phase.
Typically, GADS is not used to import users for the initial IT pilot, since it is easier
to add your initial IT department users either manually or by uploading a CSV file
into the Google Apps control panel.
If you do have manually added users that are not in your LDAP, remember to add
exclusion rules so those users are not deleted.
Early Adopter
Users: Early adopter business users, either manual or synchronized.
During the Early Adopter phase, set up a small number of active users and give
them the best possible user experience. Early adopters can then become familiar
with Google Apps, identify any common questions or issues, and learn to use the
product so that they can help others after a broader rollout.
Directory Sync: During the Early Adopter phase, prepare your synchronization
rules so that full synchronization will be ready on your Global Go Live date.
Optionally, you can also set up GADS to synchronize data for early adopters. You
can use any of these features for Early Adopter synchronization:
1. You can use GADS during your Early Adopters phase to synchronize your
entire user list, so that your Early Adopter users can see recipient addresses
in Autocomplete when sending mail. You can synchronize users as shared
contacts, or synchronize as full users without sending passwords or routing
users’ mail into Google Apps.
2. If you are running the Early Adopter phase on a separate test domain, GADS
can synchronize users to a test domain, adding users with the same
username in a separate test domain.
3. If you are using Postini Message Security, you can set up Postini for split
delivery, so that Early Adopters receive mail in Gmail while other users
receive mail on your legacy server.
Overview of Google Apps Directory Sync 17

18. Global Go Live
Users: All users active in Google Apps.
In the Global Go Live phase, all users become active and begin using Google
Apps for daily business. Mail flow is routed entirely to Gmail, users schedule their
activities in Google Calendar, and day-to-day user activities run in Google Apps.
After your Global Go Live date, data from legacy systems may be migrated into
Google Apps, or may be left on legacy servers and checked when needed.
Directory Sync: You can set up GADS to import organizations, users, aliases,
profile information, groups, contacts, and calendar resources so that your Google
Apps account is populated with the same data you have on your LDAP directory
server.
Prepare for your Go Live date. The initial synchronization of a Go Live date can
take several cycles of configuration and tests, since there may be a great deal of
data to synchronize. Be prepared for an extended synchronization, and try to run
your synchronization during off-business hours to avoid consuming network and
system resources during peak hours.
Note also that shared contacts can take up to 24 hours after synchronization to
show up in Gmail autocomplete.
During your rollout, you may decide to split your synchronization into phases to
avoid exceeding any search size limits on your directory server.
Maintenance
Users: Updated to maintain changes between your LDAP directory and
Google Apps.
After you have set up Google Apps and your users are live with the product,
continue to update Google Apps to reflect any changes on your LDAP directory.
18 Release 3.0.6

19. If you remove any users from your company, update Google Apps to reflect these
changes. Many companies remove a user by changing the user’s password and
access permissions, rather than deleting the user from Google Apps, in order to
smoothly handle the user’s documents and mail archives.
Directory Sync: Check your notification messages regularly to be sure that
GADS is running smoothly, and to detect and address any issues that arise.
You can use GADS to keep your Google Apps directory up to date. You can set up
GADS to run scheduled synchronization, so that all changes to your LDAP
directory server are synchronized with Google Apps. Any changes to your LDAP
directory server, such as new users, deleted users, or users moved to new
organizations, will be reflected in Google Apps.
Also, during maintenance, be sure to check regularly for updates to GADS. You
can check for new updates by opening Configuration Manager, or by running the
command checkforupdate.exe.
Depending on your needs, you may run scheduled synchronizations at different
rates. Usually, this ranges between once an hour and once a day. Be aware that
running synchronization too often may use up excess bandwidth or exceed
quotas.
System Requirements
Before you begin using GADS, be sure you can meet the following system
requirements.
Google Apps Account
• A Google Apps domain running Google Apps for Business, Google Apps for
Partners, Google Apps for Government, or Google Apps for Education.
Note: GADS only synchronizes primary domains, not domain aliases.
• An administrator account on your Google Apps domain, set up in the Google
Apps control panel. You can also set up an OAuth key while configuring
Google Apps if you have administrator login information.
• Provisioning API enabled on your Google Apps domain. For steps on how to
do this, see “Enable APIs” on page 42.
Overview of Google Apps Directory Sync 19

20. Server Requirements
• A server to run GADS. The server should run one of the following operating
systems:
• Microsoft Windows (supported on XP, Windows 7, Windows Server 2003/
2008)
• Linux
• Solaris (version 8+, no support for x86)
• If using 64-bit Linux systems, a 32-bit libc (such as libc6-i386) must be
installed.
• At least 5 GB of disk space for log files and data. If you are running with
DEBUG or INFO level of logging, you may need more free space than this for
additional log data.
• At least 256 MB of free RAM. At least 1 GB of free RAM is recommended if
you have less than 10,000 users, or 2 GB of free RAM if you have more than
10,000 users. For very large organizations (over 250,000), further tuning may
be needed.
• An LDAP server with user information which is accessible to GADS. All
versions of the LDAP protocol are supported.
• Network access to your LDAP server. You do not need to run GADS on your
LDAP server.
• Read and execute administrative access over the appropriate OU structure of
the LDAP server.
• An LDAP browser that can read and browse your LDAP directory server data.
• Network access to the Google Apps through HTTPS, directly or through a
proxy server. This includes ports 80 and 443.
• For best results, a network connection to Google Apps with no proxies or
firewalls is recommended.
• A mail server able to accept and relay notifications from Directory Sync.
• Access to SSL Authorities for your network.
Level of Effort and Expertise
The level of effort for using GADS will vary based on the scope of your
synchronization plans, your familiarity with the LDAP query language, and your
familiarity with your own LDAP directory server and data.
In many cases, the initial configuration of GADS includes multiple revisions of
synchronization rules, updating and refining your LDAP synchronization rules until
a simulated sync delivers expected results.
20 Release 3.0.6

21. Depending on your configuration, you may need the following levels of expertise
for implementing GADS:
• Google Apps administrator: Access to your Google Apps administrator
account and familiarity with the Google Apps control panel.
• LDAP administrator: Access to your directory server and familiarity with its
contents. Familiarity with LDAP query language.
• Network administrator: Familiarity with your network and security settings
for internal and outbound traffic.
• Mail administrator: Access to a mail server able to relay messages for
Directory Sync notifications. Familiarity with setting up mail servers for traffic.
• Human Resources contact: Familiarity with user base and ability to identify
which LDAP entries represent current employees.
Overview of Google Apps Directory Sync 21

22. 22 Release 3.0.6

23. Chapter 3
Getting Started Chapter 3
Overview
This chapter discusses the steps you’ll take when you get started with Google
Apps Directory Sync (GADS). Your GADS configuration will be faster and
smoother if you collect information about your network, LDAP directory server,
LDAP data, and synchronization plans before you begin. This chapter also
includes necessary steps for setting up your Google Apps account and your
internal network before you install GADS.
For a more successful synchronization, follow the steps detailed below.
Getting Started Steps
The following list describes typical steps for preparing, planning, and
implementing GADS.
Note that these steps do not correspond precisely to the three-phase model
described in the previous chapter in “Directory Sync and Deployment” on
page 15. In most cases, you will begin these steps during the Planning or the
Core IT phases of deployment, so that you will have synchronization ready during
the Early Adopter phase.
For details on system requirements and prerequisites, see “System
Requirements” on page 19.
1. Install LDAP Browser. Download an LDAP browser to examine your current
LDAP directory server. For more information, see “Step One: Install LDAP
Browser” on page 24.
2. Collect LDAP Inventory. Identify your LDAP resources, including LDAP
servers and expert administrators. Collect required information about your
LDAP server and your Google Apps domain. For more information, see “Step
Two: Collect LDAP Inventory” on page 25.
Getting Started 23

24. 3. Decide What To Synchronize. Decide what domains to synchronize. Plan
which users, aliases, and groups you want to synchronize with Google Apps.
This can be a very significant step, and may require a great deal of planning.
For more information, see “Step Three: Decide What to Synchronize” on
page 29.
4. Prepare Google Apps For Synchronization. Make any needed changes to
Google Apps. For more information, see “Step Four: Prepare Google Apps for
Synchronization” on page 41.
5. Prepare Your Server Environment For Synchronization. Confirm that you
have a notification mail server ready. For more information, see “Step Five:
Prepare Your Servers for Synchronization” on page 42.
6. Install Directory Sync. Once you have the needed information, download
and install GADS. This step is covered in “Installation” on page 49.
7. Configure Directory Sync. Run Configuration Manager, part of GADS, to
configure synchronization. This step is covered in “Configuration” on page 53.
8. Simulate Synchronization. Use Configuration Manager to simulate a
synchronization and review the results. This step is covered in “Sync” on
page 135.
9. Revise Configuration. Review the results of the simulated sync. If needed,
revise your configuration in Configuration Manager based on the simulation.
This could take several revisions for complex environments.
10. Preview Synchronization. At the command line, run a synchronization in
preview mode with the configuration file you created. Check the results. This
step is covered in “Command Line Synchronization” on page 139.
11. Manual Synchronization. At the command line, run a manual
synchronization to update Google Apps. The first synchronization, which
imports all information, is likely to take much longer than later
synchronizations. This step is covered in “Command Line Synchronization” on
page 139.
12. Scheduled Synchronization. Using your server’s scheduling tools, set up
automatic scheduled synchronization. This step is covered in “Scheduling
Synchronization” on page 141.
13. Monitoring. Monitor the results of your ongoing synchronization to detect and
address any problems that occur. This step is discussed in “Monitoring” on
page 143.
The first steps, related to preparation, are covered in this chapter below. Later
steps are covered in future chapters as noted.
Step One: Install LDAP Browser
By default, most LDAP directory servers do not include a way to view or modify
your LDAP structure directly. To collect information about your LDAP structure,
download and install an LDAP browser. Two such browsers are listed below.
24 Release 3.0.6

25. Note that these are third-party browsers, and this document does not include
instructions or support on the use of an LDAP browser.
Softerra LDAP Administrator
To download Softerra LDAP Administrator, go to:
http://www.ldapbrowser.com
JXplorer
To download the JXplorer Java Ldap Browser, go to:
http://www.jxplorer.org
Step Two: Collect LDAP Inventory
You can roll out and use GADS more quickly and effectively if you identify your
LDAP resources beforehand. Depending on the size and structure of your
organization, you may already know all this information, or you may need to
conduct significant research.
Identify LDAP Resources
Contact your LDAP administrators and collect the following information:
• The hostname or IP address of your LDAP server. Note that GADS can only
synchronize with one LDAP server.
• Your network access, proxy servers, and outbound connections.
• The name and password of an account on your LDAP with “read” and
“execute” permissions. If you want to limit what users and OUs you want to
synchronize, you can set up an LDAP administrator with limited permissions
on your directory server. See your directory server documentation for steps on
how to do this.
• Confirmation that your chosen LDAP directory has full access to needed
resources.
Getting Started 25

26. If you have multiple LDAP directories, consider the following:
• Consolidate. If you are using multiple directories, consolidate your LDAP
data into a “single source of truth.” Many customers have multiple LDAP
directories, either because of different departments, acquisitions, or
subsidiaries. GADS can only pull data from a single LDAP directory.
• Test Global Catalog. If you have multiple Microsoft Active Directory domains,
a Global Catalog may help with your synchronization, but only if the catalog is
set up with proper replication. If you want to try using a Global Catalog, be
sure to test the catalog thoroughly before relying upon it.
Sample Scenario: Identify LDAP Resources
MobiStep, Inc., is a medium-sized manufacturing company that has moved to
Google Apps and is starting to synchronize an existing LDAP directory server with
Google Apps. The Google Apps administrator contacts the LDAP administrator,
who provides the following information:
• An LDAP administrator account (with appropriate permissions) created
specifically for GADS.
• The IP address and hostname of the LDAP server.
The Google Apps administrator confirms with Human Resources that the users on
this server are all active users, and confirms that this is the only LDAP directory
server.
The LDAP administrator confirms that GADS will be run within the company’s
firewall and that the LDAP server will not need to be open to the outside.
Research LDAP Structure
Use an LDAP browser to collect information about your LDAP server and
structure.
You may find, while preparing for synchronization, that you have unexpected or
non-standard data in your LDAP directory server. It is always better to find and
address this before you begin synchronizing.
Be sure to collect the following key information:
• LDAP Base DN: GADS will use this Base DN as the top level for all LDAP
queries. You can use an LDAP browser to collect this information. If your
LDAP directory server includes OUs that you do not want to sync, consider a
Base DN that doesn’t include these OUs. Since GADS searches for both
users and groups from the Base DN, specify a Base DN on a level that
includes the users and groups you want to synchronize.
26 Release 3.0.6

27. Note: You can use multiple Base DNs in a configuration. You can specify a
separate Base DN for each synchronization rule. For more information, see
“User Search Rules” on page 88.
• LDAP Structure Information: You need to know which OUs contain users
and other resources you want to sync and which LDAP attributes contain
important information. Look through your LDAP directory structure with an
LDAP browser, then examine some sample users and other resources to
identify the LDAP attributes.
In many cases, the LDAP attribute that contains a user’s mail address, which
will become the username in Google Apps, is the mail attribute. Confirm the
LDAP attribute you want to use for mail addresses.
Check your LDAP directory server to find out which attributes contain the data
you need. In some cases, this data may include spaces.
Once you have collected this information, you are ready to start making decisions
about your synchronization.
Sample Scenario: Research LDAP Structure
MobiStep’s administrator downloads an LDAP browser and look through the
directory structure. The administrator finds that the Base DN to use for the domain
ad.mobistep.com is:
ou=users,ou=headquarters,dc=ad,dc=mobistep,dc=com
Then, the administrator looks more closely at the structure, and finds that the OUs
are divided up by department function. Each department function is a separate
OU under the Base DN. Department OUs include: sales, manufacturing, it,
genadmin, hr, contractors, and exec.
Clean Up LDAP Data
While you are identifying your LDAP data, be aware that you may need to clean
up your LDAP directory server data to synchronize with Google Apps. Begin
cleaning up your LDAP data early, to avoid data cleanup blocking your schedule
for synchronization.
Getting Started 27

28. When conducting LDAP cleanup, consider the following actions.
• Identify users. Identify which users you want to synchronize with Google
Apps. You may need to consult with your human resources department to
confirm that your user list is the correct list of users to synchronize.
• Populate Password Attribute (Optional). If you are using a password field
in GADS, create a custom attribute in your LDAP for your Google Apps users,
and populate the attribute with a password setting. Generate random
passwords and add them to a custom attribute. For more information about
Passwords, see “Passwords” on page 34.
• Set Naming Conventions (Optional). Identify any email naming conventions
you want to use, and update any users to fit these naming conventions. This
is optional: you do not need to set any particular naming convention for
GADS, but some companies use the transition to Google Apps as an
opportunity to change naming standards.
• Mail-Enabled Groups. Identify mail-enabled groups to synchronize with
Google Apps. This includes only mail-enabled groups that operate as mailing
lists, not security groups. Note also that you can set Google Apps to allow
users to create and manage their own groups; these are not affected by
synchronization.
• Plan Resource Naming Conventions. If you are planning to synchronize
calendar resources, you can take this opportunity to plan a naming
convention in Google Apps. For more information on this calendar resource
naming, see the Google Code site article Developing a naming strategy for
your calendar resources.
Sample Scenario: Clean Up LDAP Data
The MobiStep LDAP Administrator cleans up the MobiStep LDAP database to get
ready for synchronization.
The administrator uses an LDAP browser to identify users and mail-enabled
groups. The existing names already follow a standard naming convention, and the
administrator decides to keep that naming convention.
The LDAP administrator also creates a custom attribute for one-time passwords.
Later, this will be used to hold randomly generated passwords for new users.
Mark Google Apps Users In LDAP
One of the most effective ways to simplify your synchronization is to mark Google
Apps users beforehand in your LDAP directory. The benefit of marking your
Google Apps users in LDAP is that it will simplify your LDAP queries, make your
transition to Google Apps clear and visible, and possibly bypass any
complications with your existing LDAP directory structure.
When you first clean up your LDAP directory structure, mark the users you plan to
move into Google Apps with an OU, group, or custom attribute. Use a descriptive
name like “GoogleAppsUsers.” Use this to mark all users whom you plan to move
into Google Apps.
28 Release 3.0.6

29. Then, once you begin synchronization, mark active Google Apps users. Create an
OU, group, or custom attribute with a name like “GoogleAppsActiveUsers.” You
can then configure Directory Sync to synchronize based on this OU, group, or
custom attribute, then activate new users in Google Apps by updating your LDAP
server.
There are three ways to mark your Google Apps users in LDAP:
• OU: Set up an organizational unit (OU) and move Google Apps users into that
unit.
• Group: Create a new group in LDAP, and add Google Apps users as a
member of that group.
• Custom Attribute: Create a custom attribute for your users, and set that
attribute for new users.
Use whichever method works best for your LDAP directory environment.
The exact steps necessary to set up an OU, group, or custom attribute will vary
based on your LDAP directory server. Consult your LDAP directory server
documentation and work with your LDAP administrator to configure your LDAP
server appropriately.
Sample Scenario: Mark Google Apps Users In LDAP
The administrator creates two new groups on LDAP, GoogleAppsUsers and
GoogleAppsActiveUsers. All users who are identified to be synchronized into
Google Apps are added to the GoogleAppsUsers group. When users are added
into Google Apps, and have their mail flow switched over, those users are also
added to the ActiveGoogleAppsUsers Group. This will make it easier to track
which users are in Google Apps, and allows a clean synchronization without
removing old accounts that will not be synchronized into Google Apps.
Step Three: Decide What to Synchronize
Once you have identified your LDAP servers, decide what to synchronize.
For specific suggestions on what to synchronize during an early adopter program
or other parts of your life cycle, see “Roadmap for Deployment” on page 36, in this
chapter.
Domains
Decide what domains you want to synchronize on your LDAP server and in
Google Apps. Google Apps Directory Sync can synchronize with multiple domains
on the same account.
• Domain: Before you configure synchronization, decide what domain you want
to synchronize, and set up your domain in Google Apps.
Getting Started 29

30. Note: GADS does not create a domain for you, so you will need to add the
domain before you use Directory Sync.
Collect the exact domain name from the Google Apps control panel. Note that
you cannot synchronize a domain alias.
• Domain Name Replacement: You can also specify another domain.
Directory Sync will create or update all users in the new replacement domain.
This is most often used for a pilot domain, but can also be used if you are
using GADS to move to a new domain. If you specify another domain in
Configuration Manager, you can import a full list of users into a different
domain. Note that using domain replacement can affect your Google Apps
exclusion rules.
30 Release 3.0.6

31. Note: Domain name substitution does not support Shared Contacts
synchronization.
Set up the new domain as a primary domain in Google Apps. Then, in
Configuration Manager, enter the new domain as your Google Apps domain,
and use a Google Apps administrator for that domain. In Google Apps
Settings, set Directory Sync to replace domain names in LDAP email
addresses with this user name. Google Apps Directory Sync will rename all
your users to that new domain during synchronization.
After your pilot period is complete, you can change the domain name (and
Google Apps administrator) to your actual primary domain, and keep all other
configuration options the same. For more information on setting up your
domain name, see “LDAP Connection Settings” on page 70.
User Data
GADS can synchronize a wide variety of user data. This includes users,
passwords, alias information, and profiles. Examine your LDAP directory data and
your Google Apps configuration to decide what data to synchronize. You may
need to purchase additional licenses in Google Apps if you add users above your
current number of licenses.
Consider the following synchronization options:
• Users: Look through your whole set of users with an LDAP browser. For more
information about using an LDAP browser, see “Step One: Install LDAP
Browser” on page 24.
You may have internal-only users, or special users that should not have
external email (such as printers). You may also decide to start by
synchronizing only a small trial group of users. Construct an LDAP query for
the users you want to synchronize. For more information on constructing
LDAP queries, see “About LDAP Queries” on page 45.
WARNING: Check to be sure that you are importing the correct number of
users. If you import more users than you have licenses in Google Apps, you
may experience errors during synchronization for exceeding your user limit.
• User Profiles: If your LDAP directory server includes further information,
such as addresses, phone numbers, or contact information, you can
synchronize this information into Google Apps.
You can use GADS to import the full names of your users into Google Apps. If
you want to do this, find the LDAP attributes that contain this information.
User names are often stored in two attributes: one for the first name and one
for the last name. If you do not have an LDAP attribute with the appropriate
information, you can skip this step.You can synchronize this through LDAP
extended attributes. For more information, see “User Profiles” on page 104.
If you have full user profiles in your LDAP directory server and you want to
synchronize this information into Google Apps, you can import User Profiles.
For more information, see “User Profiles” on page 104.
• Aliases: You can synchronize one or more attributes for aliases from your
LDAP directory into Google Apps nicknames. Use an LDAP browser to
Getting Started 31

32. confirm the LDAP attribute (or attributes) you want to use. Be sure that the
attribute contains only an email address, and not other data such as a phone
number.
• Primary Domain Key: If your users are likely to change user names, set up a
Primary Key attribute beforehand so that user information is not lost when a
user changes their name. This should be a field on your LDAP that is unique
for each user, and will not change when your users change names.
• Passwords: GADS supports a limited set of password operations. If you want
GADS to handle passwords, this will require additional preparation and
planning. For more information, see “Passwords” on page 34.
• Deleted and Suspended Users: By default, users not found on your LDAP
directory will be deleted from Google Apps, and suspended users will be
ignored. If this is what you want GADS to do, leave deleted and suspended
users settings at the default.
You can set GADS to suspend users instead of deleting them. This allows for
data recovery if users are later recovered, and the ability to view and transfer
a user’s assets.
If your Google Apps account has suspended users that you want to remove,
you can instead set GADS to delete suspended users. You cannot use this
setting if you use the option, described in the paragraph above, to suspend
users instead of deleting them.
For more information on these options, see “Additional User Attributes” on
page 83.
Groups and Mailing Lists
There are several ways to organize your users in Google Apps. Different lists and
groups can be synchronized into Google Apps in different ways.
Decide how you want to organize your users, and consider the following topics.
• Mailing Lists: Decide which mailing lists you want to synchronize from your
LDAP directory server into Google Apps. Mailing lists on your LDAP directory
server will be imported as groups in Google Apps. You may not want to import
all mailing lists, since some lists may be internal lists, or company resources
such as rooms or printers, or may contain unusable data. GADS will not
modify or overwrite groups that users create with the Google Groups for
Business service. For information on synchronizing mailing lists, see “Groups”
on page 96.
If you do want to synchronize Mailing Lists, find out what attribute contains the
members of your mailing lists. This is often the member attribute or the
mailAddress attribute, but your LDAP directory server may be different. If this
attribute is also used for other data, you may need to use another attribute or
to clean up your LDAP directory server. Be sure to exclude empty lists.
Also, find out if the LDAP attribute for mailing list members contains an email
address, or a user Distinguished Name. Some mailing list attributes contain a
literal address, which follow a format like terri@mobistep.com. Some contain
Distinguished Name reference, which follow a format like cn=Terri
32 Release 3.0.6

33. Smith,ou=Executive Team,dc=mobistep,dc=com. GADS can synchronize
mailing lists using either format, but you’ll need to know which you’re using
beforehand so you can configure GADS properly.
• Org Structure: By default, GADS synchronizes all users into a single flat
structure. This works well if you have a small organization, or if you want all
users to have the same settings and rights. This also works well if you are
piloting a small group before a larger rollout.
If you want to use an org unit hierarchy in Google Apps, you can synchronize
the organization hierarchy from your LDAP directory server. If you do so, look
through your OUs with an LDAP browser beforehand to be sure that you are
synchronizing the right OU structure. You may have special OUs that should
not have org units in Google Apps, such as an OU for printers. For more
information about synchronizing your OU structure, see “LDAP Org Units” on
page 71.
If you want to create Google Apps organizations manually, you can set those
organizations up in Google Apps, then set GADS to move users into those
Google Apps organizations, without changing existing organizations. To set
this up, select “Do not create or delete Google Organizations, but move users
between existing Organizations, as specified in the User Sync Rules” option
on the General Settings page. For every user search rule, specify the
organization that should contain users for that rule, or an LDAP attribute that
contains the name of the appropriate Organization. For more information
about moving users between existing organizations, see and “User Search
Rules” on page 88.
Contacts and Calendar Resources
GADS can also synchronize other LDAP resources into Google Apps, such as
shared contacts and calendar resources.
• Shared Contacts: If you want to import addresses into Google Apps as
shared contacts, enable Shared Contacts in General Settings. Shared
Contacts will be visible to every user on a contacts list. When users enter
email addresses for recipients in Gmail, addresses in Shared Contacts will
show up in Autocomplete.
Note that this will only synchronize shared contacts; personal contacts are not
imported with GADS. Shared contacts are contacts that can be viewed by
every user in the account. These are different from personal contacts, which
are each viewed and edited by an individual user. For more information about
Shared Contacts, see “Shared Contacts” on page 112.
If you’re setting up a pilot with a small group of users, you can use Shared
Contacts to synchronize the rest of your user base into your shared contacts
list, so that pilot users will see addresses in Autocomplete that haven’t been
synchronized yet. If you decide to do so, however, note that you should
remove these shared contacts before your full synchronization, to avoid
duplicate Autocomplete addresses.
Important: Shared Contacts do not show up immediately. After you
synchronize Shared Contacts, it may take up to 24 hours for the changes to
appear in Google Apps.
Getting Started 33

34. • Do you want to synchronize Calendar Resources? If you want to import
calendar resources (such as conference rooms) from your LDAP into Google
Apps, configure Calendar Resources synchronization. Calendar Resources
are visible to every user when attempting to schedule calendar events. For
more information, see “LDAP Calendar Resources” on page 121.
If you do want to synchronize calendar resources, choose a naming format for
your calendar resources. Note that names containing spaces or special
characters (like @) will not be synchronized. The rules for calendar resources
names are different than other synchronized information. For more
information on this calendar resource naming, see the Google Code site
article Developing a naming strategy for your calendar resources.
Passwords
Directory Sync can import passwords from LDAP, but only in an LDAP attribute
that stores passwords in plain text, Base64, unsalted MD5, or unsalted SHA-1
format. Other password encryption hashes are not currently supported, nor are
salted hashes. Most directory servers do not support these formats natively, and
storing your user passwords in these formats on your mail server may have
serious security implications.
34 Release 3.0.6

35. For password synchronization, GADS provides the following options:
• Implement Single Sign-On for your domain. Set up a SAML server for your
account to manage Single Sign-On. Users will use the same passwords and
authorization for both Google Apps and your LDAP directory server. GADS
will create random passwords during synchronization in this case.
Note that Single Sign-On supports only web authentication. Other forms of
authentication (such as IMAP, POP, and ActiveSync) do not support Single
Sign-On and will still require a Google password.
Use this option if you are planning to set up Single Sign-On for your domain.
For more information on Single Sign-On, see the SSO site on Google Code.
• Use a plain text LDAP attribute for default password for new users. With
this option, Google Apps passwords are separate from passwords on your
LDAP directory server. You can use this method to create a temporary
password from any LDAP attribute that holds data in plain text format.
The most secure way to create a default password is to populate a custom
attribute with a randomly generated password. Alternately, you can use a
private and unique field, such as employee ID number. Avoid using a field that
could be easily guessed, such as email address or last name, since this could
make it easier for other users to sign up using temporary credentials.
Use this option if you want users to have separate one-time passwords, and
you have or can create an appropriate LDAP field to use for temporary
passwords.
• Use a third-party utility to convert unsupported passwords to a
supported format. Check the Google Marketplace for third-party tools to help
with synchronizing passwords. Use this option if you need to have Google
Apps use the same passwords as your LDAP directory server, but you are
unable to set up a SAML server. This may require you to set new passwords
on your LDAP directory.
• Specify a default password for new users. Every new user will have the
same password until that user logs in and changes the password. With this
option, Google Apps passwords are separate from passwords on your LDAP
directory server. Set a default password for new users, and then set Directory
Sync to synchronize passwords for new users and force new users to change
their passwords.
Because this password may be guessed by other users, this is not generally
recommended as a secure option.
Important: Be careful of the security considerations of passwords. Also, note that if
you use a plaintext password, be sure to set GADS to synchronize passwords
only for new users, and to require new users to change passwords.
Mapping
Decide how your LDAP directory server data should map to your Google Apps
data. You should have a clear picture of where every user, group, and resource in
your LDAP directory server should be synchronized in your Google Apps data.
Getting Started 35

36. For a chart of how your LDAP data maps to Google Apps, see “What Is
Synchronized” on page 13.
Note that you may have some users who should not be synchronized, either on
your LDAP server or in Google Apps. Prepare a list of exceptions so that you
know what rules to set up.
• Mapping: For each group of users, decide whether those users should be
imported, and where those users should be imported. You can set up this
mapping to a flat hierarchy, an automatic one-to-one synchronization, or a
manual set of custom rules.
• Exceptions on Google Apps: Are there any exceptions on your Google
Apps domain that you don’t want to synchronize? Your Google Apps account
may have users or groups that you don’t want to synchronize with LDAP. This
could include new users not listed in your LDAP directory, pilot test accounts,
shared Google Apps accounts, or other entries that belong in your Google
Apps account but not your LDAP directory. Find out which users and groups
you’d like to exclude, and look for any common pattern that may simplify
exception rules.
• Exceptions on LDAP Directory: Are there any exceptions on your LDAP
directory that you don’t want to synchronize? Your LDAP directory server may
have obsolete users, suspended users, test accounts, printers, defunct
mailing lists, or other data that you do not want to import into Google Apps. In
most cases, you can set your LDAP search rules to ignore these users, but in
some cases, you may need to set up manual exception rules to skip specific
users, or a pattern of users. Identify any exceptions that you don’t want to
synchronize, and note these so that you can create exceptions during
configuration.
Roadmap for Deployment
The best settings to use for synchronization depend on your situation, server, and
stage in the life cycle of using GADS. The following roadmap suggests likely
settings for different stages of a deployment.
36 Release 3.0.6

37. For more information about deployment phases and the 3-phase deployment
model, see “Directory Sync and Deployment” on page 15.
Core IT Early Adopter Go Live Maintenance
Goals in this Clean up data By the end of the Switch users over Keep Google
phase and prepare for Early Adopter to Google Apps. Apps data
migration in Early phase, you Set Google Apps synchronized with
Adopter phase. should have up as primary your LDAP
Test connectivity GADS ready for service. directory.
and your Global Go
synchronization. Live date. The first Plan a scheduled
Synchronization synchronization
can take time. of Google Apps.
Synchronize a Scheduled
few days in synchronization
advance of your will take less time
Go Live date so and resources
that users will be than the first
ready. In some synchronization.
cases, it may be a
good idea to
synchronize over
a weekend.
Domains
Optionally, you Use your primary Use your primary
can use a domain for domain for
“shadow” or test synchronization. synchronization.
domain, replacing
domain names
with a subdomain
of your existing
organization, like
test.exmpl.com.
Getting Started 37

38. Core IT Early Adopter Go Live Maintenance
Users
Set up exceptions Synchronize your Set up exceptions
for manually- early adopters or for Google Apps
added Core IT add them users that are not
users, temporary manually. Mark listed in your
administrators, or which users are LDAP directory.
other users that activated in your
are not part of LDAP directory.
your LDAP
search rules. Optionally, you
can synchronize
Create an LDAP all users (but not
OU, group, or change their mail
custom attribute flow or send
for users that will passwords), so
be synced into that all addresses
Google Apps. will be visible in
Then, create a Autocomplete.
group of custom
attribute for active
Google Apps
users.
User Profiles
If your LDAP If your LDAP If your LDAP
directory includes directory includes directory includes
rich profile data, rich profile data, rich profile data,
you can you can you can
synchronize this synchronize this synchronize this
with Google with Google with Google
Apps. Apps. Apps.
Aliases
Passwords
If you are syncing
your users, sync
passwords as
well.
38 Release 3.0.6

39. Core IT Early Adopter Go Live Maintenance
Suspended
Users
You can Suspended users Usually not used Usually not used
synchronize can be used for after go live date, after go live date,
Google Apps early migration of but available if but available if
users as data. you want to you want to
suspended users suspend users suspend users
for testing Google instead of instead of
Apps functionality. deleting them. deleting them.
Mailing Lists
Most mailing lists Mailing lists
will still be should now be
maintained on managed in
legacy server. Google Apps as
groups.
GADS does not
synchronize or
overwrite user-
managed mailing
lists (groups).
Org Structure
Optionally, start If you have a Changes to your
setting up your large organization Organization
org structure in or complex Structure
advance during hierarchy in your Mapping rules will
Early Adopter LDAP directory move users within
phase. server that you Google Apps.
want to keep,
configure
Directory Sync to
synchronize Org
Structure.
Getting Started 39

40. Core IT Early Adopter Go Live Maintenance
Shared
Contacts
Optionally, you If your company If your company
can synchronize directory has directory has
all users as shared contacts, shared contacts,
shared contacts you can you can
so that they will synchronize synchronize
be visible in these during your these during your
Autocomplete. Go Live Go Live
synchronization. synchronization.
Note that these
shared contacts Note that Note that
may lead to personal contacts personal contacts
duplicate contacts are not are not
if not removed synchronized. synchronized.
before your Go
Live date.
Calendar
Resources
Most calendar Calendar
resources will be resources should
maintained on now be managed
legacy server. in Google Apps.
Primary Key
Attribute
Set up Primary Primary Key
Key Attribute for attributes help
easier ongoing users keep data
maintenance. after a name
change.
Sample Scenario
The Google Apps administrator for MobiStep decides that the existing
organization hierarchy on the LDAP server should be copied onto Google Apps,
and identifies the OUs that should be synchronized.
40 Release 3.0.6

41. The administrator decides that MobiStep needs to synchronize:
• OUs
• Users
• Aliases
• Groups (mailing lists)
• Shared contacts
• Calendar resources
The mailing lists in the LDAP server use the attribute member to store the members
of each mailing list, and the member attribute contains the full DN of the mailing
list members, rather than their email address. The GADS administrator notes this
attribute, and notes that it is a reference attribute, not a literal attribute.
Because the LDAP user profile information on the LDAP server is not in a
standard format across organizations, the Google Apps administrator decides not
to synchronize this information.
The LDAP administrator creates a custom attribute and populates the attribute
with a randomly-generated one-time password. The Google Apps administrator
sets up a mail merge to send out these passwords to users along with information
on how to activate their accounts.
The Google Apps identifies that there are some users in the contractors OU that
are no longer with the company and should not be synchronized. The
administrator looks through these users and notes that all of them match a regular
expression (the user addresses all begin with “defunct”) and notes this to create
exceptions in Google Apps.
Step Four: Prepare Google Apps for Synchronization
Once you know what to synchronize, there are a few miscellaneous steps you’ll
need to take to prepare for synchronization.
Google Apps Authentication
GADS needs to log into Google Apps to update information. There are two ways
to do this.
• OAuth Credentials (recommended): GADS can generate an OAuth token
during configuration, and use that token to connect and synchronize. If you
are using this method, you will generate the token during configuration, but
will need a Google Apps administrator username and password during this
process. This method is recommended because it is more secure.
• Administrator: Alternately, you can supply a Google Apps username and
password that GADS will use when synchronizing. Collect the username and
password for the administrator account you will use.
Getting Started 41

42. For more information, see “Google Apps Connection Settings” on page 58.
Enable APIs
GADS uses the Google Apps Provisioning API to update your Google Apps
domain. Before you can synchronize, you must log in to Google Apps and enable
the User API.
To enable the Provisioning API access for your domain:
1. Log in to your control panel.
2. Click Domain settings > User settings.
3. For Provisioning API: Check the box next to Enable provisioning API. If it’s
already checked, leave it checked.
4. Click Save changes.
For more information, see the Google Apps Help Center.
Step Five: Prepare Your Servers for Synchronization
Be sure that your servers and network are prepared for GADS.
Notifications Mail Server
GADS is designed to be used for scheduled synchronization without supervision,
once synchronization rules are set up. Because of this, you will need a mail server
that can relay reports from GADS.
Collect the following information:
• The addresses that should receive notifications.
• The address the notifications should come from.
• The SMTP relay host IP address or domain name.
• The username and password for connecting to the SMTP relay host (if
needed).
Note that you cannot use Google Apps as your notifications mail server.
Sample Scenario
MobiStep’s Google Apps administrator decides to use OAuth, and collects a
Google Apps administrator username and password to configure this.
42 Release 3.0.6

43. The administrator also contacts MobiStep’s mail administrator to set up
notifications. The existing MobiStep mail server has a rule to block all relay
attempts, so the mail administrator sets up an exception so that the machine
running Directory Sync can relay mail through that server to send out notifications.
The server doesn’t use SMTP authentication, so no username or password are
required. The MobiStep administrator decides that the notifications should come
from the address dirsync.notifications@mobistep.com so that notifications can
be filtered separately into a label.
Further Steps
Further steps are discussed in later chapters:
5. Install Directory Sync. This step is covered in “Installation” on page 49.
6. Configure Directory Sync. This step is covered in “Configuration” on
page 53.
7. Simulate Synchronization. This step is covered in “Sync” on page 135.
8. Revise Configuration. This step is covered in “Configuration” on page 53.
9. Preview Synchronization. This step is covered in “Command Line
Synchronization” on page 139.
10. Manual Synchronization. This step is covered in “Command Line
Synchronization” on page 139.
11. Scheduled Synchronization. This step is covered in “Scheduling
Synchronization” on page 141.
12. Monitoring. This step is covered in “Monitoring” on page 143.
Getting Started 43

44. 44 Release 3.0.6

45. Chapter 4
LDAP Queries Chapter 4
About LDAP Queries
GADS uses the LDAP query language to collect data from your directory server.
Before you can synchronize data from your directory server, you will need to
prepare LDAP queries.
The LDAP query language is a flexible standard that supports complex and
powerful logical queries, and is discussed in this section. Google Apps Directory
Sync strictly adheres to RFC 2254, which defines international standards on
LDAP filters.
To build your LDAP queries, you will need to know your LDAP structure. The best
way to collect directory server information is an LDAP browser. For more
information, see “Step One: Install LDAP Browser” on page 24.
Most of the search rules in GADS use LDAP queries for information. The only
exception to this are Exception Rules, which use substring or regular expressions
based on the text of email addresses, not LDAP fields.
Note: This document lists many common queries, but every directory server is
different, and many store information in different fields or formats. To develop
these queries, consult standard LDAP documentation and review your LDAP
structure with an LDAP browser. Google support cannot write LDAP queries for
your environment or debug your LDAP queries.
Syntax
The following syntax is used in LDAP filters:
Name of
Operator Character Use
Equals = Creates a filter which requires a field to have a
given value.
LDAP Queries 45

46. Name of
Operator Character Use
Any * Wildcard to represent that a field can equal
anything except NULL.
Parentheses () Separates filters to allow other logical
operators to function.
And & Joins filters together. All conditions in the
series must be true.
Or | Joins filters together. At least one condition in
the series must be true.
Not ! Excludes all objects that match the filter.
For examples of how these operators are used, see the common LDAP queries
below.
Common LDAP Queries
The examples below show the most common LDAP queries. These queries are
the most common queries used, and are designed to work with most directory
server environments.
All objects (this may cause load problems):
objectclass=*
All user objects that are designated as a “person”
(&(objectclass=user)(objectcategory=person))
Mailing Lists only
(objectcategory=group)
Public Folders only
(objectcategory=publicfolder)
All user objects except for ones with primary email addresses that begin with
“test”
(&(&(objectclass=user)(objectcategory=person))(!(mail=test*)))
All user objects except for ones with primary email addresses that end with
“test”
(&(&(objectclass=user)(objectcategory=person))(!(mail=*test)))
46 Release 3.0.6

47. All user objects except for ones with primary email addresses that contain the
word “test”
(&(&(objectclass=user)(objectcategory=person))(!(mail=*test*)))
All user objects (users and aliases) that are designated as a “person” and all
group objects (distribution lists)
(|(&(objectclass=user)(objectcategory=person))(objectcategory=grou
p))
All user objects that are designated as a “person”, all group objects and all
contacts, except those with any value defined for extensionAttribute9:
(&(|(|(&(objectclass=user)(objectcategory=person))(objectcategory=
group))(objectclass=contact))(!(extensionAttribute9=*)))
All users who are members of the group identified by the DN of
“CN=GRoup,OU=Users,DC=Domain,DC=com”:
(&objectcategory=user)(memberof=CN=GRoup,OU=Users,DC=Domain,DC=com
))
Active Directory LDAP: All users
(objectClass=person)
Active Directory LDAP: All email users (alternate)
(&(objectclass=user)(objectcategory=person))
OpenLDAP: All users
(objectClass=inetOrgPerson)
Lotus Domino LDAP: All users
(objectClass=dominoPerson)
Lotus Domino LDAP: All objects with a mail address defined that are designated
as a “person “or “group”:
(&(|(objectclass=dominoPerson)(objectclass=dominoGroup)(objectclas
s=dominoServerMailInDatabase))(mail=*))
LDAP Queries 47

48. 48 Release 3.0.6

49. Chapter 5
Installation Chapter 5
About Installation
Google Apps Directory Sync (GADS) is designed to run on Windows, Linux or
Solaris servers.
The installer is an executable program that installs all needed components on the
server, including managing libraries, classpath variables, and other components.
The installer also uninstalls any existing version of GADS in the same directory.
The sections below contain system requirements, and instructions on how to
install, upgrade or uninstall GADS on your server.
Install Google Apps Directory Sync
To install GADS:
1. Go to the GADS download page at:
http://google.com/apps/directorysync
2. Choose the operating system of the server where you plan to run GADS and
click Download.
Installation 49

50. 3. Download and run the installer.
4. Complete all the steps of the installer.
The installer contains all needed components and can be run offline without any
outside connection.
Note: To run synchronization, you must also enable APIs on your Google Apps
domain. See “Enable APIs” on page 42.
50 Release 3.0.6

51. Upgrade Google Apps Directory Sync
GADS automatically checks to see if there are any updates available. If updates
are available, you will be prompted to upgrade when you start Configuration
Manager.
Configuration files are backward-compatible. Future versions of GADS can run
configuration files created in earlier versions.
The installer wizard automatically detects and uninstalls previous versions of the
software in the same directory.
Uninstall Google Apps Directory Sync
GADS also includes an uninstaller.
To remove GADS:
1. Open a command line interface and go to the directory that contains GADS.
2. Run the following command:
uninstall
3. In the uninstaller, click Next to uninstall GADS.
4. Once uninstallation has completed close the uninstaller.
All GADS utility files and all libraries not used by other programs will be removed.
Log files and XML configuration files will not be deleted.
Installation 51

52. 52 Release 3.0.6