Gads Admin

Google Apps Directory Sync
Administration Guide
Release 1.6.21
Google, Inc.
1600 Amphitheatre Parkway
Mountain View, CA 94043
www.google.com
Part number: GADS_1.6.21_20
November 23, 2010
© Copyright 2010 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 1.6.21DAMAGES (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
This product includes software developed by
2 Release 1.6.21
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 Release 1.6.21
Contents
About This Guide 7

What This Guide Contains 7
Related Documentation 7
How to Send Comments About This Guide 8
Chapter 2: Introduction 9
About Google Apps Directory Sync 9
Features and Benefits 10
System Requirements 11
Comparison with Google Apps Directory Sync for Email Security 11
Architecture 12
Utility Overview 14
Chapter 3: Preparation and Planning 15

About Preparation 15
Useful LDAP Tools 16
Planning Your Synchronization Strategy 16
LDAP Queries 23
Chapter 4: Installation 27
About Installation 27
Enable APIs 27
Install Google Apps Directory Sync 28
Upgrade Google Apps Directory Sync 29
Uninstall Google Apps Directory Sync 29
Chapter 5: Configuration 31
About Configuration 31
Configuration Files 32
General Settings 32
Google Apps Configuration 35
Google Apps Settings 36
Exclusion Filters for Google Apps 38
LDAP Settings 44
LDAP Connection 45
Contents 5
LDAP Org Units 47
LDAP Org Unit Search Rules 48
LDAP Org Units Exclusion Rules 50
LDAP Org Unit Mappings 54
LDAP Users 56
LDAP User Attributes 58
LDAP Extended Attributes 60
LDAP User Sync 64
LDAP User Exclusion Rules 68
LDAP Groups 72
LDAP Group Search Rules 73
LDAP Group Exclusion Rules 78
LDAP User Profiles 81
LDAP User Profiles Attributes 82
LDAP User Profiles Sync 84
LDAP User Profiles Exclusion Rules 87
LDAP Shared Contacts 90
LDAP Shared Contacts Attributes 92
LDAP Shared Contacts Sync 94
LDAP Shared Contacts Exclusion Filter 97
Notifications 100
Delete Limits 102
Log Files 104
Simulate Sync 105
Chapter 6: Synchronization 109

About Synchronization 109
Command Line Synchronization 109
Scheduling Synchronization 111
Chapter 7: Troubleshooting 113

About Troubleshooting 113
Common Issues 113
System Tests 116
Escalating Problems 117
6 Release 1.6.21
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 the directory sync utility on your server.
• Configuration for the directory sync utility.
• Synchronizing users, groups, and shared contacts.
• Troubleshooting the directory sync utility.
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.
7
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. If you have comments about this guide, please
send an email message to:
postini-doc_comments@google.com
Please specify in your email message the section to which your comment applies.
If you want to receive a response to your comments, ensure that you include your
name and contact information.
8 Release 1.6.21
Chapter 2
Introduction Chapter 2
About Google Apps Directory Sync

Google Apps Directory Sync is a utility that adds and deletes your users, groups,
and shared contacts in Google Apps to match your LDAP directory server. When
you synchronize, any changes on your LDAP server are reflected in Google Apps.
The directory sync utility runs on a server machine in your network environment.
You can use any machine that is able to connect to your LDAP server and to
Google Apps.
Use Google Apps Directory Sync to synchronize information so that your Google
Apps users, groups, and shared contacts are automatically kept up to date with
your LDAP directory server.
Important: Before you enable Google Apps Directory Sync for your organization,
please keep a few things in mind:
Introduction 9
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).
Features and Benefits

Google Apps Directory Sync offers the following features and benefits:
• Updates your Google Apps user and groups to match your LDAP data.
• A local on-site utility that runs in your server environment. No machine outside
your perimeter will access your LDAP directory server data.
• Runs on any Windows (XP or Vista), Linux or Solaris server.
• All needed components included in installation.
• Allows sophisticated rules to handle groups, aliases, and exceptions.
• Advanced LDAP query capabilities to handle irregular LDAP environments.
• Extensive tests and simulations to ensure correct synchronization.
10 Release 1.6.21
System Requirements
Using Google Apps Directory Sync requires the following:
• A Google Apps domain running Premier Edition, Partner Edition or Education

Edition. Google Apps Directory Sync is not available with Standard Edition or
Team Edition of Google Apps.
Note: Google Apps Directory Sync only synchronizes primary domains, not
domain aliases.
• An administrator account on your Google Apps domain.
• User APIs enabled on your Google Apps domain. For steps on how to do this,
see “Enable APIs” on page 27.
• A server on which to install Google Apps Directory Sync, running Microsoft

Windows (tested on XP and Vista), Linux or Solaris (version 8+, no support for
x86).
• At least 5GB 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 256MB of free RAM. At least 1GB of free RAM is suggested if you
have less than 10,000 users, or 2GB 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 the directory

sync utility. All versions of the LDAP protocol are supported.
• Network access to your LDAP server. You do not need to run the directory
sync utility on your LDAP server.
• Read and execute administrative access over the appropriate OU structure of

the LDAP server.
• Network access to the Google Apps through HTTPS, directly or through a

proxy server.
• A mail server able to accept and relay notifications from the directory sync
utility.
Comparison with Google Apps Directory Sync for Email Security

Google Apps Directory Sync is a utility that synchronizes your LDAP directory
server with Google Apps, and lets you control users for applications like Gmail,
Google Docs and Google Spreadsheet for your domain.
There is another utility with a similar name, Google Apps Directory Sync for Email
Security. This utility is used with Google Message Security, powered by Postini.
Despite the similar names, the utilities are completely separate. Google Apps
Directory Sync cannot be used with the message security service, and Google
Apps Directory Sync for Email Security cannot be used with Google Apps for your
domain.
Introduction 11
You can use both utilities in the same environment.
To find out more about Google Apps Directory Sync for Email Security, see the
Google Apps Directory Sync for Message Security web site here:
http://www.postini.com/dir_sync
Architecture
Google Apps Directory Sync runs on your server and updates Google Apps to
match your LDAP server. The directory sync utility never updates or changes your
LDAP server.
The following steps describe how the data flow of directory sync works.
1. The directory sync utility 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.
12 Release 1.6.21
2. The directory sync utility 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. The directory sync utility compares these lists, and generates a list of
changes.
Introduction 13
4. The directory sync utility then updates Google Apps to match your LDAP
server settings.
Utility Overview
The directory sync utility includes several components, designed to work together.
These components are:
• Configuration Manager - Use this graphical UI to configure how the directory

sync utility will connect to Google Apps and to your LDAP server. You can
also create rules for user lists, search queries, organization mapping, aliases,
distribution lists and exceptions. For more information, see “Configuration” on
page 31.
• XML Configuration File - Save configuration information from Configuration

Manager in an XML file. Use this file during synchronization.
• Synchronization Command Line - Use the command-line utility sync-cmd to

perform actual synchronization. This utility uses settings in your XML
configuration file to connect to Google Apps and your LDAP server, and
updates your users and aliases in Google Apps. For more information, see
“Synchronization” on page 109.
• Scheduling - Once you have used sync-cmd successfully, use your operating
system’s scheduling functionality to schedule future synchronization.
Depending on the server you use, this might be a cron job, a Windows
Scheduled Service utility, or any other scheduling tool. For more information,
see “Synchronization” on page 109.
14 Release 1.6.21
Chapter 3
Preparation and Planning Chapter 3
About Preparation
Before you install Google Apps Directory Sync and configure synchronization, you
should plan how you will synchronize your LDAP structure with Google Apps.
Many steps in the configuration and synchronization process assume you already
have available key information about your LDAP directory server, mail server, and
Google Apps domain.
This chapter includes a checklist of information you’ll need before you begin,
strategy tips, LDAP browser information, and some sample LDAP queries.
For information on system requirements, see “System Requirements” on page 11.
Overview
You can expect the following steps when configuring a typical setup for Google
Apps Directory Sync.
1. Identify your LDAP resources, including LDAP servers and expert

administrators.
2. Plan which users, aliases, and groups you want to synchronize with Google
Apps.
Note: You may need to purchase additional licenses in Google Apps if you add
users above your current number of licenses.
3. Collect required information about your LDAP server and your Google Apps
domain. You may need to download and set up an LDAP Browser to do this.
For links to LDAP browsers, see “Useful LDAP Tools” on page 16.
4. Make any necessary changes to clean up extraneous or problematic data in

your LDAP server.
5. Install the directory sync utility. For information about installation

prerequisites, see “System Requirements” on page 11.
Preparation and Planning 15

6. Run Configuration Manager (part of Google Apps Directory Sync) to configure
synchronization.
7. In Configuration Manager, simulate a synchronization and review the results.
8. If needed, revise your configuration in Configuration Manager based on the

simulation. This could take several revisions for complex environments.
9. When the simulation is successful, save your final copy of the configuration
file and exit Configuration Manager.
10. At the command line, run a synchronization in preview mode with the
configuration file you created. Check the results.
11. 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.
12. Using your server’s scheduling tools, set up automatic scheduled

synchronization.
Useful LDAP Tools

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.
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
Planning Your Synchronization Strategy

Plan your synchronization strategy before you start configuring Google Apps
Directory Sync. Gathering information about your LDAP directory server and data
beforehand helps ensure a smoother and easier synchronization.
When planning your synchronization strategy, consider the following factors.
16 Release 1.6.21
LDAP Data Evaluation and Cleanup
Use an LDAP browser to examine your directory server data before you install
Google Apps Directory Sync or begin synchronizing. For more information on
downloading an LDAP browser, see “Useful LDAP Tools” on page 16.
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.
1. If you have the ability to modify or format your LDAP directory server, consider
cleaning up your LDAP server for easier synchronization. Look through your
data, and consider any data you may want to alter.
2. Check your LDAP directory server to find out which attributes contain the data
you need. In some cases, this data may include spaces. Google Apps stores
group names as email addresses, which cannot contain spaces, so note if any
of your group names require cleanup.
Terminology: LDAP Directory Server and Google Apps

LDAP directory servers use a different set of terms than Google Apps, and
sometimes use different terms for the same thing.
Users are fairly similar in LDAP and Google Apps, but LDAP also distinguishes
between users who are a “person” (actual humans) and users who are
“resources” (like printers and conference rooms). Different LDAP directory servers
implement users in different ways.
LDAP includes the concept of aliases, also sometimes called proxy addresses. In
Google Apps, these are called nicknames, but are functionally identical.
LDAP mailing lists forward mail for one address to a number of member
addresses. In Google Apps, these are implemented as groups. Google Apps
groups can include additional functionality, but should support the features of a
standard LDAP mailing list.
Corresponding Concept in Google

Concept in LDAP Apps
Org Units (OUs) Organizations
Users Users
Aliases Nicknames
Mailing Lists Groups (all groups are added as

Public groups)

Decisions You’ll Need To Make
Before you install Google Apps Directory Sync, review your LDAP structure and
consider the following decisions you’ll need to make.
• Which users do you want to synchronize? Look through your whole set of
users with an LDAP browser. You may have internal-only users, or special
users that should not have external email (such as conference rooms). 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.
• Do you want to synchronize the LDAP org hierarchy? If you want to user
an org unit hierarchy in Google Apps, you can synchronize the organization
hierarchy from your LDAP directory server. Look through your whole set of
OUs with an LDAP browser. You may have special OUs that should not have
org units in Google Apps (such as an OU for printers). You may also decide to
start by synchronizing only a small trial group of users. Construct an LDAP
query for the org units you want to synchronize, and plan how you want to
map this into a hierarchy in Google Apps.
If you want to move users into Google Apps Organizations that you have
already set up, without creating or deleting Organizations in Google Apps,
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.
• Do you want to use the same domain or a pilot domain? If you specify
another domain in Configuration Manager, you can import a full list of users
into a different domain. You can use this method to test out Google Apps with
a trial domain that is different from the domain in your LDAP server. For more
information on pilot domains, see “Pilot Domain” on page 22.
• What LDAP attribute contains a user’s mail address? In many cases, this
will be the mail attribute. Use an LDAP browser to confirm the LDAP attribute
you want to use for mail addresses.
• What LDAP attribute(s) contain a user’s aliases? You can synchronize one
or more attributes for aliases in your LDAP Server into Google Apps
nicknames. Use an LDAP browser to confirm the LDAP attribute you want to
use. Be sure that the attribute contains only an email address, and not other
data such as a phone number.
• Do you want to import user names? You can use Google Apps Directory
Sync to import the full names of your users into Google Apps. If you want to
do this, find the LDAP attribute(s) that contains 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.
• Do you want to import passwords? You can also use Google Apps
Directory Sync to import passwords from your LDAP directory server into
Google Apps. Passwords are supported as strings or binaries.
To synchronize passwords from LDAP, you will need an LDAP attribute that
stores passwords in plain text, MD5 or SHA1 format. Before you begin
configuration, find out what encryption format your LDAP directory server
18 Release 1.6.21
uses for passwords. By default, Active Directory and Lotus Domino directory
servers do not include these passwords.
Note: Other password encryption hashes are not currently supported.
If you wish to synchronize passwords, you can synchronize for all users (if
you want to manage passwords in LDAP) or only for new users (if you want to
manage passwords in Google Apps).
If your LDAP directory server does not support passwords in the format that
Google Apps Directory Sync uses, consider the following options:
• Specify a default password for new users and force new users to change
their password on first login.
• Use a plaintext attribute, and force new users change their password on
first login.
• Use a third-party utility to convert unsupported passwords to a supported
format.
• Implement Single Sign-On for your domain.
• Set passwords in Google Apps Directory Sync manually.
• What groups do you want to import? 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. Directory Sync will
not modify or overwrite groups that users create with the Groups (user-
managed) service.
• What LDAP attribute contains mailing list members? Find out what
attribute lists 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. If this field
contains any spaces, choose a substitution character to replace spaces, since
Google Apps mailing addresses cannot contain spaces.
• Is the LDAP attribute for mailing list members a literal email address, or
a user DN reference? Some mailing list attributes describe members by
email address (literal), and some describe members by a Distinguished Name
(reference). Google Apps Directory Sync can work with either, but you’ll need
to know which you’re using beforehand.
• Do you want to synchronize User Profiles? If you want detailed information

from your LDAP directory server to show up in Google Apps, you can enable
User Profiles synchronization. User Profiles synchronization requires extra
steps to configure, but gives more profile information within Google Apps.
• Do you want to synchronize Shared Contacts? If you want to import

addresses into Google Apps as shared contacts, enable Shared Contacts.
Shared Contacts will be visible to every user on a contacts list. When users
enter email addresses for recipients in Google Apps mail, addresses in
Shared Contacts will show up in Autocomplete. Shared Contacts
synchronization is also often used for trials with a small number of users.

Important: Shared Contacts do not show immediately. After you synchronize
Shared Contacts, it may take up to 24 hours for the changes to appear in
Google Apps.
• Do you want to replace domain names? By default, all synchronized users

will have their domains changed to match the domain name you are using in
Google Apps. This can be very helpful if you are running a trial using a
different domain name. If all your users in your LDAP directory server have
the same domain name as your Google Apps domain, it doesn’t matter
whether you replace domain names or not.
• Do you want to delete users who are not in your LDAP directory server,
or just suspend them? By default, users not found on your LDAP directory
server will be deleted. If you are worried about losing user data, you can set
the directory sync utility to suspend users instead of deleting them. This
allows for data recovery if users are later recovered.
• Do you want to delete suspended users, or leave them alone? By default,

the directory sync utility will ignore suspended users. You can instead set
directory sync to delete any suspended users that are not found in your LDAP
directory server query.
Note: You cannot use this setting if you set directory sync to suspend users in
LDAP directory server instead of deleting them.
• Are there any exceptions on your LDAP directory server that you don’t
want to synchronize? Your LDAP directory server may contain users or
groups that you don’t want to synchronize with Google Apps. This could
include internal users, resources like printers or conference rooms, archived
or deleted users, test accounts, or other entries that belong in your LDAP
directory server but not in Google Apps. Find out which users and groups
you’d like to exclude, and look for any common pattern that may simplify
exception rules.
• 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 directory server. This could
include new users not listed in your LDAP directory server, pilot test accounts,
shared Google Apps accounts, or other entries that belong in your Google
Apps account but not your LDAP directory server. Find out which users and
groups you’d like to exclude, and look for any common pattern that may
simplify exception rules.
Checklist: Before You Begin

Before you configure synchronization, gather the information you need from
Google Apps, as well as your own LDAP server and mail server.
Each item on the checklist is detailed below:
• Google Apps Directory Sync Domain: Before you configure

synchronization, set up your domain in Google Apps.
20 Release 1.6.21
Note: The directory sync utility does not create a domain for you, so you will
need to add it beforehand.
Collect the exact domain name from the Google Apps Control Panel. Note
that you can only synchronize a primary domain, not a domain alias.
• Google Apps Administrator: Note the administrator username and

password for an administrator in Google Apps.
• LDAP Structure Information: Gather information about your LDAP directory

server. You will need to know what OUs contain users you want to sync and
which LDAP attributes contain important information. To collect this
information, use an LDAP browser. For more information, see “Useful LDAP
Tools” on page 16.
• LDAP Base DN: The directory sync utility 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 the
directory sync utility 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.
A typical Base DN for a domain called ad.example.com might be as follows:

ou=test,ou=sales,ou=melbourne,dc=ad,dc=example,dc=com

Note: You can use multiple Base DNs in a configuration. You can specify a
separate Base DN for each synchronization rule.
• LDAP Administrator: Collect the username and password of an

administrator for Google Apps Directory Sync to use when connecting to your
LDAP directory server. This user should have read and execute permissions
for the whole LDAP subtree you want to synchronize. 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.
• LDAP Queries: Decide which users to synchronize from your LDAP directory
server, and create one or more LDAP queries that will find those users. For
more information, see “LDAP Queries” on page 23.
• Mapping: Plan which users will go into Google Apps. 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.
• Mail Server: The SMTP mail server to use for notifications. The directory
sync utility connects to the mail server you specify. You will need the domain
name or IP address of a mail server that will relay messages from the
directory sync server. If the SMTP server you plan to use requires SMTP
authentication, find or create a username and password for SMTP
authentication.
Once you have collected this information and decided on how you want to
synchronize users in different organizations, you’re ready to begin with
Configuration Manager.
If you begin using Configuration Manager and find you need more information,
save your configuration file. You can return to Configuration Manager and load
your XML file after you collect the needed information.
Pilot Domain
You may decide to run a pilot program, using a test domain instead of your LDAP
primary domain to try Google Apps and Google Apps Directory Sync. Using
Google Apps Directory Sync, this is very easy.
Set up the pilot domain as a primary domain in Google Apps. Then, in

Configuration Manager, enter the pilot domain as your Google Apps domain, and
use a Google Apps administrator for that domain. In Google Apps Settings,
enable “Replace domain names in LDAP email addresses (of users and groups)
with this domain name.” The Google Apps Directory Sync will rename all your
accounts to that pilot 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” on page 45.
22 Release 1.6.21
Planning for Large or Complex Deployments
If your deployment is large enough or complex enough to require multiple
configuration files, you may need extra planning and preparation.
An LDAP query that returns too many results may time out before returning
results. If this happens, do not create multiple configuration files to reduce load,
since this will actually slow down performance of Google Apps Directory sync.
Instead, consider using a single configuration file with multiple LDAP queries.
For instance, instead of looking for all users in an organization with a single query,
create two rules, one to search for users with an address that starts with any letter
A through M, and another that starts with any letter N through Z (plus any
numbers or other supported characters). Splitting up your LDAP query into
multiple queries with fewer results is called sharding. Sharding is a common
solution to LDAP timeout issues for large deployments.
You can also run the same configuration file, and synchronize only groups, or
synchronize only users. For more information on how to do this, see “Command
Line Synchronization” on page 109.
LDAP Queries
The directory sync utility uses the LDAP query language to gather information
from your directory server. The LDAP query language is a flexible standard that
supports complex and powerful logical queries.
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 “Useful LDAP Tools” on page 16.
Google Apps Directory Sync strictly adheres to RFC 2254, which defines
international standards on LDAP filters.
Most of the search rules in the directory sync utility 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.
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)
24 Release 1.6.21
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)))
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=*)))
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=*))

26 Release 1.6.21
Chapter 4
Installation Chapter 4
About Installation
To run Google Apps Directory Sync, install the directory sync utility on your server.
The directory sync utility is designed to run on Windows, Linux or Solaris
machines.
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 the directory sync utility in the
same directory.
The sections below contain system requirements, and instructions on how to

install, upgrade or uninstall the directory sync utility on your server.
Enable APIs
Google Apps Directory Sync uses the Google Apps User API to update your
Google Apps domain. For successful synchronization, log in to Google Apps and
enable the User API.
To enable the User API access for your domain:
1. Log in to your control panel.
2. Click Users and Groups.
3. Click the Settings tab.
4. For Provisioning API: Check the box next to Enable provisioning API.
5. Click Save changes.
For more information, see the Google Apps Help Center.
Installation 27
Install Google Apps Directory Sync
To install the directory sync utility:
1. Go to the Directory Sync microsite at:

http://google.com/apps/directorysync
2. Choose the operating system of the server where you plan to run the directory
sync utility and click Download.
3. Download and run the installer.
28 Release 1.6.21
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 27.
Upgrade Google Apps Directory Sync

Google Apps Directory Sync 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 the directory sync

utility 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

The directory sync utility also includes an uninstaller.
To remove the directory sync utility:
1. Open a command line interface and go to the directory that contains the
directory sync utility.
Installation 29
2. Run the following command:
uninstall
3. In the uninstaller, click Next to uninstall the directory sync utility.
4. Once uninstallation has completed close the uninstaller.
All directory sync utility files and all libraries not used by other programs will be
removed. Log files and XML configuration files will not be deleted.
30 Release 1.6.21
Chapter 5
Configuration Chapter 5
About Configuration
Configuration Manager is a step-by-step graphical user interface that walks you
through creating and testing an XML configuration file for Google Apps Directory
Sync.
Note: Before you use Configuration Manager, collect information about your LDAP
directory server and your Google Apps setup. For more information, see
“Planning Your Synchronization Strategy” on page 16.‘
In Configuration Manager, you can:
• Set up and test a connection to Google Apps.
• Configure which users, groups, and shared contacts in Google Apps to

synchronize.
• Set up and test a connection to your LDAP server.
• Configure LDAP search criteria for synchronization.
• Set up notifications and logging.
• Run a simulated synchronization to verify your settings.
Once you have set up your configuration in Configuration Manager, you can run
your actual synchronization from the command line. See “Synchronization” on
page 109.
Configuration Manager does not change the data in your LDAP directory server or
Google Apps. It is strictly used to configure and simulate synchronization.
Configuration Manager walks you through each step of configuring Google Apps
Directory Sync. Once you have finished each page, click Next to go to the next
step. You can also go back to previous steps with the Previous button, or jump
directly to any step using the left side navigation menu.
The directory sync utility includes several ways to customize search rules and
filters. When collecting information from your LDAP server, you can define LDAP
queries to extract information. The directory sync utility supports RFC 2254, the
international standard on LDAP Filters. For the details, see RFC 2254:
Configuration 31
http://www.ietf.org/rfc/rfc2254.txt
The directory sync utility also includes some non-LDAP filters. In these, you can
use regular expressions to filter for patterns of text. Regular expressions use
standard Java regular expression syntax, which is similar to most standard regular
expression syntax standards.
In Configuration Manager, required fields are marked by blue highlight.
Configuration Files
In Configuration Manager, you can save or load configuration files to manage
multiple configuration files and store settings for later. All configuration files are
XML files.
To save configuration settings under a new name, select File->Save As from the
top menu and specify the directory and filename you wish to use. If you overwrite
an existing file, Configuration Manager will save the existing file as a copy with the
timestamp in the file name.
To save configuration settings under the existing name, select File->Save from
the top menu. If you are editing a new configuration file you haven’t saved yet, this
option will be greyed out. If you overwrite an existing file, Configuration Manager
will save the previous file as a copy with the timestamp of when the file was
overwritten.
To open a configuration file, select File->Open from the top menu and choose the
configuration file. The user interface will then show the settings for that
configuration file. To open a recent configuration file, select File->Open Recent
and choose the configuration file.
To start a new configuration file, select File->New from the top menu.
Configuration Manager will load a new file with no configuration rules specified.
General Settings
On the General Settings page, specify which categories of object to synchronize.
Notice about Google Apps Directory Sync

Before you enable Google Apps Directory Sync 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.
32 Release 1.6.21
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).
General Settings
The General Settings page also includes a reminder to enable the Provisioning
API. For more information about the Provisioning API, see “Enable APIs” on
page 27.
Configuration 33
On the General Settings page, specify the following:
General Setting Description
Synchronization of Google How Google Apps Directory Sync

Organizations (from LDAP synchronizes users from LDAP Org Units into
Org Units) Google Organizations.
Options:
• Sync LDAP Org Units, and move users

into Google Organizations, as specified
in the User Sync Rules. Google Apps
Directory Sync will create and delete
Organizations and move users into
specified organizations.
• Do not create or delete Google

Organizations, but move users between
existing Organizations, as specified in
the User Sync Rules. Google Apps
Directory Sync move users into specified
organizations, but will not modify your
organizations structure in Google Apps.
• Ignore and Google Organization

information (Any new users are created
in the default Google Organization)
The default is “Ignore and Google

Organization information (Any new users are
created in the default Google Organization)”.
Users Whether Google Apps Directory Sync should

synchronize users. Checked by default.
For more information, see “LDAP Users” on

page 56.
Uncheck if you do not want to synchronize

users.
Groups Whether Google Apps Directory Sync should

synchronize groups. Checked by default.
For more information, see “LDAP Groups” on

page 72.
Uncheck if you do not want to synchronize

groups.
34 Release 1.6.21
General Setting Description
Profiles Whether Google Apps Directory Sync should

synchronize user profiles. Unchecked by
default.
For more information, see “LDAP User

Profiles” on page 81.
Check if you want to synchronize user profiles.
Contacts Whether Google Apps Directory Sync should

synchronize shared contacts. Unchecked by
default.
For more information, see “LDAP Shared

Contacts” on page 90.
Check if you want to synchronize user profiles.
Google Apps Configuration

The first step in Configuration Manager is to set how Directory Sync will connect
to Google Apps.
To start the application, run Google Apps Directory Sync Config Manager from the
Start menu, or run config-manager from the command line in the directory where
you installed the directory sync utility.
Before you begin setup in Google Apps Configuration, collect information about
your Google Apps domain and your LDAP directory server. For details on what
information you’ll need, see “Planning Your Synchronization Strategy” on page 16.
Configuration 35
Google Apps Settings
Enter your Google Apps login and connection information in this section.
Specify the following:
Google Apps Setting Description
Admin Email The email address used to log into Google Apps. This
Address address should be a valid Google Apps administrator
in the domain that you are synchronizing.
The domain must match the Domain name.
Example: admin@example.com
Admin Password Enter the password for the Google Apps administrator.
Example: swordfish
Passwords are stored in an encrypted format.
Domain Name Enter the domain you wish to synchronize. You must
use the primary domain in Google Apps, not a domain
alias.
If you enter a domain that is different from the domain

on your LDAP server, Google Apps Directory Sync will
rename all users and use the Domain name listed here
instead.
Example: example.com
36 Release 1.6.21
Replace domain If checked, all LDAP email addresses are changed to

names in LDAP match the domain listed in Domain Name. For
email addresses (of instance, if your Domain Name is example.com, and
users and groups) your LDAP query returns an email address
with this domain user23@domain.com, then the directory sync utility
name. synchronizes user23@example.com.
If unchecked, all LDAP email addresses keep their

original domain name.
Note: Domain names for shared contacts and user

profiles are not replaced.
By default, this is checked.
SSL Proxy Host If your server is running behind a firewall that requires
Name an SSL Proxy to connect to an outside server, enter
the proxy host name here.
(if needed)
If you can connect directly to the internet from this
machine, leave this field blank.
Example: firewall02-http.mixateriacorp.com
SSL Proxy Host Port If your server is running behind a firewall that requires
an SSL Proxy to connect to an outside server, enter
(if needed) the proxy host port here. Otherwise, leave this field
blank.
Common ports for SSL proxy are 80, 8080, 3128 and
1080.
Example: 80
SSL Proxy User If your server is running behind a firewall that requires
Name an SSL Proxy to connect to an outside server, and that
proxy requires authentication, enter the proxy
(if required) authentication user name here.
Otherwise, leave this field blank.
Example: proxyuser01
SSL Proxy If your server is running behind a firewall that requires

Password an SSL Proxy to connect to an outside server, and that
(if required) authentication password here.
Example: swordfish
Configuration 37
HTTP Proxy Host If you use a different proxy server for HTML
Name connections than SSL connections, enter the HTTP
proxy host here.
(if needed)
Directory Sync always connects to Google Apps on
SSL. The only time the directory sync utility sends
traffic by unencrypted HTTP is to validate a certificate
with the issuing authority.
If you do not use a proxy server, or you use the same

proxy server for HTML and SSL connections, leave
this field blank.
If blank, this field defaults to the value of the SSL Proxy

Host Name field.
Example: firewall02-http.mixateriacorp.com
HTTP Proxy Host If you use a different proxy server for HTML
Port connections than SSL connections, enter the HTTP
proxy host port number here.
(if needed)
If you do not use a proxy server, or you use the same
proxy server for HTML and SSL connections, leave
this field blank.
If blank, this field defaults to the value of the SSL Proxy

Host Port field.
Example: 80
HTTP Proxy User If you use a different proxy server for HTML
Name connections than SSL connections, and your HTML
(if required) authentication user name here.
Example: proxyuser01
HTTP Proxy If you use a different proxy server for HTML

Password connections than SSL connections, and your HTML
(if required) authentication password here.
Example: swordfish
Exclusion Filters for Google Apps

If you have any users on your Google Apps user list who should not be deleted or
moved by the synchronization, add an exclusion filter to protect those users.
38 Release 1.6.21
Other exclusion filters you might want to include are:
• Administrators who are not in your LDAP system
• Users listed in Google Apps but not your LDAP server
• Mailing list addresses you’ve manually added in your Google Apps groups
that are not in your LDAP server
Exclusion rules are based on string values and regular expressions, not LDAP
settings. You can exclude user profiles or shared contacts by their primary sync
key.
This page shows the list of exclusion filters. In a new configuration, this contains
no exclusion rules. To add new exclusion filters, click the Add Rule button at the
bottom of the screen.
In the list of Exclusion Filters, you can change existing filters as follows:
• Reorganize: Click the up arrow or down arrow icon to change the order of
exclusion filters.
• Edit: Click the notepad icon to edit the settings of an exclusion filter.
• Delete: Click the X icon to delete the exclusion filter.
Example Google Apps Exclusion Rules

Listed below are samples of common exclusion rules. Note that the exact text of
these rules will vary based on your needs.
Configuration 39
Users not in your LDAP Server
The directory sync utility will delete users from your list of Google Apps users and
from all Google Apps groups if they are not listed in your LDAP directory server.
Therefore, for single users not listed in your LDAP, add the following two rules.
First rule:
• Type: User Name
• Match Type: Exact Match
• Exclusion Rule: username@example.com
Second rule:
• Type: Member Name
• Exclusion Rule: username@example.com
Pattern of users
If your Google Apps users list includes users that aren’t in your LDAP directory
server, and they all match a specific text pattern, you can use a substring or
regular expression instead of creating a rule for each user. In this example, all
these users have the name “appstrial” in their primary address, such as
appstrial-lydia@example.com and appstrial-manesh@example.com.
First rule:
• Type: User Name
• Match Type: Substring
• Exclusion Rule: appstrial
Second rule:
• Exclusion Rule: appstrial
Custom Google Apps Groups
If you have groups listed in Google Apps that don’t match a mailing list in your
LDAP directory server, the directory sync utility will delete them, Therefore, add
the following rule.
• Type: Group Name
• Exclusion Rule: FloridaSalesTeam@example.com
40 Release 1.6.21
External Mailing List Members
Groups in Google Apps can also include mailing address that are outside your
domain. Google Apps Directory Sync will remove these unless you add a Member
Name exclusion filter.
In this example, the Google Apps group also include addresses in two other
domains, gmail.com and electric-automotive.com.
First Rule:
• Exclusion Rule: @gmail.com
Second Rule:
• Exclusion Rule: @electric-automotive.com
Add Rule
Click Add Rule at the bottom of the page to create an exclusion rule.
Configuration 41
In the Add Exclusion Rule panel, specify the following to add an exclusion rule.
Keep in mind that this is information on your Google Apps account, not your LDAP
directory server.
Exclusion Rule Setting Description
Type Sets the type of exclusion filter to create: User Name,

Group Name, or Member Name.
• User Email Address: Do not delete any user

whose primary address matches the rule. The
interface displays this choice as USER_NAME.
• Alias Email Address: Do not delete any user with

an alias address that matches the rule. The
interface displays this choice as USER_ALIAS.
• Group Email Address: Do not remove any group

which has a name that matches the rule. The
interface displays this choice as GROUP_NAME.
• Group Member Address: Do not remove any

user whose primary address matches this rule
from any groups. The interface displays this choice
as MEMBER_NAME.
• User Profile Primary Sync Key: Do not delete

any user profile if the user’s address matches the
rule. The interface displays this choice as
USER_PROFILE_PRIMARY_KEY.
• Shared Contact Primary Search Key: Do not

remove a shared contact if the contact’s primary
key (specified in the Sync Key field) matches the
rule. The interface displays this choice as
SHARED_CONTACT_PRIMARY_KEY.
42 Release 1.6.21
Match Type The type of rule to match for the filter.
• Exact Match: The address or organization name

must match the rule exactly.
Examples:
User Name: user1@example.com excludes that

single Google Apps user from user list
synchronization, but not group synchronization.
Group Name: FloridaSalesGroup@example.com

excludes that Google Apps group from groups
synchronization.
Member Name: user1@example.com excludes that

single Google Apps user from groups
synchronization.
• Substring Match: The address or organization

name must contain the text of the rule as a
substring.
Examples:
User Name: sales excludes

sales_questions@example.com and
amanda@sales.example.com.
Group Name: Sales excludes

FloridaSalesGroup@example.com and
NorthAmericaSalespeople@example.com.
Member Name: sales excludes

sales_questions@example.com and
amanda@sales.example.com from groups
synchronization.
• Regular Expression: The address or organization

must match the regular expression in the rule.
Examples:
User Name the regular expression team[3-

9]@example.com excludes team3@example.com
through team9@example.com.
Group Name: the regular expression Local Team -

[A-Z][A-Z] excludes the “Local Team - NJ” and
“Local Team - AZ” groups.
Member Name: the regular expression team[3-

9]@example.com excludes team3@example.com
through team9@example.com from groups
synchronization.
Configuration 43
Exclusion Rule The text of the match or regular expression to

compare.
See above for examples for these rules.
Users that meet the requirements for an exclusion filter

will not be deleted. If they are listed on the LDAP
server, the directory sync utility will attempt to add the
user and fail.
LDAP Settings
The LDAP Settings section configures how the directory sync utility connects to
your LDAP directory server and generates your LDAP user list for comparison.
You may need to collect information from your LDAP directory server before you
can enter details in this section.
44 Release 1.6.21
LDAP Connection
Specify your LDAP connection and authentication in this page.
LDAP Connection
Setting Description
Connection Type Choose whether to use an encrypted connection.
If your LDAP server supports an SSL connection and

you wish to use it, choose LDAP + SSL. Otherwise,
choose Standard LDAP.
Example: Standard
Host Name Enter the domain name or IP address of your LDAP

directory server.
Example: ad.example.com, or 10.22.1.1.
Port Specify the host port. The default is 389.
Example: 389
Base DN Enter the Base DN for the subtree to synchronize. Do

not include spaces between commas. If you don’t
know the Base DN, consult your LDAP administrator or
check an LDAP browser.
Example:
ou=test,ou=sales,ou=melbourne,dc=ad,dc=example,
dc=com
Configuration 45
LDAP Connection
Setting Description
Authentication Type The authentication method for your LDAP server
If your LDAP server allows anonymous connections

and you want to connect anonymously, select
Anonymous. Otherwise, select Simple.
Example: Simple
Authorized User Enter the user who will connect to the server. This user
should have read and execute permissions for the
whole subtree.
If your LDAP directory server requires a domain for

login, include the domain for the user as well.
Example: admin1
Password Enter the password for the authorized user.
Example: swordfishX23
Passwords are stored in an encrypted format.
Test Connection
Once you have configured LDAP Authentication settings, click Test Connection.
Configuration Manager will connect to your LDAP server and attempt to log in, to
verify the settings you entered.
46 Release 1.6.21
LDAP Org Units
The LDAP Org Units section configures how the directory sync utility
synchronizes your LDAP org hierarchy with your Google Apps org units. You may
need to collect information from your LDAP directory server before you can enter
details in this section.
Synchronizing org units is optional. If you set “Do not create or delete Google
Organizations, but move users between existing Organizations” in General
Settings, org units will not be synchronized from LDAP. You can still specify which
users go in org units in the LDAP User Sync rules. For more information, see
“LDAP User Sync” on page 64.
Configuration 47
LDAP Org Unit Search Rules
This shows a list of rules used when generating the LDAP org units.
By default, all org units that match these search rules will be added to the Google
Apps org unit hierarchy, and all org units that do not match these search rules will
be removed. You can change this behavior with exclusion filters.
This page shows the list of search rules. In a new configuration, this will be an
empty list. To add a search rule, click the Add Org Unit Search Rule button at the
On the list of Search Rules, you can change existing rules:
search rules.
• Edit: Click the notepad icon to edit the settings of a search rule.
• Delete: Click the X icon to delete a search rule.
Search rules are processed in the order listed. If you would like one search rule to
take priority over another, move that search rule up using the up arrow icon on this
page. If two rules contradict each other, the first rule takes precedence.
48 Release 1.6.21
Add Org Unit Search Rule
To add a new search rule, click Add Search Rule.
LDAP Org Unit Search

Rule Setting Description
Org Unit Description An LDAP attribute that contains the description of each
Attribute org unit.
This field is optional. If left blank, your Org Units will not
contain a description when created.
Example: description
Configuration 49
LDAP Org Unit Search
Rule Setting Description
Scope This determines where in the LDAP directory this rule

applies.
Choose which option to use:
• Subtree: All objects matched by the search, and

anything under those objects, recursively. Subtree
gives the broadest search, but for very large
organizations this can be load-intensive and cause
system problems.
• One-level: All objects matched by the search, and

anything one level underneath them. Does not look
further than one level. One-level provides a limited
search that will avoid causing extreme load for
very large organizations.
• Object: Only objects directly matched by the

search. No recursion of any kind.Object is rarely
used except with very complex LDAP searches. It
allows a search only on the specified object.
Example: Subtree
Rule The search rule for org unit sync to match. This rule is
a standard LDAP query, and allows sophisticated logic
and complex rules for searching. For more information
about LDAP search filters, see “LDAP Queries” on
page 23.
Base DN The Base DN (Distinguished Name) to use for this

search rule. This will override the default Base DN you
specified in LDAP Connection.
This field is optional. In most cases, you can leave this

field blank and use the Base DN specified in the LDAP
Connection page. If you want this rule to use a different
Base DN than the default, specify an alternate base
DN.
Example:
ou=powerusers,ou=test,ou=sales,ou=melbourne,dc=
ad,dc=example,dc=com
LDAP Org Units Exclusion Rules

If you have any org units on your LDAP directory server that match your search
rules but should not be added to Google Apps, add an LDAP org unit exclusion
rule.
50 Release 1.6.21
Some examples of reasons for LDAP org unit exclusion rules:
• Internal org units that do not have outside email addresses
• OUs for printers, conference rooms, and other non-user resources
• Test OUs on your LDAP directory server
• OUs that are not participating in a pilot program
Note: To exclude individual org units, add a separate rule for each org unit.
This page shows the list of exclusion filters. In a new configuration, this will be an
empty list. To add exclusion filters, click the Add Rule button at the bottom of the
screen.
exclusion filters.
Example LDAP Org Unit Exclusion Rules

Configuration 51
Sample Substring Match: Defunct OUs
Several organizational units are no longer in use because two nearby offices
combined together. The defunct OUs all have “stpaul” in the DN.
• Match Type: Substring Match
• Rule: stpaul
Sample Exact Match: Secure OUs
Three specific organizational units are top security and should not be
synchronized.
Add a separate rule for each special LDAP mailing list.
First rule:
• Rule: ou=earlystatements,u=finance,ou=users,dc=ad,dc=example,dc=com
Second rule:
• Rule: ou=confidential,ou=legal,ou=users,dc=ad,dc=example,dc=com
Sample Regular Expression Match: Internal Testing OUs
About thirty extra OUs are listed in the LDAP directory server, but they are only
used for internal load testing. All the test users follow the same name pattern:
ou=internaltextX,dc=ad,dc=example,dc=com, where X is a number.
• Match Type: Regular Expression
52 Release 1.6.21
Rule: ou=internal-test[0-9]*,dc=ad,dc=example,dc=com
Add Rule
Click the Add Rule button at the bottom of the page to exclude an org unit in your
LDAP server from synchronization.
Exclude Type This Exclude Type is always Org Unit DN.
• Org Unit DN: Base the exclusion rule on the

Distinguished Name (DN) of the org unit to
exclude.
Match Type The type of rule to use for the filter.
• Exact Match: The org unit DN must match the rule

exactly, with the domain name added on.
Note: In many cases, Substring Match yields

better results than Exact Match.
• Substring Match: The organization unit DN must

contain the text of the rule as a substring.
• Regular Expression: The org unit DN must match

the regular expression specified.
Configuration 53
Rule The match string or regular expression for the

exclusion rule. Behavior of this field depends on the
Match Type you choose.
Addresses that contain this string (or match this

regular expression) will not be added to Google Apps,
and will be deleted if found.
Examples:
• Exact Match:
ou=test,ou=sales,ou=melbourne,dc=ad,dc=exam
ple,dc=com
• Substring Match: ou=test
• Regular Expression: ou=printer.*
LDAP Org Unit Mappings

This shows a list of rules used when generating the LDAP org units.
Specify how OUs on your LDAP server correspond to Org Units in Google Apps.
Add mappings for top-level Org Units, and Directory Sync will automatically map
sub-organizations on your LDAP directory server to Google Apps Org Units with
the same name. Add specific rules to override sub-organization mappings.
.
This page shows the list of mappings. In a new configuration, this will be an empty
list. To add a search rule, click the Add Org Mapping button at the bottom of the
screen.
54 Release 1.6.21
search rules.
Examples of Mapping
Listed below are samples of common mappings. Note that the exact text of these
rules will vary based on your needs.
Sample Mapping: Multiple Locations
In this example, an LDAP directory server has an organizational hierarchy split

between two office locations: Melbourne and Detroit. The Google Apps org unit
hierarchy will match the same hierarchy.
First Rule:
• (LDAP) DN: ou=melbourne,dc=ad,dc=example,dc=com
• (Google Apps) Name: Melbourne
Second Rule:
• (LDAP) DN: ou=detroit,dc=ad,dc=example,dc=com
• (Google Apps) Name: Detroit
Sample Mapping with Exceptions: Departments
In this example, an LDAP directory server has an organizational hierarchy split

based on different departments: Sales, HR, Support, Marketing, IT and
Executives. Most of the Google Apps org unit hierarchy will match the same
hierarchy, under the Users group, but the IT team will synchronize to the root org
unit, and Executives will synchronize to a separate org unit
First Rule (general case for most OUs):
• (LDAP) DN: ou=users,dc=ad,dc=example,dc=com
• (Google Apps) Name: Users
Second Rule (exception for IT):
• (LDAP) DN: ou=it,ou=users,dc=ad,dc=example,dc=com
• (Google Apps) Name: /
Configuration 55
Third Rule (exception for Executives):
• (LDAP) DN: ou=executives,ou=users,dc=ad,dc=example,dc=com
• (Google Apps) Name: Executives
Add Mapping
To add a new search rule, click Add Mapping.
Mapping Setting Description
(LDAP) DN The Distinguished Name (DN) on your LDAP directory

server to map.
Example: ou=melbourne,dc=ad,dc=example,dc=com
(Google Apps) The name of the org unit in Google Apps to map.
Name
To add users to the default Organization in Google
Apps, enter a single forward slash /.
Example: Melbourne
LDAP Users
The LDAP Settings section configures how Google Apps Directory Sync
generates your LDAP user list for comparison. You may need to collect
information from your LDAP directory server before you can enter details in this
section.
56 Release 1.6.21
WARNING: After you delete a user, you can’t add the same user for 5 days.
Important: You must add at least one LDAP User Sync rule to run Google Apps
Directory Sync. This determines which users are synchronized and added in
Google Apps. Even if you only use Google Apps Directory Sync to sync groups
and not users (See “Synchronization options” on page 110), the users must be
read in, in order to resolve Reference Attributes for group members or group
owners.
Configuration 57
LDAP User Attributes
Specify what attributes Google Apps Directory Sync will use when generating the
LDAP user list.
LDAP User Attribute

Setting Description
Server Type The type of LDAP server that you are using with the
directory sync utility.
If you are using a Lotus Domino, Microsoft Active

Directory, or Open LDAP directory server, select that
server type. Otherwise, select Other.
Example: Microsoft Active Directory
Email Address The LDAP attribute that contains a user’s primary

Attribute email address.
Example: The default is mail.
Alias Address One or more attributes used to hold alias addresses.

Attribute These addresses will be added into Google Apps as
nicknames of the primary address listed in the Email
(if needed) Address Attribute field.
Example: proxyAddresses
58 Release 1.6.21
LDAP User Attribute
Setting Description
Domino Alias Only for Lotus Domino servers. One or more attributes
Address Attribute used to hold internal Domino alias attributes, which are
stored as usernames without domain information.
(if needed) These addresses will be formatted as email addresses
and placed as aliases to the primary address listed in
the Email Address Attribute field.
If you are using a Lotus Domino server but your alias

address attribute stores full SMTP email addresses, list
the attribute in Alias Address Attributes, not Domino
Alias Address Attributes.
Example: uid
Domino Only for Lotus Domino servers. If an address contains

Replacement a space, Google Apps Directory Sync will substitute
Character this character instead.
Example: The most common values are dot (“.”) and

underscore (“_”).
Use Defaults
Click this button to use the default values for your server type, as follows:
• Lotus Domino: Email Address Attribute mail, Domino Alias Address

Attribute uid.
• MS Active Directory: Email Address Attribute mail, Alias Address Attribute

proxyAddresses.
• OpenLDAP: Email Address Attribute mail.
• Other: Email Address Attribute mail.
Configuration 59
LDAP Extended Attributes
LDAP Extended Attributes are optional LDAP attributes that you can use to import
additional information about your Google Apps users, including passwords.
All attributes are optional. If you do not specify an attribute, the directory sync
utility will not import this information.
LDAP Extended Attribute

Setting Description
Given Name Attribute An LDAP attribute that contains each user’s

given name. (In the English language, this is
usually the first name.)
This is synchronized with the user’s name in

Google Apps.
Example: givenName
Family Name Attribute An LDAP attribute that contains each user’s

family name. (In the English language, this is
usually the last name.)
This is synchronized with the user’s name in

Google Apps.
Example: surname
Mailbox Quota Size Attribute This field is not implemented.
60 Release 1.6.21
Setting Description
Synchronize Passwords Indicates which passwords the directory sync

tool will synchronize.
Options are:
• Only for new users: When the directory

sync utility creates a new user, it will
synchronize that user’s password. Existing
passwords are not synced. Use this option
if you want your users to manage their
passwords in Google Apps.
• For new and existing users: The

directory sync utility will always sync all
user passwords. Existing passwords on
Google Apps are overwritten. Use this
option if you want to manage user
passwords on your LDAP server.
Example: Only for new users
Password Attribute An LDAP attribute that contains each user’s

password. If you set this attribute, your users’
Google Apps password will be synchronized to
match your users’ LDAP passwords.
The password field supports string or binary

attributes.
Example: CustomPassword1
Configuration 61
Setting Description
Password Encryption Method The encryption algorithm that the password

attribute uses.
• SHA1: Passwords in your LDAP directory

server use SHA1 encryption.
• MD5: Passwords in your LDAP directory

server use MD5 encryption.
• Plaintext: Passwords in your LDAP

directory server are not encrypted. The
directory sync utility will read the password
attribute as unencrypted text, then
immediately encrypt the password using
SHA1 encryption and synchronize with
Google Apps.
Note: The directory sync utility will never

save, log or transmit your passwords
unencrypted. Simulate sync and full sync
logs show the password as a SHA1
password.
Use this field only if you also specify a

Password Attribute. If you leave the Password
Attribute field blank, when you save and reload
the configuration resets to the default of SHA1.
Note that some password encoding formats

are not supported. Check your LDAP directory
server with a directory browser to find or
change your password encryption.
By default, Active Directory and Lotus Domino

directory servers do not store passwords in
any of these formats. Consider setting a
default password for new users and requiring
users to change passwords on first login.
Example: SHA1
Force new users to change When checked, new users must change
password passwords the first time they log in to Google
Apps.
This allows you to set an initial password,

either from an LDAP attribute or by specifying
a default password for new users, that must be
changed the first time the user logs on to their
Google Apps account
62 Release 1.6.21
Setting Description
Default password for new Enter a text string that will serve as the default
users password for all new users. If the user does
not have a password in the password attribute,
directory sync will use the default password.
Important: If you enter a default password

here, be sure to enable “Force new users to
change password” so that users will not keep
their default password.
Example: swordfishX2!
Google Apps Users Deletion/ Options for deleting and suspending users.
Suspension Policy
Available options:
• Delete only active Google Apps users

not found in LDAP (suspended users
are retained). Active users in Google
Apps will be deleted if they are not in your
LDAP, but suspended users are left alone.
This is the default setting.
• Delete active and suspended users not

found in LDAP. All users in Google Apps
will be deleted if they are not in your LDAP,
including suspended users.
• Suspend Google Apps users not found

in LDAP, instead of deleting them.
Active users in Google Apps will be
suspended if they are not in your LDAP.
Suspended users are left alone.
Configuration 63
LDAP User Sync
This shows a list of rules used when generating the LDAP user list.
By default, all users that match these search rules will be added to the Google
Apps user list and all users that do not match these search rules will be removed.
You can change this behavior with exclusion filters.
empty list. To add a search rule, click the Add Search Rule button at the bottom
of the screen.
Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP
directory. Instead, limit the LDAP administrator authority on your LDAP directory
server, removing access to any OUs on your LDAP directory server that you do
not want to synchronize.
search rules.
Add Search Rule
To add a new search rule, click Add Search Rule.
64 Release 1.6.21
Depending on your General Settings, you may see different versions of the Add
LDAP User Sync Rule menu.
Configuration 65
LDAP User Sync

Setting Description
Place users in the This option only shows if you have Synchronization of
following Google Google Organizations set to “Sync LDAP Org Units” or
Apps Org Unit “Do not create or delete Google Organizations, but
move users between existing Organizations” in
General Settings.
Specify which Google Apps org unit should contain

users that match this rule. If the org unit specified does
not exist, directory sync will add the users to the root
level org unit in Google Apps.
Options include:
• Org Unit based on Org Units Mappings and DN.

This option only shows if you have
Synchronization of Google Organizations set to
“Sync LDAP Org Units” in General Settings. Add
users to the org unit that maps to the user’s DN on
your LDAP server. This is based on your Org
Mappings. This will show in the LDAP User Sync
list as [derived]. For more information, see
“LDAP Org Unit Mappings” on page 54.
• Org Unit Name. Add all users that match this rule
to the same Google Apps Org Unit. Specify the org
unit in the text field.
Example: Users
• Org Unit name defined by this LDAP Attribute.

Add each user to the org unit with the name
specified in an attribute on your LDAP directory
server. Enter the attribute in the text field.
Example: extensionAttribute11
66 Release 1.6.21
LDAP User Sync
Setting Description
Suspend these This option only shows if you have Synchronization of

users in Google Google Organizations set to “Ignore any Google
Apps Organization information” in General Settings.
Suspend all users that match this LDAP user sync rule.
The directory sync utility suspends users that already

exist in Google Apps. User data is retained.
The directory sync utility will add new users that do not
yet exist in Google Apps. The new users are added as
suspended users, and are not active users.
Suspended users will not show up in your Global
Address List.
Use for an LDAP query that returns deleted or

suspended users on your LDAP directory server.
If you are importing active users with this rule, leave

this unchecked.
Scope This determines where in the LDAP directory this rule

applies.

system problems.

search that will avoid causing extreme load for
very large organizations.

search. No recursion of any kind.Object is rarely
Example: Subtree
Configuration 67
LDAP User Sync
Setting Description
Rule The search rule for user sync to match. This rule is a
standard LDAP query, and allows sophisticated logic
and complex rules for searching. For more information
about LDAP search filters, see “LDAP Queries” on
page 23.
Example 1: To match all objects (this may cause load

problems):
objectclass=*
Example 2: To match all human users:
• For OpenLDAP:
• For Active Directory:

• for Lotus Domino:



DN.
Example:
LDAP User Exclusion Rules

If you have any users on your LDAP directory server that match your search rules
but should not be added to Google Apps, add an LDAP user exclusion rule.
Some examples of reasons for LDAP user exclusion rules:
• Internal users who do not have outside email addresses
• Printers, conference rooms, and other non-user resources
• Test users on your LDAP directory server
• Users who do not want a Google Apps mailbox
68 Release 1.6.21
settings.
Note: To exclude individual users, add a separate rule for each user.
empty list. To add exclusion filters, click the Add Exclusion Filter button at the
exclusion filters.
Example LDAP User Exclusion Rules

Sample Substring Match: Printers
In this example, printers are listed as LDAP users and would match the LDAP
query given. However, the printers all have the word “printer” in the name. The
rule looks for that substring.
• Exclude Type: Primary Address
• Rule: printer
Configuration 69
Sample Exact Match: Opt-Out Users
Two users have opted out of Google Apps and should not be synchronized.
Add a separate rule for each special user.
First rule:
• Match Type: Substring Match or Exact Match
• Rule: atif
Second rule:
• Match Type: Substring Match or Exact Match
• Rule: svetlana
Sample Regular Expression Match: Test Users
About five hundred test users are listed in LDAP, but they are only used for
internal load testing. All the test users follow the same name pattern: internal-
testX, where X is a number, and all test users are in the same domain.
• Rule: internal-test[0-9]*@example.com
Add Exclusion Filter

Click the Add Exclusion Filter at the bottom of the page to exclude a user or
organization in your LDAP server from synchronization.
70 Release 1.6.21
• Exact Match: The address must match the rule

exactly, with the domain name added on.
Note: In many cases, Substring Match yields

better results than Exact Match.
Example: maria (if you are using the domain

example.com) would exclude only the user
maria@example.com.

substring.
Example: “test” would exclude

testadmin@example.com and
salestest1@example.com.

must match the regular expression specified.
Example: internal.*@example.com would exclude

internalhelpdesk@example.com and
internal@example.com.
Exclude Type What kind of LDAP data to exclude.
• Primary Address: Directory Sync will exclude

primary addresses that match this rule. The
interface displays this choice as ADDRESS.
• Alias Address: Directory Sync will exclude aliases

that match this rule. The interface displays this
choice as ALIAS.
If you want to exclude both primary addresses and

alias addresses, create two exclusion rules.


Examples:
• Exact Match: maria
• Substring Match: internal-list
• Regular Expression: internal.*@example.com
Configuration 71
LDAP Groups
Set up synchronization for Google Groups for Enterprise in the LDAP Groups
page. Google Groups for Enterprise are similar to LDAP mailing lists, and allow
users to send email to multiple recipients with a single email address. You can
also use groups to share content, including Google Docs, Sites, Videos and
Calendars.
The LDAP Settings section configures how Google Apps Directory Sync
generates a list of groups from your LDAP directory server. You may need to
collect information from your LDAP directory server before you can enter details in
this section.
72 Release 1.6.21
User-Defined Groups and Google Apps Directory Sync
If you have enabled the Groups (user-managed) service in the Google Apps
control panel, you can let users create their own groups. These groups are not
centrally administered and are controlled by your users.
The directory sync utility will automatically detect groups that users create, and
will not delete or overwrite them.
LDAP Group Search Rules

Groups in Google Apps are a special kind of email address that direct mail to
many addresses at once. Google Apps Directory Sync can synchronize groups
with your LDAP directory server mailing lists.
This page shows the list of LDAP Group Sync rules. In a new configuration, this
will be an empty list. To add mail lists, click the Add Rule button at the bottom of
the screen.
In the list of Mail List rules, you can change existing filters as follows:
exclusion filters.
Configuration 73
Add Group Search Rule Filter (LDAP)
Click the Add Rule at the bottom of the page to synchronize one or more
addresses as mailing lists.
The first tab you see is the LDAP tab, which contains information on which LDAP
objects to synchronize, and which attributes to use for groups information.
To view the groups you have in Google Apps, see the Google Apps control panel.
Attribute Fields: Reference vs. Literal
For two entries (Member and Owner) you have a choice of two attributes, a
Reference attribute or a Literal attribute. Enter only one of them.
To determine which to use, use an LDAP browser to look at the contents of the
field you want to use:
• If the field contains an email address such as listowner@example.com then

use the Literal attribute.
• If the field contains a distinguished name such as

CN=listowner,OU=administrators,OU=example,OU=com then use the
Reference attribute.
74 Release 1.6.21
LDAP Group Rule

Setting Description
Scope Where to apply the mail list rule.
Choose which option to user:

system problems.

search that will avoid causing load for very large
organizations.

search. No recursion of any kind. Object is rarely
Example: Subtree
Rule The LDAP query for Group Sync to match. This allows
sophisticated logic and complex rules for searching.
For more information about LDAP search filters, see
“LDAP Queries” on page 23.
Example: (objectclass=dominoGroup)


DN.
Example:
Group Email An LDAP attribute that contains the email address of

Address Attribute the group. This will become the group email address in
Google Apps.
Example: mail
Configuration 75
LDAP Group Rule
Setting Description
Group Display Name An LDAP attribute that contains the display name of
Attribute the group. This will be used in the display to describe
the group, and does not need to be a valid email
address.
Group Description An LDAP attribute that contains the full-text description

Attribute of the group. This will become the group description in
Google Apps.
This field is optional.
Example: extendedAttribute6
Member Reference An attribute that contains the DN of mailing list

Attribute members in your LDAP directory sync.
(Either this field or Google Apps Directory Server looks up the email
Member Literal addresses of these members and adds each member
Attribute is to the group in Google Apps.
required.)
Example: memberUID
Member Literal An attribute that contains the full email address of

Attribute mailing list members in your LDAP directory sync.
(Either this field or Google Apps Directory Server adds each member to
Member Reference the group in Google Apps.
Attribute is
required.) Example: memberaddress
Owner Reference An attribute that contains the DN of each group’s

Attribute owner.
Google Apps Directory Server looks up the email

addresses of each mailing list’s owner and adds that
address as the group owner in Google Apps.
Example: ownerUID
Owner Literal An attribute that contains the full email address of each
Attribute group’s owner.
Google Apps Directory Server adds that address as

the group owner in Google Apps.
Example: owner
76 Release 1.6.21
Edit LDAP Group Rule (Prefix-Suffix)
If you need the directory sync utility to add a prefix or suffix to group names, user
names or owner names in Google Apps, list them here.
LDAP Group Rule Setting Description
Group Name Prefix Text to add at the beginning of each group

name.
Example: groups-
Group Name Suffix Text to add at the end of each group name.
Example: -list
Replace spaces in group If the group name in your LDAP server

names with contains any spaces, they will be replaced with
this.
If you leave this blank, the directory sync utility

will remove spaces and concatenate group
names.
Example: underscore (_)
User Name Prefix Text to add at the beginning of each user name
for group members.
User Name Suffix Text to add at the end of each user name for
group members.
Owner Name Prefix Text to add at the beginning of each user name
for group owners.
Owner Name Suffix Text to add at the end of each user name for
group owners.
Configuration 77
LDAP Group Exclusion Rules
You can exclude particular addresses from being imported as groups.
If you have any entries in your directory server that match a mail list rule, but
should not be treated as a mailing list, list them here. This might include:
• Internal mailing lists that do not have outside email addresses
• Printers, conference rooms, and other non-user resources
• Mailing lists that should be treated as individual users, with separate

mailboxes and settings.
settings.
empty list. To add exclusion filters, click the Add Rule button at the bottom of the
screen.
In the list of exclusion filters, you can change existing filters as follows:
exclusion filters.
Example LDAP Group Exclusion Rules

78 Release 1.6.21
Sample Substring Match: Defunct Mailing Lists
Several mailing lists are no longer in use because two nearby offices combined
together. The defunct lists all have “stpaul” in the address.
• Rule: stpaul
Sample Exact Match: Secure Mailing Lists
Three small-distribution LDAP mailing lists are top security and should not be
imported.
Add a separate rule for each special LDAP mailing list.
First rule:
• Rule: finance-early-statements
Second rule:
• Rule: internal-security
Third rule:
• Rule: legal-confidential
Sample Regular Expression Match: Test Lists
About five hundred test mailing lists are listed in LDAP, but they are only used for
Configuration 79
Click Add Rule at the bottom of the page to prevent an address from being
treated as a mailing list.
Type Sets the type of exclusion filter to create: User Name,

Group Name, or Member Name.
• User Name: Do not sync any user whose primary

address matches the rule. The interface displays
this choice as ADDRESS.
• Group Name: Do not sync any group which has a

name that matches the rule. The interface displays
this choice as NESTED_GROUP_NAME.
• Member Name: Do not sync any user whose

primary address matches this rule from any
groups. The interface displays this choice as
MEMBER_NAME.
80 Release 1.6.21
• Exact Match: The address or organization name

(minus domain name) must match the rule exactly.

substring.

Exclusion Rule The text of the match or regular expression to

compare.
Addresses that meet the requirements for an exclusion

filter will not be added as Google Apps groups.
LDAP User Profiles

Set up synchronization for Google Apps user profiles in the LDAP User Profiles
page. User Profiles contain extended information about users, such as phone
number and title.
The LDAP User Profiles section configures how Google Apps Directory Sync
generates user profile information from your LDAP directory server. You may need
to collect information from your LDAP directory server before you can enter details
in this section.
Configuration 81
LDAP User Profiles Attributes
LDAP user profiles.
82 Release 1.6.21
The fields are as follows.
LDAP Profile User Attribute Description
Primary email LDAP attribute that contains a user’s primary

mail address. This is usually the same as the
primary mail address listed in the previous
LDAP Users section.
Example: mail
Job title LDAP attribute that contains a user’s job title.
Company name LDAP attribute that contains a user’s company

name.
Assistant’s DN LDAP attribute that contains the LDAP

Distinguished Name (DN) of the user’s
assistant.
Manager’s DN LDAP attribute that contains the LDAP

Distinguished Name (DN) of the user’s direct
manager.
Department LDAP attribute that contains a user’s

department.
Office location LDAP attribute that contains a user’s office

location.
Employee ids LDAP attribute that contains a user’s

Employee ID number.
Websites LDAP attribute that contains a user’s home

page or other website.
Work phone numbers LDAP attribute that contains a user’s work

phone number.
Home phone numbers LDAP attribute that contains a user’s home

phone number.
Fax phone numbers LDAP attribute that contains a user’s fax

number.
Mobile phone numbers LDAP attribute that contains a user’s personal

mobile phone number.
Work mobile phone numbers LDAP attribute that contains a user’s work
Assistant’s Number LDAP attribute that contains a work phone

number for a user’s assistant.
Street Address LDAP attribute that contains the street address

portion of a user’s primary work address.
P.O. Box LDAP attribute that contains the P.O. Box of a

user’s primary work address.
Configuration 83
LDAP Profile User Attribute Description
City LDAP attribute that contains the city of a user’s

primary work address.
State/Province LDAP attribute that contains the state or

province of a user’s primary work address.
ZIP/Postal Code LDAP attribute that contains the ZIP code or

Postal Code of a user’s primary work address.
Country/Region LDAP attribute that contains the country or

region of a user’s primary work address.
LDAP User Profiles Sync

This shows a list of rules used when determining which user profiles to import.
Note: If you store your user profile information in the same place in your directory
server as your users’ mail addresses, you may use the same sync rules for LDAP
User Profiles as you did for LDAP User Sync. To use the same settings, add a
new search rule and copy the same scope and rule text.
By default, user profile information will be synchronized for all users that match
these search rules will be added to the Google Apps user list. You can change this
behavior with exclusion filters.
84 Release 1.6.21
empty list. To add a search rule, click the Add Search Rule button at the bottom
of the screen.
search rules.
Search rules are processed in the order listed.
Add User Profile Search Rule

To add a new search rule, click Add User Profile Search Rule.
Configuration 85
This dialog box has the following fields
LDAP User Profile Search Rule

Field Description
Scope This determines where in the LDAP directory

this rule applies.
• Subtree: All objects matched by the

search, and anything under those objects,
recursively. Subtree gives the broadest
search, but for very large organizations
this can be load-intensive and cause
system problems.
• One-level: All objects matched by the

search, and anything one level underneath
them. Does not look further than one level.
One-level provides a limited search that
will avoid causing extreme load for very
large organizations.
• Object: Only objects directly matched by

the search. No recursion of any
kind.Object is rarely used except with very
complex LDAP searches. It allows a
search only on the specified object.
Example: Subtree
Rule The search rule for user profile sync to match.

This rule is a standard LDAP query, and allows
sophisticated logic and complex rules for
searching. For more information about LDAP
search filters, see “LDAP Queries” on page 23.
Example 1: To match all objects (this may

cause load problems):
objectclass=*
• For OpenLDAP:


86 Release 1.6.21
Field Description
Base DN The Base DN (Distinguished Name) to use for

this search rule. This will override the default
Base DN you specified in LDAP Connection.
This field is optional. In most cases, you can

leave this field blank and use the Base DN
specified in the LDAP Connection page. If you
want this rule to use a different Base DN than
the default, specify an alternate base DN.
Example:
ou=powerusers,ou=test,ou=sales,ou=melbou
rne,dc=ad,dc=example,dc=com
LDAP User Profiles Exclusion Rules

If you have any existing user profile information in Google Apps that you do not
want to synchronize, specify it here.
Configuration 87
exclusion filters.
Example LDAP User Profile Exclusion Rules

Sample Substring Match: Printers
In this example, printers are listed as LDAP users and would match the LDAP
query given. However, the printers all have the word “printer” in the name. The
rule looks for that substring.
• Rule: printer
Sample Exact Match: Opt-Out Users
Two users have opted out of Google Apps and should not be synchronized.
First rule:
• Rule: atif@example.com
Second rule:
• Rule: svetlana@example.com
Sample Regular Expression Match: Test Users
88 Release 1.6.21

exactly.
Example: maria@example.com would exclude only

the user maria@example.com.

substring.



Configuration 89


Examples:
• Exact Match: maria@example.com
• Substring Match: listinternal
LDAP Shared Contacts

Set up synchronization for Google Apps user profiles in the LDAP User Profiles
page. Shared Contacts contain information about contacts, such as name, email
address, phone number and title.
Shared Contacts in Google Apps are contacts that any user can see and use.
Shared Contacts correspond to a Global Address List (GAL) in Microsoft Active
Directory and other directory servers.
90 Release 1.6.21
You can see Shared Contacts in Google Apps by going to your Inbox and clicking
the Contacts link.
The LDAP Shared Contacts section configures how Google Apps Directory Sync
generates shared contacts information from your LDAP directory server. You may
need to collect information from your LDAP directory server before you can enter
details in this section.
How to use Shared Contacts

Shared Contacts information is similar to a Global Address List in a directory
server. Your Shared Contacts in Google Apps is a domain-wide repository of
contacts, available to all users.
Shared Contacts are visible to a Google Apps user in three places:
• Autocomplete. While a user types a recipient address in Google Apps Mail,

autocomplete will suggest possible addresses that match what the user has
typed. This list of possible recipients comes from three places: addresses that
the user has mailed before, users (but not groups) in the domain, and Shared
Contacts. Adding Shared Contacts means that users will see the address in
the suggestion list even if they have not mailed that contact before.
• Chooser. When a user click on the To field while composing a Google Apps
Mail message, the Chooser will present a list of possible recipients, similar to
an address list. This list of possible recipients comes from three places:
addresses that the user has mailed before, users (but not groups) in the
domain, and Shared Contacts.
• Contacts information. Shared Contacts are not visible when a user clicks
the Contacts tab. However, if a user sends mail to a contact, or adds a
contact, Google Apps will also add information from Shared Contacts.
Configuration 91
Below are some of the most common reasons to import Shared Contacts:
• Add groups and outside addresses to autocomplete. User addresses in your

domain will show up in autocomplete. However, groups and outside
addresses are not visible in autocomplete. Create LDAP sync rules to import
any groups or outside addresses you want your users to see when using
autocomplete.
• Give pilot users access to all users for autocomplete. If you are adding a small
number of users for a pilot program, consider adding other users as Shared
Contacts, so that pilot users will see the address of other users in
autocomplete.
• Provide supplemental directory information to users. If your users want to see

rich contact information from your directory server for their contacts (such as
postal addresses, phone numbers, companies, and titles), synchronize this
information using Shared Contacts. Users will see this additional information
in the Contacts page after they have added the contact manually, or sent mail
to that contact’s address.
Important: Shared Contacts do not show immediately. After you synchronize

Shared Contacts, it may take up to 24 hours for the changes to appear in Google
Apps.
LDAP Shared Contacts Attributes

LDAP user profiles.
92 Release 1.6.21
The fields are as follows.
LDAP Shared Contact Attribute Description
Sync key An LDAP attribute that contains a unique

identifier for the contact. Choose an attribute
present for all your contacts that is not likely to
change, and which is unique for each contact.
This field becomes the ID of the contact.
Examples: dn or contactReferenceNumber
Full name LDAP attribute that contains a contact’s full

name.
Job title LDAP attribute that contains a contact’s job

title.
Company name LDAP attribute that contains a contact’s

company name.
Assistant’s DN LDAP attribute that contains the LDAP

Distinguished Name (DN) of the contact’s
assistant.
Manager’s DN LDAP attribute that contains the LDAP

Distinguished Name (DN) of the contact’s
direct manager.
Department LDAP attribute that contains a contact’s

department.
Office location LDAP attribute that contains a contact’s office

location.
Work email address LDAP attribute that contains a contact’s email

address
Employee ids LDAP attribute that contains a contact’s

employee ID number.
Websites LDAP attribute that contains a contact’s home

page or other website.
Work phone numbers LDAP attribute that contains a contact’s work

phone number.
Home phone numbers LDAP attribute that contains a contact’s home

phone number.
Fax phone numbers LDAP attribute that contains a contact’s fax

number.
Mobile phone numbers LDAP attribute that contains a contact’s

personal mobile phone number.
Work mobile phone numbers LDAP attribute that contains a contact’s work
Configuration 93
LDAP Shared Contact Attribute Description
Assistant’s Number LDAP attribute that contains a work phone

number for a contact’s assistant.
Street Address LDAP attribute that contains the street address

portion of a contact’s primary work address.
P.O. Box LDAP attribute that contains the P.O. Box of a

contact’s primary work address.
City LDAP attribute that contains the city of a

contact’s primary work address.
State/Province LDAP attribute that contains the state or

province of a contact’s primary work address.
ZIP/Postal Code LDAP attribute that contains the ZIP code or

Postal Code of a contact’s primary work
address.
Country/Region LDAP attribute that contains the country or

region of a contact’s primary work address.
LDAP Shared Contacts Sync

This shows a list of rules used when determining which shared contacts to import.
By default, shared contacts will be synchronized for all contacts that match these
search rules will be added to the Google Apps user list, and removed for shared
contacts that do not match these rules. You can change this behavior with
exclusion filters.
94 Release 1.6.21
empty list. To add a search rule, click the Add Shared Contact Search Rule
button at the bottom of the screen.
search rules.
Search rules are processed in the order listed.
Add Shared Contact Search Rule

To add a new search rule, click Add Shared Contact Search Rule.
Configuration 95
Field Description
Scope This determines where in the LDAP directory

this rule applies.
• Subtree: All objects matched by the

search, and anything under those objects,
recursively. Subtree gives the broadest
search, but for very large organizations
this can be load-intensive and cause
system problems.
• One-level: All objects matched by the

search, and anything one level underneath
them. Does not look further than one level.
One-level provides a limited search that
will avoid causing extreme load for very
large organizations.
• Object: Only objects directly matched by

the search. No recursion of any
kind.Object is rarely used except with very
complex LDAP searches. It allows a
search only on the specified object.
Example: Subtree
Rule The search rule for shared contact sync to

match. This rule is a standard LDAP query,
and allows sophisticated logic and complex
rules for searching. For more information
about LDAP search filters, see “LDAP
Queries” on page 23.
Example 1: To match all contacts:
(objectclass=contact)
• For OpenLDAP:


96 Release 1.6.21
Field Description
Base DN The Base DN (Distinguished Name) to use for

this search rule. This will override the default
Base DN you specified in LDAP Connection.
This field is optional. In most cases, you can

leave this field blank and use the Base DN
specified in the LDAP Connection page. If you
want this rule to use a different Base DN than
the default, specify an alternate base DN.
Example:
ou=powerusers,ou=test,ou=sales,ou=melbou
rne,dc=ad,dc=example,dc=com
LDAP Shared Contacts Exclusion Filter

If you have any contacts on your LDAP directory server that match your search
rules but should not be added to Google Apps, add an LDAP shared contacts
exclusion rule.
settings.
Note: To exclude individual contacts, add a separate rule for each contact.
Configuration 97
exclusion filters.
Example LDAP Shared Contact Exclusion Rules

Sample Exact Match: Private Contacts
Two contacts have opted out of Google Apps and should not be synchronized.
First rule:
• Rule: atif@example.com
Second rule:
• Rule: svetlana@example.com
Sample Regular Expression Match: Test Contacts
98 Release 1.6.21

exactly.
Example: maria@example.com would exclude only

the user maria@example.com.

substring.



Configuration 99


Examples:
• Exact Match: maria@example.com
• Substring Match: listinternal
Notifications
You can set Configuration Manager so that every time synchronization occurs,
Google Apps Directory Sync will send out a notification to one or more users.
Consider adding a notification to send mail to your own address, and possibly the
addresses of any concerned parties in your company.
Note: Notifications are sent by plain SMTP, not TLS.
100 Release 1.6.21

Notifications Setting Description
Send notifications Enter the “From:” address for the notification mail.
from address Recipients will see this address as the notification
sender. For instance, you might use your own email
address.
Example: dirsync@example.com
Send notifications Notifications will be sent to all addresses on this list.

to the following Enter any valid email address on any domain. Enter
addresses each recipient email address individually, then click the
Add button.
Depending on your mail server settings, the directory

sync utility may be unable to send mail to external
email addresses. Run a test notification to confirm that
mail is sent properly.
Example: dirsync-admins@example.com
SMTP Relay Host The SMTP mail server to use for notifications. The
directory sync utility uses this mail server as a relay
host.
Note: You cannot use Google Apps as your SMTP

Relay Host for Notifications.
Example: 127.0.0.1 to run the mail server on the

same machine.
Example: mail.example.com
Username If the SMTP server you specify requires SMTP

authentication, enter the user name to use here.
(if needed)
Example: admin5
Password If the SMTP server you specify requires SMTP

authentication, enter the Password to use here.
(if needed)
Example: swordfish
Passwords are stored in the configuration file in an

encrypted format.
Configuration 101
Notifications Setting Description
Do not include in You can limit the information sent in notifications by

notifications checking any of the three checkboxes. All checkboxes
are optional.
(Optional)
• Extra details: Google Apps Directory Sync
notifications will not include extra details and
potentially extraneous information.
• Warnings: Google Apps Directory Sync

notifications will not include warning messages.
• Errors: Google Apps Directory Sync notifications

will not include error messages.
Test Notification
Click this button to test notifications. Configuration Manager will connect to the
SMTP server you specified and send a test notification to the addresses you list.
Delete Limits
As a safeguard, you can limit how many users, groups, and shared contacts
Google Apps Directory Sync can delete during synchronization. This is
recommended as a way to prevent accidental mass deletion.
102 Release 1.6.21

The directory sync utility checks to be sure that synchronization will not delete too
many users. If the synchronization would delete more users than the delete limits
allow, the entire synchronization fails and no users, groups, or shared contacts
are added, moved or deleted. This will be noted in the notifications email.
Note: Delete limits apply during synchronization, but not during simulation.
Simulation results will not include delete limits.
To set a delete limit, specify one of the following:
Delete Limits Setting Description
Delete no more than Specify a maximum percentage of users that can be

% of users, groups deleted. This is a percentage of the users registered on
and shared contact Google Apps, not a percentage of users on your LDAP
server.
(Optional)
If no delete limit is specified, the default is 5%.
Example: 5%
You can suppress delete limits from the command line.
Delete no more than Specify a maximum number of users, groups, and

users, groups and shared contacts that can be deleted.
shared contacts
Example: 25
(Optional)
Configuration 103
Log Files
You can specify the file name and level of detail of logging for Google Apps
Directory Sync.
Logging Setting Description
File name Enter the directory and file name to use for the log file
or click Browse to browse your file system.
Example: sync.log
Log Level The level of detail of the log. Options are FATAL,
ERROR, WARN, INFO, DEBUG, and TRACE.
The level of detail is cumulative: each level includes all

the details of previous levels. ERROR includes all
ERROR and FATAL messages, and so on.
• FATAL only logs fatal operations.
• ERROR only logs errors and fatal operations.
• WARN only logs warnings, errors and fatal

operations.
• INFO logs summary information.
• DEBUG logs more extensive details.
• TRACE logs all possible details.
104 Release 1.6.21

Logging Setting Description
Maximum Log Size The maximum size of the log file, in gigabytes. When
this file reaches half capacity, it is saved as a backup
file (which overwrites any existing backup file) and a
new file is created. At any time, the total size of these
two files (the log file and the backup log file) will not
exceed the total maximum size.
Example: 4
Simulate Sync
After you enter configuration information, use this section to verify and test your
Google Apps Directory Sync settings. Configuration Manager does not check for
valid LDAP syntax. To find invalid LDAP queries, use Simulate Sync. Invalid LDAP
queries will cause errors.
For information on common errors that might occur and how to troubleshoot them,
see “Common Issues” on page 113.
Simulate Sync
When you first go to this page, you will see Validation Results. This page will show
a checklist of all the Configuration Manager sections. If you are missing required
information, you will see error messages showing what needs to be added.
Important: This checklist confirms only the minimum needed for synchronization.
You may need to configure additional filters or rules to be sure the results are what
you expect.
Configuration 105
Once you’ve completed all required fields, you will be able to use the Simulate
Sync button to simulate a synchronization.
Once you’re ready, click Simulate Sync. You will see the Simulate Sync page.
During simulation, Configuration Manager will:
• Connect to Google Apps and generate a list of users, groups, and shared
contacts.
• Connect to your LDAP directory server and generate a list of users, groups,
and shared contacts.
• Generate a list of differences.
• Log all events.
• If connection was successful, show a Proposed Change Report which shows

what changes would have been made to your Google Apps user list.
Note: Simulate Sync will never update or change your LDAP server or your users
in Google Apps. The simulation is strictly for configuration and testing. To run an
actual synchronization, use the command line. See “Synchronization” on
page 109 for more.
106 Release 1.6.21

Review the Simulation Results to confirm that the simulation occurred correctly
without any unexpected results.
If any errors occur, check the error text. Most error text is human readable, but
some error text may contain Java stack trace errors. If you need help
troubleshooting these errors, see “Troubleshooting” on page 113.
If the synchronization was successful, check the Proposed Change Report and
review it for unexpected results.
Note: The Proposed Change Report doesn’t check your delete limits.
If you see any errors or unexpected results, you can go back and change your
configuration to try again. To change your configuration, click on any of the
headings on the left navigation bar.
You can switch between the Validation Results and Simulation Results pages
using the buttons at the bottom of the page. You can also run another simulation
from either page by clicking the Simulate Sync button at the bottom.
Once you are finished, save your configuration file and run synchronization. See
“Synchronization” on page 109.
Configuration 107
108 Release 1.6.21
Chapter 6
Synchronization Chapter 6
About Synchronization
Run the synchronization command to push your LDAP directory server user
information to Google Apps.
The directory sync utility uses the command sync-cmd to run synchronization.
This simple command line interface gives you the flexibility to incorporate
synchronization into any scheduling or batch script you wish to use.
Before you can synchronize Google Apps with your LDAP directory server, you
must create rules that detail how to connect to both servers, and what filters and
rules to use. These rules are stored in an XML file. To create this XML file, run
Configuration Manager. For more information about Configuration Manager, see
“Configuration” on page 31.
Most administrators run their first synchronization manually to test the process,
import an initial set of users, and confirm the changes. After initial synchronization
with the command line, you can set up automatic scheduling for future
synchronization.
Command Line Synchronization

Before you can run synchronization, create a Configuration XML file using the
Configuration Manager user interface. For more information, see For more
information about Configuration Manager, see “Configuration” on page 31.
The command line to use for all platforms is
sync-cmd
Run without any arguments, this command gives an error and directs you to run
sync-cmd -h for help.
To synchronize, use the following command line to read a configuration file,

connect to both servers, generate a list of changes, and apply those changes:
sync-cmd -a -c [filename]
Synchronization 109
Replace [filename] with the name of the XML file you created in the
Synchronization options
The table below describes the possible arguments to the sync-cmd command. You
can also see this information by running the following:
sync-cmd -h
in the directory where the directory sync utility is installed.
Option Values
-r,--report-out Write reports to the specified output file, in

addition to writing them to the log.
-a,--apply Apply detected changes.
Note: If you do not use this tag, the

synchronization is a test only and will not affect
your Google Apps account. For best results,
run a test without this flag before running a full
synchronization with this flag.
-V Display detailed application version
information. Does not synchronize.
-c,--config [filename] Specify the configuration to load.
Synchronization will not occur without a valid
XML file for this argument.
-d, --deletelimits Ignores any configured delete limits.
-f, --flush For support troubleshooting only (slows sync)
WARNING: This option is intended only to

resolve specific troubleshooting issues.
Improper use can cause performance
degradation. Do not use this option unless
directed by support.
-g, --groups Do not analyze groups. Use this option if you
want to synchronize users, but not groups.
-h,--help View this information and exit.
-l,--loglevel [level] Override the default and/or configured log
level with the specified value. Valid values (in
increasing order of verbosity) are FATAL,
ERROR, WARN, INFO, DEBUG, and TRACE.
In most cases, the recommended log level is

INFO.
110 Release 1.6.21

Option Values
-s, --sharedcontacts Do not analyze shared contacts.
Note: Do not use this option. It is intended for

other versions of the directory sync utility, and
will have no effect.
-u, --users Do not analyze users. Use this option if you
want to synchronize groups, but not users.
-v Display short application version information.
Scheduling Synchronization
Once you have successfully run a manual synchronization, you can set up
automatic synchronization. Use existing third-party scheduling software to
automate synchronization.
In most cases, scheduling twice a week is recommended. The exact timing will
vary based on the number of users you have and how often you need to update
them. A large company with many users changing frequently may need to run the
directory sync utility daily, while a small company with few changes may not need
to run the utility more than once a week.
The exact method to schedule this task depends on the operating system in which
the directory sync utility is installed. In Microsoft Windows, use Scheduled Tasks.
In Linux or Solaris, use cron. Steps for how to do this are listed below. You can
also use any other scheduling software that can launch commands from the
command line interface.
Microsoft Windows: Scheduled Tasks

In Microsoft Windows, schedule synchronization using Scheduled Tasks.
Note: These steps apply to most common Microsoft Windows configurations.

Scheduled Tasks is a third-party product and is not supported directly by the
Google (or Postini) team. In the event of a Scheduled Tasks issue, contact your
Windows administrator.
To schedule a task
1. In Control Panel, open Scheduled Tasks.
2. Double-click Add Scheduled Task.
Synchronization 111
3. Complete the Scheduled Task wizard using the following information. (Steps
may vary depending on your version of Microsoft Windows.)
• Choose the program sync-cmd.exe, located where the directory sync

utility is installed.
• The frequency of the task depends on your synchronization needs. For
most environments, twice per week is appropriate.
• Use Advanced Properties to specify an exact command line. The
appropriate command line is:
[path]\sync-cmd -a -c [filename]
Replace [path] with the path where the directory sync utility was
installed. Replace [filename] with the name of the XML file you created
in the Configuration Manager.
4. Test the scheduled task by running manually once. In the Scheduled Tasks
window, right-click the task you created and select Run from the right-click
menu. Check the log file for errors.
Linux and Solaris: cron

In Linux and Solaris environments, schedule synchronization using crontab.
Note: These steps apply to most common Linux and Solaris configurations. Linux
and Solaris are third-party products and are not supported directly by the Google
(or Postini) team. In the event of an issue with cron, contact your administrator.
To add a cron job
1. Run crontab -e to update the crontab file.
2. Add a line in the crontab file for the following command:

sync-cmd -a -c [filename]
The syntax of this line will depend on your operating system and version of
cron. For instance, to schedule the task to run at 3:30 AM twice per week, on
Monday and Thursday, add the following entry:
30 3 * * 1,4 [path]/sync-cmd -a -c [filename]
Replace [path] with the path where the directory sync utility was
installed.Replace [filename] with the name of the XML file you created in the
3. Save the crontab file and exit your text editor.
112 Release 1.6.21

Chapter 7
Troubleshooting Chapter 7
About Troubleshooting
This chapter covers information about how to troubleshoot problems that may
occur with Google Apps Directory Sync.
Troubleshooting information includes information about common issues, system

tests and researching issues.
For information about LDAP queries, see “LDAP Queries” on page 23.
Common Issues
The following describes common issues and questions related to Google Apps
Directory Sync.
Configuration Manager
When creating an exception rule, the dialog box does not have an OK button.
You may be using a font that is too large for the screen. The dialog box does not
work with Extra Large Fonts or Large Fonts. Change your font size, or edit your
XML file directly.
What port numbers should be used in Google Apps Directory Sync when
connecting to Global Catalog server?
By default, Google Apps Directory Sync connects to an LDAP server with the
standard LDAP port 389 to query users from a single domain/LDAP server.
If you need to query users over multiple domains/LDAP servers that have trust
relationship, configure Google Apps Directory Sync to connect to a Global Catalog
server with the standard Global Catalog server port 3268.
Troubleshooting 113
User Sync Errors
Error Message: You are not authorized to access this API
Confirm that you are using Premier, Partner or Educational Edition of Google
Apps. Google Apps Directory Sync is not compatible with Standard Edition or
Team Edition.
Enable APIs on your Google Apps domain, as described in “Enable APIs” on

page 27.
How does Google Apps Directory Sync handle suspended users?
Google Apps Directory Sync is unable to detect suspended users, and will not try
to delete them. If Google Apps Directory Sync tries to add a suspended user, you
will see an error message: EntityAlreadyExists (1300).
Error Message: DomainUserLimitExceeded (error code 1200)
You attempted to add more users than you have licensed seats. Contact your
sales representative to purchase more user licenses, or change your LDAP
queries to synchronize fewer users.
Error Message: UserDeletedRecently (error code 1100)
The directory sync utility tried to add a user who was deleted. When you delete a
user, you can’t add that user until 5 days pass. Wait 5 days, or contact support for
help.
Where can I find a list of other error messages and their meanings?
Other error messages are listed in the Error Codes section of the Google Apps
Provisioning API Developer’s Guide.
Synchronization Rules
A group rule or exclusion rule doesn’t seem to be doing anything.
Check the scope of the rule. You may need to set the scope to SUBTREE.
A group rule generates errors.
Check the Group Search Attribute in LDAP Configuration. This is the field that
contains the email address of a group. In most cases, this will be mail.
How can I exclude a specific LDAP organization?
You cannot create an LDAP rule to exclude users in a specific LDAP organization.
Instead, limit the authority of the LDAP Administrator you use, removing access to
any OUs you do not want to synchronize.
114 Release 1.6.21

Connections and Security
The proxy environment requires a password challenge for external web access.
The directory sync utility can use a proxy server but cannot respond to password
challenges. To run synchronization, you will need to change your network setup to
allow the directory sync utility to connect without a password challenge, or without
a proxy server.
I cannot simulate a synchronization because the notifications server not

specified.
To run a simulated synchronization, you will need a server capable of sending

mail. If you are running directory sync on a mail server machine, you can use the
IP address 127.0.0.1 for your mail server. Otherwise, contact your mail
administrator for the correct mail information.
How securely are passwords stored?
Google Apps Directory Sync stores passwords using a two-way encryption

scheme. This protects your sensitive information from casual snooping or reverse
engineering.
To convert a configuration file to the new format with encrypted passwords:
1. Open the file in Configuration Manager.
2. Save the file again.
You can also upgrade the file with the following command-line executable:
upgrade-config -c [filename]
where [filename] is the name of the XML configuration file to upgrade.
Note: Configuration files for version 1.3.11 or later are not compatible with earlier
versions.
LDAP Directory Server
The Base DN information doesn’t seem to be correct.
Check to be sure your Base DN doesn’t include any spaces.
How do I find out information about my LDAP server fields?
You will need to download an LDAP browser. An LDAP browser allows you to
browse through an LDAP directory server and identify all fields and values. Many
directory servers do not include a complete LDAP browser. For information on
LDAP browsers, see “Useful LDAP Tools” on page 16.
Troubleshooting 115
How can I get password sync to work?
Google Apps Directory Sync supports two encoding formations: SHA-1 and MD-5.
Specify the name of the attribute that contains the password. Google Apps does
not return the encoded password back, so every time you run a synchronization,
the report will show that all users had passwords updated.
To synchronize passwords from LDAP, you will need an LDAP attribute that stores
passwords in plain text, MD5 or SHA1 format. Before you begin configuration, find
out what encryption format your LDAP directory server uses for passwords. By
default, Active Directory and Lotus Domino directory servers do not include these
passwords.
Note: Other password encryption hashes are not currently supported.
If you wish to synchronize passwords, you can synchronize for all users (if you
want to manage passwords in LDAP) or only for new users (if you want to manage
passwords in Google Apps).
If your LDAP directory server does not support passwords in the format that
Google Apps Directory Sync uses, consider the following options:
• Specify a default password for new users and force new users to change their
password on first login.
• Use a plaintext attribute, and force new users change their password on first
login.
• Use a third-party utility to convert unsupported passwords to a supported

format.
• Implement Single Sign-On for your domain.
• Set passwords in Google Apps Directory Sync manually.
An LDAP query that includes a wildcard isn’t working with Lotus Domino LDAP
Lotus Domino has a setting for “Minimum characters for wildcard search” that
controls how wildcard LDAP searches work. Update your search to include more
characters, or change this setting to a lower number.
System Tests
If you encounter problems, use the tests in Configuration Manager to find the
problem:
1. In Configuration Manager, open the XML file you are using for configuration.
2. Under LDAP Connections, click Test Connection to confirm you can connect
to your LDAP server.
3. Under Notifications, click Test Notification to confirm you can send a test
notification.
4. Under Simulate Sync, confirm you have filled out all required fields.
116 Release 1.6.21

5. Under Simulate Sync, click Simulate Sync to confirm that synchronization is
running properly.
If you encounter any problems, note which tests failed and confirm that the
configuration information is correct for those sections of Configuration Manager.
Escalating Problems
If you are unable to run directory sync, and cannot resolve the problem using
system tests, collect the following information for troubleshooting:
• The most current sync log file, located in the folder where the directory sync
utility is installed.
• The version number of the directory sync utility you are running. You can find
this in the Configuration Manager UI by going to Help->About, or you can run
the command sync-cmd -V.
• The current config file you are using. This is an XML file (default name
sync.xml) located in the same folder where the directory sync utility is
installed.
• The brand and version of the LDAP directory server you're using.
• The operating system on the machine where the directory sync utility is
running.
Once you have collected this information, check the help center or contact support
for help.
Documentation and Support

For documentation, support information and help center articles, see the Directory
Sync page in Google Apps Admin Help:
http://google.com/apps/directorysync
Expediting Support with Your Support PIN

To contact support directly for assistance, and receive expedited support as a
Premium Edition customer, find your Customer PIN and Support PIN. Information
on how to collect this information is available in the help center here:
http://www.google.com/support/a/bin/answer.py?answer=60233
Troubleshooting 117
118 Release 1.6.21

Gads Admin

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Gads Admin

Caricato da

Copyright:

Formati disponibili

Google Apps Directory Sync

Part number: GADS_1.6.21_20

November 23, 2010

© Copyright 2010 Google, Inc. All rights reserved.

Copyright (c) 2002-2008 JGoodies Karsten Lentzsch. All rights reserved.

This software uses Apache Derby.

Copyright 2004-2007 The Apache Software Foundation

This product includes software developed by

(C) Copyright IBM Corp. 2003.

About This Guide 7

Chapter 3: Preparation and Planning 15

Chapter 6: Synchronization 109

Chapter 7: Troubleshooting 113

What This Guide Contains

• Google Apps Directory Sync features.

• Configuration for the directory sync utility.

• Synchronizing users, groups, and shared contacts.

• Troubleshooting the directory sync utility.

Google Apps Directory Sync Another version of Google Apps Directory

How to Send Comments About This Guide

About Google Apps Directory Sync

Customer acknowledges and agrees that Customer is solely responsible for

Features and Benefits

• Runs on any Windows (XP or Vista), Linux or Solaris server.

• All needed components included in installation.

• Allows sophisticated rules to handle groups, aliases, and exceptions.

• Advanced LDAP query capabilities to handle irregular LDAP environments.

• Extensive tests and simulations to ensure correct synchronization.

• A Google Apps domain running Premier Edition, Partner Edition or Education

• An administrator account on your Google Apps domain.

• A server on which to install Google Apps Directory Sync, running Microsoft

• An LDAP server with user information which is accessible to the directory

• Read and execute administrative access over the appropriate OU structure of

• Network access to the Google Apps through HTTPS, directly or through a

Comparison with Google Apps Directory Sync for Email Security

• Configuration Manager - Use this graphical UI to configure how the directory

• XML Configuration File - Save configuration information from Configuration

• Synchronization Command Line - Use the command-line utility sync-cmd to

Preparation and Planning Chapter 3

For information on system requirements, see “System Requirements” on page 11.

1. Identify your LDAP resources, including LDAP servers and expert

4. Make any necessary changes to clean up extraneous or problematic data in

5. Install the directory sync utility. For information about installation

Preparation and Planning 15

7. In Configuration Manager, simulate a synchronization and review the results.

8. If needed, revise your configuration in Configuration Manager based on the

12. Using your server’s scheduling tools, set up automatic scheduled

Useful LDAP Tools

Softerra LDAP Administrator

Planning Your Synchronization Strategy

When planning your synchronization strategy, consider the following factors.

Terminology: LDAP Directory Server and Google Apps

Corresponding Concept in Google

Org Units (OUs) Organizations

Mailing Lists Groups (all groups are added as

Preparation and Planning 17

Note: Other password encryption hashes are not currently supported.

• Do you want to synchronize User Profiles? If you want detailed information

• Do you want to synchronize Shared Contacts? If you want to import

Preparation and Planning 19

• Do you want to replace domain names? By default, all synchronized users

• Do you want to delete suspended users, or leave them alone? By default,

Checklist: Before You Begin