1. No category

Google Apps Directory Sync
Administration Guide
Release 4.0.2
Google, Inc.
1600 Amphitheatre Parkway
Mountain View, CA 94043
www.google.com
Part number: GADS_4.0.2
November 5, 2014
© Copyright 2014 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 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
OF SUCH DAMAGE.
This software uses Apache Derby.
Apache Derby
Copyright 2004-2007 The Apache Software Foundation
2
Release 4.0.2
This product includes software developed by
The Apache Software Foundation (http://www.apache.org/).
Portions of Derby were originally developed by International Business Machines Corporation and are licensed to the Apache
Software Foundation under the “Software Grant and Corporate Contribution License Agreement”, informally known as the
“Derby CLA”.
The following copyright notice(s) were affixed to portions of the code with which this file is now or was at one time distributed
and are placed here unaltered.
(C) Copyright 1997,2004 International Business Machines Corporation. All rights reserved.
(C) Copyright IBM Corp. 2003.
The portion of the functionTests under 'nist' was originally developed by the National Institute of Standards and Technology
(NIST), an agency of the United States Department of Commerce, and adapted by International Business Machines
Corporation in accordance with the NIST Software Acknowledgment and Redistribution document at
http://www.itl.nist.gov/div897/ctg/sql_form.htm
3
4
Release 4.0.2
Contents
About This Guide 9
What This Guide Contains 9
Related Documentation 9
How to Send Comments About This Guide
10
Chapter 2: Overview of Google Apps Directory Sync
What Is Google Apps Directory Sync? 11
How Directory Sync Works 11
What Is Synchronized 13
Directory Sync and Deployment 15
System Requirements 19
11
Chapter 3: Getting Started 23
Overview 23
Step One: Install LDAP Browser 24
Step Two: Collect LDAP Inventory 25
Step Three: Decide What to Synchronize 28
Step Four: Prepare Google Apps for Synchronization 38
Step Five: Prepare Your Servers for Synchronization 39
Further Steps 39
Chapter 4: LDAP Queries 41
About LDAP Queries 41
Syntax 41
Common LDAP Queries 42
Chapter 5: Installation 45
About Installation 45
Install Google Apps Directory Sync 45
Upgrade Google Apps Directory Sync 46
Uninstall Google Apps Directory Sync 47
Chapter 6: Configuration
About Configuration 49
Configuration Files 50
49
Contents
5
Configuration Best Practices 51
General Settings 52
Google Apps Configuration 53
Google Apps Connection Settings 54
Google Apps Proxy Settings 57
Google Apps Exclusion Rules 58
LDAP Configuration 64
LDAP Connection Settings 65
LDAP Org Units 66
Org Unit Mappings 67
Org Unit Search Rules 70
Org Unit Exclusion Rules 72
User Accounts 76
User Attributes 77
Additional User Attributes 79
User Search Rules 84
User Exclusion Rules 87
Groups 91
Group Search Rules 92
Group Exclusion Rules 98
User Profiles 101
User Profile Attributes 102
User Profile Search Rules 104
User Profile Exclusion Rules 107
Shared Contacts 109
Shared Contact Attributes 111
Shared Contact Search Rules 113
Shared Contact Exclusion Rules 116
LDAP Calendar Resources 119
Calendar Resource Attributes 120
Calendar Resource Search Rules 121
Calendar Resource Exclusion Rules 123
Notifications 127
Logging Settings 130
Sync 131
Chapter 7: Synchronization 135
About Synchronization 135
Synchronizing from the Configuration Manager
Command Line Synchronization 135
Scheduling Synchronization 137
Monitoring 139
Chapter 8: Release 4.0.1 Troubleshooting
About Troubleshooting 141
Troubleshooting With Log Files 141
Common Issues 141
System Tests 144
6
Release 4.0.2
135
141
Escalating Problems
145
Contents
7
8
Release 4.0.2
About This Guide
What This Guide Contains
The Google Apps Directory Sync Administration Guide provides information
about:
•
Google Apps Directory Sync features
•
Basic steps for installing Directory Sync on your server
•
Configuration for Directory Sync
•
Synchronizing users, groups, and shared contacts
•
Troubleshooting Directory Sync
This guide is intended for administrators who are already familiar with Google
Apps and with LDAP directory servers.
Related Documentation
For additional information about Google Apps and about related products, refer to
the following documents.
Document
Description
Directory Sync Admin Help
Page
Central page for Google Apps Directory Sync.
Includes a description of the product, as well
as available downloads. Get the latest
download here.
Google Apps Admin Help
Help Center for Google Apps. This includes
documentation and support for the entire
Google Apps suite, including Google Apps,
Mail, and Google Apps Directory Sync.
9
Document
Description
Google Apps Directory Sync
Release Notes
Release Notes for Google Apps Directory
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
for Email Security
Another version of Google Apps Directory
Sync. Google Apps Directory Sync for Email
Security synchronizes with Message Security
and Delivery (powered by Postini) instead of
Google Apps.
How to Send Comments About This Guide
Google values your feedback. Please send comments about this guide to:
[email protected]
10
Release 4.0.2
Chapter 2
Overview of Google Apps Directory Sync
Chapter 2
What Is Google Apps Directory Sync?
Google Apps Directory Sync (also called Directory Sync or GADS) is a utility that
automatically adds, modifies, and deletes your users, OUs, groups, shared
contacts, and calendar resources in Google Apps to match your LDAP directory
server. When you synchronize, Google Apps changes to match your LDAP
directory.
GADS runs on your LDAP server and updates Google Apps to match your LDAP
directory. Directory Sync never modifies your LDAP directory information.
Important Notice
Before you enable GADS for your organization, please keep a few things in mind:
If Google Profiles is enabled for your organization, the data synced from your
institution’s directory will be auto-populated into the Google Profile, which your
end user may then choose to publish publicly on the web. Your use of Google
Apps Directory Sync may in some cases override the user’s edits to their own
profile fields -- please communicate this to your end users if you have enabled
Google Profiles for your organization or if you do so in the future.
Customer acknowledges and agrees that Customer is solely responsible for
complying with all applicable laws and regulations in using Google Apps Directory
Sync, including 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). To the extent that synced data includes
personally identifiable information from education records that are subject to
FERPA, Google will be considered a "School Official" (as that term is used in
FERPA and its implementing regulations) and will comply with FERPA.
How Directory Sync Works
This section discusses how GADS synchronizes your LDAP data into Google
Apps.
Overview of Google Apps Directory Sync
11
Technical Overview
GADS includes two connected tools: Configuration Manager and the sync-cmd
synchronization command line utility.
Configuration Manager is a GUI-based wizard that walks you through the steps of
configuring a synchronization. In Configuration Manager, you set up what data to
synchronize, specify LDAP query rules, list which attributes contain the
information you want to synchronize, specify server connections, and note any
exclusion rules. The Configuration Manager utility allows you to test your settings,
and stores information in an XML file that is then used by the sync-cmd utility.
sync-cmd is a command-line utility that syncs your LDAP data to Google Apps
using the XML file you create in Configuration Manager. Because it’s a commandline utility, it’s easy to schedule a recurring sync on your LDAP server.
Data Flow
The following steps describe how the data flow of GADS works.
1. GADS connects to your LDAP server and generates a list of users, groups,
and shared contacts on your directory. You can set up rules to specify how
this list is generated.
2. GADS connects to Google Apps and generates a list of users, groups, and
shared contacts in Google Apps. You can set up rules to specify how this list
is generated.
3. GADS compares these lists, and generates a list of changes.
4. GADS then updates Google Apps to match your LDAP server settings.
After GADS has finished synchronization, it sends a report of results to email
addresses that you specify.
12
Release 4.0.2
Security
GADS has the following security features:
•
It runs inside your network, on a machine you control.
•
It connects to your LDAP server inside your network through Standard LDAP
or secure LDAP + SSL. This connection occurs on any port you specify, but
defaults to standard LDAP ports.
•
It connects to Google Apps through the Internet via HTTPS on port 443. This
connection can also run through a proxy host in your network.
•
It connects to any mail server using standard SMTP or SMTP over TLS.
•
It does not store LDAP data on the Directory Sync machine. Directory Sync
stores connection details, configuration files, and event logs on the Directory
Sync server, but does not store any LDAP data. All LDAP data is
synchronized with Google Apps and stored as user information on Google
Apps secure servers.
•
It caches some Google Apps information locally on your Directory Sync
server.
What Is Synchronized
The chart below details what gets synchronized by GADS, the equivalent terms
between LDAP and Google Apps, and notes on what is and is not synchronized.
.
LDAP
Google Apps
Synchronizes
Notes
Org Units (OU)
Organizations
Organizations in Google Apps contain multiple
users. Organizations can be used to structure
users by department, location, or other
categories. You can synchronize org structure
automatically, or manually by each
organization.
Mailing Lists
Groups
Mailing lists in LDAP correspond to public
groups in Google Apps. Groups can also be
used to control access to sites and
documents.
Google Apps users can also create private,
user-managed Groups. These are not altered
or synchronized by Google Apps Directory
Sync.
User
Users
In Google Apps, users are organized by email
address, not LDAP Distinguished Name.
Overview of Google Apps Directory Sync
13
LDAP
Google Apps
Synchronizes
Notes
User Aliases
Nicknames
Other email addresses also used by a given
primary address. Each user can have multiple
nicknames in Google Apps, and these can
come from multiple LDAP alias attributes.
Passwords
Passwords
GADS can only synchronize passwords that
are stored in SHA-1 or MD-5 format with no
salted hashes. Alternatively, passwords can
be managed separately, or authentication can
be handled by SSO (Single Sign-On).
For more information on Passwords, see
“Passwords” on page 32.
Messages and calendar data are not migrated
with GADS. If you need to migrate your legacy
messages and calendar data, use a migration
tool, such as Google Apps Migration for Lotus
Notes, or Google Apps Migration for Microsoft
Exchange (which also migrates data for other
IMAP servers.)
Messages and
Calendar Data
Rooms
Calendar
Resources
Calendar resources, like rooms and
projectors, can be synchronized from your
LDAP directory into Google Apps.
Contacts
Shared
Contacts
An LDAP Contacts list corresponds to Google
Apps Shared Contacts. Shared Contacts are
visible as autocomplete options when users in
Gmail start typing an email address. Personal
contacts are not synchronized. Shared
Contacts appear in autocomplete about 24
hours after synchronization.
Personal Contacts
Personal
Contacts
GADS does not synchronize personal
contacts. If your users wish to import personal
contact information, they can use client-based
migration tools like Google Apps Migration for
Microsoft Outlook.
Extended User
Information
User Profiles
Extended LDAP information, like phone
numbers and addresses, can be synchronized
into Google Apps as rich User Profiles.
Shared Folders
None
Google Apps does not include an equivalent
to shared folders. Users typically share
information in Google Apps through Groups or
by sharing docs in Google Drive.
14
Release 4.0.2
Directory Sync and Deployment
GADS can be used during different stages of the Google Apps deployment cycle.
This section discusses the three-phase deployment model recommended for
implementing Google Apps, and how Directory Sync fits into this model.
For a tutorial on the three-phase deployment model, see the video Planning Your
Google Apps Deployment.
The Three-Phase Deployment Model
The methodology described in this section is based on field studies and real-world
deployment experience with Google Apps. The goal of this model is to accomplish
a Google Apps deployment quickly and give users the best possible customer
experience.
Deployment is typically divided into three phases, plus planning beforehand and
maintenance afterward.
The following steps are described in more detail below.
•
Plan: Before you begin with your Core IT phase, take time to learn about
Google Apps, plan for your deployment, and secure resources.
•
First Phase: Core IT: Core IT department users are activated on Google
Apps.
•
Second Phase: Early Adopter: A small number of early adopters are
activated with Google Apps and use it for regular business functions.
•
Third Phase: Global Go Live: All users are activated in Google Apps.
•
Maintenance: After your Global Go Live date, ongoing maintenance involves
keeping up services, monitoring to detect any issues, and updating for
changes to your organization such as departing users, new hires, and name
changes.
Variations for Different Organizations
These steps may vary for your environment. If you are administering an
organization with fewer than 250 users, you may decide to add your Core IT and
Early Adopter users at the same time, and combine these two phases.
Overview of Google Apps Directory Sync
15
If you have already added users through another method, and begin using GADS
afterwards, you may move directly to Global Go Live and continue through
maintenance. In this case, you would not set up a Core IT or Early Adopter phase,
and you would set up GADS to synchronize your users and maintain Google Apps
to match your LDAP data going forward.
Plan
Users: No users added yet.
Before you begin with the Core IT phase, there’s a period of preparation and
planning. During the Plan step, the goal is to understand the services available,
learn technical details, decide what tools to use, identify any need for outside
consulting or support, and set a plan for implementing Google Apps.
Directory Sync: During this phase, begin making preparations for Google Apps.
Specific preparations you can make at this stage include the following.
•
Prepare a provisioning strategy.
•
Secure LDAP resources.
•
Clean up your LDAP directory.
•
Prepare your firewall/proxy settings and network ports to ensure that Directory
Sync has a connection to your LDAP directory and to Google Apps.
Fore more information on these preparations, see “Getting Started” on page 23.
Core IT
16
Release 4.0.2
Users: A small number of manually added users.
In the Core IT phase, a small number of IT users activate in Google Apps and
begin learning and configuring Google Apps. The goal of the Core IT phase is to
learn how to use the applications and utilities, to configure services, and to
prepare for Early Adopters.
Directory Sync: During this phase, continue preparation and testing to be ready
for Directory Sync implementation by the Early Adopter phase.
Typically, GADS is not used to import users for the initial IT pilot, since it is easier
to add your initial IT department users either manually or by uploading a CSV file
into the Google Apps control panel.
If you do have manually added users that are not in your LDAP, remember to add
exclusion rules so those users are not deleted.
Early Adopter
Users: Early adopter business users, either manual or synchronized.
During the Early Adopter phase, set up a small number of active users and give
them the best possible user experience. Early adopters can then become familiar
with Google Apps, identify any common questions or issues, and learn to use the
product so that they can help others after a broader rollout.
Directory Sync: During the Early Adopter phase, prepare your synchronization
rules so that full synchronization will be ready on your Global Go Live date.
Optionally, you can also set up GADS to synchronize data for early adopters. You
can use any of these features for Early Adopter synchronization:
1. You can use GADS during your Early Adopters phase to synchronize your
entire user list, so that your Early Adopter users can see recipient addresses
in Autocomplete when sending mail. You can synchronize users as shared
contacts, or synchronize as full users without sending passwords or routing
users’ mail into Google Apps.
2. If you are running the Early Adopter phase on a separate test domain, GADS
can synchronize users to a test domain, adding users with the same
username in a separate test domain.
3. If you are using Postini Message Security, you can set up Postini for split
delivery, so that Early Adopters receive mail in Gmail while other users
receive mail on your legacy server.
Overview of Google Apps Directory Sync
17
Global Go Live
Users: All users active in Google Apps.
In the Global Go Live phase, all users become active and begin using Google
Apps for daily business. Mail flow is routed entirely to Gmail, users schedule their
activities in Google Calendar, and day-to-day user activities run in Google Apps.
After your Global Go Live date, data from legacy systems may be migrated into
Google Apps, or may be left on legacy servers and checked when needed.
Directory Sync: You can set up GADS to import organizations, users, aliases,
profile information, groups, contacts, and calendar resources so that your Google
Apps account is populated with the same data you have on your LDAP directory
server.
Prepare for your Go Live date. The initial synchronization of a Go Live date can
take several cycles of configuration and tests, since there may be a great deal of
data to synchronize. Be prepared for an extended synchronization, and try to run
your synchronization during off-business hours to avoid consuming network and
system resources during peak hours.
Note also that shared contacts can take up to 24 hours after synchronization to
show up in Gmail autocomplete.
During your rollout, you may decide to split your synchronization into phases to
avoid exceeding any search size limits on your directory server.
Maintenance
Users: Updated to maintain changes between your LDAP directory and
Google Apps.
After you have set up Google Apps and your users are live with the product,
continue to update Google Apps to reflect any changes on your LDAP directory.
18
Release 4.0.2
If you remove any users from your company, update Google Apps to reflect these
changes. Many companies remove a user by changing the user’s password and
access permissions, rather than deleting the user from Google Apps, in order to
smoothly handle the user’s documents and mail archives.
Directory Sync: Check your notification messages regularly to be sure that
GADS is running smoothly, and to detect and address any issues that arise.
You can use GADS to keep your Google Apps directory up to date. You can set up
GADS to run scheduled synchronization, so that all changes to your LDAP
directory server are synchronized with Google Apps. Any changes to your LDAP
directory server, such as new users, deleted users, or users moved to new
organizations, will be reflected in Google Apps.
Also, during maintenance, be sure to check regularly for updates to GADS. You
can check for new updates by opening Configuration Manager, or by running the
command checkforupdate.exe.
Depending on your needs, you may run scheduled synchronizations at different
rates. Usually, this ranges between once an hour and once a day. Be aware that
running synchronization too often may use up excess bandwidth or exceed
quotas.
System Requirements
Before you begin using GADS, be sure you can meet the following system
requirements.
Google Apps Account
•
A Google Apps domain running Google Apps for Work, Google Apps for
Partners, Google Apps for Government, or Google Apps for Education.
Note: GADS only synchronizes primary domains, not domain aliases.
•
Access to a Google Apps super admin account to authorize GADS.
Overview of Google Apps Directory Sync
19
Server Requirements
•
A server to run GADS. The server should run one of the following operating
systems:
•
Microsoft Windows (supported on XP, Windows 7, Windows 8, Windows
Server 2003/2008/2012)
•
Linux
•
If you’re using a 32-bit version of GADS on a 64-bit Linux system, a 32-bit
libc (such as libc6-i386) must be installed.
•
At least 5 GB of disk space for log files and data. If you are running with
DEBUG or INFO level of logging, you may need more free space than this for
additional log data.
•
At least 256 MB of free RAM. At least 1 GB of free RAM is recommended if
you have less than 10,000 users, or 2 GB of free RAM if you have more than
10,000 users. For very large organizations (over 250,000), further tuning may
be needed.
•
An LDAP server with user information which is accessible to GADS. All
versions of the LDAP protocol are supported.
•
Network access to your LDAP server. You do not need to run GADS on your
LDAP server.
•
Read and execute administrative access over the appropriate OU structure of
the LDAP server.
•
An LDAP browser that can read and browse your LDAP directory server data.
•
Network access to the Google Apps through HTTPS, directly or through a
proxy server. This includes ports 80 and 443.
•
For best results, a network connection to Google Apps with no proxies or
firewalls is recommended.
•
A mail server able to accept and relay notifications from Directory Sync.
•
Access to SSL Authorities for your network.
Level of Effort and Expertise
The level of effort for using GADS varies based on the scope of your
synchronization plans, your familiarity with the LDAP query language, and your
familiarity with your own LDAP directory server and data.
In many cases, the initial configuration of GADS includes multiple revisions of
synchronization rules, updating and refining your LDAP synchronization rules until
a simulated sync delivers expected results.
20
Release 4.0.2
Depending on your configuration, you may need the following levels of expertise
for implementing GADS:
•
Google Apps administrator: Access to your Google Apps administrator
account and familiarity with the Google Apps control panel.
•
LDAP administrator: Access to your directory server and familiarity with its
contents. Familiarity with LDAP query language.
•
Network administrator: Familiarity with your network and security settings
for internal and outbound traffic.
•
Mail administrator: Access to a mail server able to relay messages for
Directory Sync notifications. Familiarity with setting up mail servers for traffic.
•
Human Resources contact: Familiarity with user base and ability to identify
which LDAP entries represent current employees.
Overview of Google Apps Directory Sync
21
22
Release 4.0.2
Chapter 3
Getting Started
Chapter 3
Overview
This chapter discusses the steps you’ll take when you get started with Google Apps Directory Sync
(GADS). Your GADS configuration will be faster and smoother if you collect information about your
network, LDAP directory server, LDAP data, and synchronization plans before you begin. This chapter also
includes necessary steps for setting up your Google Apps account and your internal network before you
install GADS.
For a more successful synchronization, follow the steps detailed below.
Getting Started Steps
The following list describes typical steps for preparing, planning, and implementing GADS.
Note that these steps do not correspond precisely to the three-phase model described in the previous
chapter in “Directory Sync and Deployment” on page 15. In most cases, you will begin these steps during
the Planning or the Core IT phases of deployment, so that you will have synchronization ready during the
Early Adopter phase.
For details on system requirements and prerequisites, see “System Requirements” on page 19.
1. Install an LDAP browser. Download an LDAP browser to examine your current LDAP directory
server. For more information, see “Step One: Install LDAP Browser” on page 24.
2. Collect LDAP inventory. Identify your LDAP resources, including LDAP servers and expert
administrators. Collect required information about your LDAP server and your Google Apps domain.
For more information, see “Step Two: Collect LDAP Inventory” on page 25.
3. Decide what to synchronize. Decide what domains to synchronize. Plan which users, aliases, and
groups you want to synchronize with Google Apps. This can be a very significant step, and may
require a great deal of planning. For more information, see “Step Three: Decide What to Synchronize”
on page 28.
4. Prepare Google Apps for synchronization. Make any needed changes to Google Apps. For more
information, see “Step Four: Prepare Google Apps for Synchronization” on page 38.
Getting Started
23
5. Prepare your server environment for synchronization. Confirm that you have a notification mail
server ready. For more information, see “Step Five: Prepare Your Servers for Synchronization” on
page 39.
6. Install GADS. Once you have the needed information, download and install GADS. This step is
covered in “Installation” on page 45.
7. Configure GADS. Run Configuration Manager, part of GADS, to configure synchronization. This step
is covered in “Configuration” on page 49.
8. Simulate synchronization. Use Configuration Manager to simulate a synchronization and review the
results. This step is covered in “Sync” on page 131.
9. Revise configuration. Review the results of the simulated sync. If needed, revise your configuration
in Configuration Manager based on the simulation. This could take several revisions for complex
environments.
10. Preview synchronization. At the command line, run a synchronization in preview mode with the
configuration file you created. Check the results. This step is covered in “Command Line
Synchronization” on page 135.
11. Synchronize manually. At the command line, run a manual synchronization to update Google Apps.
The first synchronization, which imports all information, is likely to take much longer than later
synchronizations. This step is covered in “Command Line Synchronization” on page 135.
12. Schedule regular synchronization. Using your server’s scheduling tools, set up automatic
scheduled synchronization. This step is covered in “Scheduling Synchronization” on page 137.
13. Monitor syncs. Monitor the results of your ongoing synchronization to detect and address any
problems that occur. This step is discussed in “Monitoring” on page 139.
The first steps, related to preparation, are covered in this chapter below. Later steps are covered in future
chapters as noted.
Step One: Install LDAP Browser
By default, most LDAP directory servers do not include a way to view or modify your LDAP structure
directly. To collect information about your LDAP structure, download and install an LDAP browser. Two
such browsers are listed below.
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
24
Release 4.0.2
JXplorer
To download the JXplorer Java Ldap Browser, go to:
http://www.jxplorer.org
Step Two: Collect LDAP Inventory
You can deploy GADS more quickly if you identify your LDAP resources beforehand. Depending on the
size and structure of your organization, you may already know all this information, or you may need to do
some research.
Identify LDAP Resources
Contact your LDAP administrators and collect the following information:
•
The hostname or IP address of your LDAP server. Note that GADS can only synchronize with one
LDAP server.
•
Your network access, proxy servers, and outbound connections.
•
The name and password of an account on your LDAP with “read” and “execute” permissions. If you
want to limit what users and OUs you want to synchronize, you can set up an LDAP administrator with
limited permissions on your directory server. See your directory server documentation for steps on how
to do this.
•
Confirmation that your chosen LDAP directory has full access to needed resources.
If you have multiple LDAP directories, consider the following:
•
Consolidate. If you are using multiple directories, consolidate your LDAP data into a “single source of
truth.” Many customers have multiple LDAP directories, either because of different departments,
acquisitions, or subsidiaries. GADS can only pull data from a single LDAP directory.
•
Test Global Catalog. If you have multiple Microsoft Active Directory domains, a Global Catalog may
help with your synchronization, but only if the catalog is set up with proper replication. If you want to try
using a Global Catalog, be sure to test the catalog thoroughly before relying upon it.
Sample Scenario: Identify LDAP Resources
MobiStep, Inc., is a medium-sized manufacturing company that has moved to Google Apps and is starting
to synchronize an existing LDAP directory server with Google Apps. The Google Apps administrator
contacts the LDAP administrator, who provides the following information:
•
An LDAP administrator account (with appropriate permissions) created specifically for GADS.
•
The IP address and hostname of the LDAP server.
The Google Apps administrator confirms with Human Resources that the users on this server are all active
users, and confirms that this is the only LDAP directory server.
The LDAP administrator confirms that GADS will be run within the company’s firewall and that the LDAP
server will not need to be open to the outside.
Getting Started
25
Research LDAP Structure
Use an LDAP browser to collect information about your LDAP server and structure.
You may find, while preparing for synchronization, that you have unexpected or non-standard data in your
LDAP directory server. It is always better to find and address this before you begin synchronizing.
Be sure to collect the following key information:
•
LDAP Base DN: GADS will use this Base DN as the top level for all LDAP queries. You can use an
LDAP browser to collect this information. If your LDAP directory server includes OUs that you do not
want to sync, consider a Base DN that doesn’t include these OUs. Since GADS searches for both
users and groups from the Base DN, specify a Base DN on a level that includes the users and groups
you want to synchronize.
Note: You can use multiple Base DNs in a configuration. You can specify a separate Base DN for each
synchronization rule. For more information, see “User Search Rules” on page 84.
•
LDAP Structure Information: You need to know which OUs contain users and other resources you
want to sync and which LDAP attributes contain important information. Look through your LDAP
directory structure with an LDAP browser, then examine some sample users and other resources to
identify the LDAP attributes.
In many cases, the LDAP attribute that contains a user’s mail address, which will become the
username in Google Apps, is the mail attribute. Confirm the LDAP attribute you want to use for mail
addresses.
Check your LDAP directory server to find out which attributes contain the data you need. In some
cases, this data may include spaces.
Once you have collected this information, you are ready to start making decisions about your
synchronization.
Sample Scenario: Research LDAP Structure
MobiStep’s administrator downloads an LDAP browser and look through the directory structure. The
administrator finds that the Base DN to use for the domain ad.mobistep.com is:
ou=users,ou=headquarters,dc=ad,dc=mobistep,dc=com
Then, the administrator looks more closely at the structure, and finds that the OUs are divided up by
department function. Each department function is a separate OU under the Base DN. Department OUs
include: sales, manufacturing, it, genadmin, hr, contractors, and exec.
Clean Up LDAP Data
While you are identifying your LDAP data, be aware that you may need to clean up your LDAP directory
server data to synchronize with Google Apps. Begin cleaning up your LDAP data early, to avoid data
cleanup blocking your schedule for synchronization.
26
Release 4.0.2
When conducting LDAP cleanup, consider the following actions.
•
Identify users. Identify which users you want to synchronize with Google Apps. You may need to
consult with your human resources department to confirm that your user list is the correct list of users
to synchronize.
•
Populate Password Attribute (Optional). If you are using a password field in GADS, create a custom
attribute in your LDAP for your Google Apps users, and populate the attribute with a password setting.
Generate random passwords and add them to a custom attribute. For more information about
Passwords, see “Passwords” on page 32.
•
Set Naming Conventions (Optional). Identify any email naming conventions you want to use, and
update any users to fit these naming conventions. This is optional: you do not need to set any
particular naming convention for GADS, but some companies use the transition to Google Apps as an
opportunity to change naming standards.
•
Mail-Enabled Groups. Identify mail-enabled groups to synchronize with Google Apps. This includes
only mail-enabled groups that operate as mailing lists, not security groups. Note also that you can set
Google Apps to allow users to create and manage their own groups; these are not affected by
synchronization.
•
Plan Resource Naming Conventions. If you are planning to synchronize calendar resources, you
can take this opportunity to plan a naming convention in Google Apps. For more information on this
calendar resource naming, see the Google Code site article Developing a naming strategy for your
calendar resources.
Sample Scenario: Clean Up LDAP Data
The MobiStep LDAP Administrator cleans up the MobiStep LDAP database to get ready for
synchronization.
The administrator uses an LDAP browser to identify users and mail-enabled groups. The existing names
already follow a standard naming convention, and the administrator decides to keep that naming
convention.
The LDAP administrator also creates a custom attribute for one-time passwords. Later, this will be used to
hold randomly generated passwords for new users.
Mark Google Apps Users In LDAP
One of the most effective ways to simplify your synchronization is to mark Google Apps users beforehand
in your LDAP directory. The benefit of marking your Google Apps users in LDAP is that it will simplify your
LDAP queries, make your transition to Google Apps clear and visible, and possibly bypass any
complications with your existing LDAP directory structure.
When you first clean up your LDAP directory structure, mark the users you plan to move into Google Apps
with an OU, group, or custom attribute. Use a descriptive name like “GoogleAppsUsers.” Use this to mark
all users whom you plan to move into Google Apps.
Then, once you begin synchronization, mark active Google Apps users. Create an OU, group, or custom
attribute with a name like “GoogleAppsActiveUsers.” You can then configure Directory Sync to synchronize
based on this OU, group, or custom attribute, then activate new users in Google Apps by updating your
LDAP server.
Getting Started
27
There are three ways to mark your Google Apps users in LDAP:
•
OU: Set up an organizational unit (OU) and move Google Apps users into that unit.
•
Group: Create a new group in LDAP, and add Google Apps users as a member of that group.
•
Custom Attribute: Create a custom attribute for your users, and set that attribute for new users.
Use whichever method works best for your LDAP directory environment.
The exact steps necessary to set up an OU, group, or custom attribute will vary based on your LDAP
directory server. Consult your LDAP directory server documentation and work with your LDAP
administrator to configure your LDAP server appropriately.
Sample Scenario: Mark Google Apps Users In LDAP
The administrator creates two new groups on LDAP, GoogleAppsUsers and ActiveGoogleAppsUsers. All
users who are identified to be synchronized into Google Apps are added to the GoogleAppsUsers group.
When users are added into Google Apps, and have their mail flow switched over, those users are also
added to the ActiveGoogleAppsUsers Group. This will make it easier to track which users are in Google
Apps, and allows a clean synchronization without removing old accounts that will not be synchronized into
Google Apps.
Step Three: Decide What to Synchronize
Once you have identified your LDAP servers, decide what to synchronize.
For specific suggestions on what to synchronize during an early adopter program or other parts of your life
cycle, see “Roadmap for Deployment” on page 33, in this chapter.
Domains
Decide what domains you want to synchronize on your LDAP server and in Google Apps. Google Apps
Directory Sync can synchronize with multiple domains on the same account.
•
Domain: Before you configure synchronization, decide what domain you want to synchronize, and set
up your domain in Google Apps.
28
Release 4.0.2
Note: GADS does not create a domain for you, so you will need to add the domain before you use
Directory Sync.
Collect the exact domain name from the Google Apps control panel. Note that you cannot synchronize
a domain alias.
•
Domain Name Replacement: You can also specify another domain. Directory Sync will create or
update all users in the new replacement domain. This is most often used for a pilot domain, but can
also be used if you are using GADS to move to a new domain. If you specify another domain in
Configuration Manager, you can import a full list of users into a different domain. Note that using
domain replacement can affect your Google Apps exclusion rules. See GADS Troubleshooting article.
Note: Even if you use domain name replacement, your Shared Contacts' domain names won't be
replaced, because Shared Contacts are meant to be used for external contacts, not addresses from
your own domain
Set up the new domain as a primary domain in Google Apps. Then, in Configuration Manager, enter
the new domain as your Google Apps domain, and use a Google Apps administrator for that domain.
In Google Apps Settings, set Directory Sync to replace domain names in LDAP email addresses with
this user name. Google Apps Directory Sync will rename all your users to that new domain during
synchronization.
After your pilot period is complete, you can change the domain name (and Google Apps administrator)
to your actual primary domain, and keep all other configuration options the same. For more information
on setting up your domain name, see “LDAP Connection Settings” on page 65.
User Data
GADS can synchronize a wide variety of user data. This includes users, passwords, alias information, and
profiles. Examine your LDAP directory data and your Google Apps configuration to decide what data to
synchronize. You may need to purchase additional licenses in Google Apps if you add users above your
current number of licenses.
Consider the following synchronization options:
•
Users: Look through your whole set of users with an LDAP browser. For more information about using
an LDAP browser, see “Step One: Install LDAP Browser” on page 24.
You may have internal-only users, or special users that should not have external email (such as
printers). You may also decide to start by synchronizing only a small trial group of users. Construct an
LDAP query for the users you want to synchronize. For more information on constructing LDAP
Getting Started
29
queries, see “About LDAP Queries” on page 41.
WARNING: Check to be sure that you are importing the correct number of users. If you import more
users than you have licenses in Google Apps, you may experience errors during synchronization for
exceeding your user limit.
•
User Profiles: If your LDAP directory server includes further information, such as addresses, phone
numbers, or contact information, you can synchronize this information into Google Apps.
You can use GADS to import the full names of your users into Google Apps. If you want to do this, find
the LDAP attributes that contain this information. User names are often stored in two attributes: one for
the first name and one for the last name. If you do not have an LDAP attribute with the appropriate
information, you can skip this step.You can synchronize this through LDAP extended attributes. For
more information, see “User Profiles” on page 101.
If you have full user profiles in your LDAP directory server and you want to synchronize this
information into Google Apps, you can import User Profiles. For more information, see “User Profiles”
on page 101.
•
Aliases: You can synchronize one or more attributes for aliases from your LDAP directory into Google
Apps nicknames. Use an LDAP browser to confirm the LDAP attribute (or attributes) you want to use.
Be sure that the attribute contains only an email address, and not other data such as a phone number.
•
Unique ID: If your users are likely to change user names, set up a Unique ID attribute beforehand so
that user information is not lost when a user changes their name. This should be a field on your LDAP
that is unique for each user, and will not change when your users change names. On Active Directory
servers, the objectGUID attribute is recommended.
•
Passwords: GADS supports a limited set of password operations. If you want GADS to handle
passwords, this requires additional preparation and planning. For more information, see “Passwords”
on page 32.
If you have an Active Directory server, you can keep your LDAP passwords synced to Google Apps
with Google Apps Password Sync. For more information on Google Apps Password Sync, see the
Google Apps admin help center:
http://support.google.com/a/bin/answer.py?answer=2611859
•
Deleted and Suspended Users: By default, users not found on your LDAP directory will be deleted
from Google Apps, and suspended users will be ignored. If this is what you want GADS to do, leave
deleted and suspended users settings at the default.
You can set GADS to suspend users instead of deleting them. This allows for data recovery if users
are later recovered, and the ability to view and transfer a user’s assets.
If your Google Apps account has suspended users that you want to remove, you can instead set
GADS to delete suspended users. You cannot use this setting if you use the option, described in the
paragraph above, to suspend users instead of deleting them.
For more information on these options, see “Additional User Attributes” on page 79.
Groups and Mailing Lists
There are several ways to organize your users in Google Apps. Different lists and groups can be
synchronized into Google Apps in different ways.
Decide how you want to organize your users, and consider the following topics.
30
Release 4.0.2
•
Mailing Lists: Decide which mailing lists you want to synchronize from your LDAP directory server
into Google Apps. Mailing lists on your LDAP directory server will be imported as groups in Google
Apps. You may not want to import all mailing lists, since some lists may be internal lists, or company
resources such as rooms or printers, or may contain unusable data. GADS will not modify or overwrite
groups that users create with the Google Groups for Work service. For information on synchronizing
mailing lists, see “Groups” on page 91.
If you do want to synchronize Mailing Lists, find out what attribute contains the members of your
mailing lists. This is often the member attribute or the mailAddress attribute, but your LDAP directory
server may be different. If this attribute is also used for other data, you may need to use another
attribute or to clean up your LDAP directory server. Be sure to exclude empty lists.
Also, find out if the LDAP attribute for mailing list members contains an email address, or a user
Distinguished Name. Some mailing list attributes contain a literal address, which follow a format like
[email protected]. Some contain Distinguished Name reference, which follow a format like
cn=Terri Smith,ou=Executive Team,dc=mobistep,dc=com. GADS can synchronize mailing lists using
either format, but you’ll need to know which you’re using beforehand so you can configure GADS
properly.
•
Org Structure: By default, GADS synchronizes all users into a single flat structure. This works well if
you have a small organization, or if you want all users to have the same settings and rights. This also
works well if you are piloting a small group before a larger rollout.
If you want to use an org unit hierarchy in Google Apps, you can synchronize the organization
hierarchy from your LDAP directory server. If you do so, look through your OUs with an LDAP browser
beforehand to be sure that you are synchronizing the right OU structure. You may have special OUs
that should not have org units in Google Apps, such as an OU for printers. For more information about
synchronizing your OU structure, see “LDAP Org Units” on page 66.
If you want to create Google Apps organizations manually, you can set those organizations up in
Google Apps, then set GADS to move users into those Google Apps organizations, without changing
existing organizations. To set this up, select “Do not create or delete Google Organizations, but move
users between existing Organizations, as specified in the User Sync Rules” option on the Org Units
page. For every user search rule, specify the organization that should contain users for that rule, or an
LDAP attribute that contains the name of the appropriate Organization. For more information about
moving users between existing organizations, see and “User Search Rules” on page 84.
Contacts and Calendar Resources
GADS can also synchronize other LDAP resources into Google Apps, such as shared contacts and
calendar resources.
•
Shared Contacts: If you want to import addresses into Google Apps as shared contacts, enable
Shared Contacts in General Settings. Shared Contacts will be visible to every user on a contacts list.
When users enter email addresses for recipients in Gmail, addresses in Shared Contacts will show up
in Autocomplete.
Note that this will only synchronize shared contacts; personal contacts are not imported with GADS.
Shared contacts are contacts that can be viewed by every user in the account. These are different
from personal contacts, which are each viewed and edited by an individual user. For more information
about Shared Contacts, see “Shared Contacts” on page 109.
If you’re setting up a pilot with a small group of users, you can use Shared Contacts to synchronize the
rest of your user base into your shared contacts list, so that pilot users will see addresses in
Autocomplete that haven’t been synchronized yet. If you decide to do so, however, note that you
should remove these shared contacts before your full synchronization, to avoid duplicate
Getting Started
31
Autocomplete addresses.
Important: Shared Contacts do not show up immediately. After you synchronize Shared Contacts, it
may take up to 24 hours for the changes to appear in Google Apps.
•
Do you want to synchronize Calendar Resources? If you want to import calendar resources (such
as conference rooms) from your LDAP into Google Apps, configure Calendar Resources
synchronization. Calendar Resources are visible to every user when attempting to schedule calendar
events. For more information, see “LDAP Calendar Resources” on page 119.
If you do want to synchronize calendar resources, choose a naming format for your calendar
resources. Note that names containing spaces or special characters (like @) will not be synchronized.
The rules for calendar resources names are different than other synchronized information. For more
information on this calendar resource naming, see the Google Code site article Developing a naming
strategy for your calendar resources.
Passwords
Directory Sync can import passwords from LDAP, but only in an LDAP attribute that stores passwords in
plain text, Base64, unsalted MD5, or unsalted SHA-1 format. Other password encryption hashes are not
currently supported, nor are salted hashes. Most directory servers do not support these formats natively,
and storing your user passwords in these formats on your mail server may have serious security
implications.
For password synchronization, GADS provides the following options:
•
Implement Single Sign-On for your domain. Set up a SAML server for your account to manage
Single Sign-On. Users will use the same passwords and authorization for both Google Apps and your
LDAP directory server. GADS will create random passwords during synchronization in this case.
Note that Single Sign-On supports only web authentication. Other forms of authentication (such as
IMAP, POP, and ActiveSync) do not support Single Sign-On and will still require a Google password.
Use this option if you are planning to set up Single Sign-On for your domain. For more information on
Single Sign-On, see the SSO site on Google Code.
•
Use a plain text LDAP attribute for default password for new users. With this option, Google Apps
passwords are separate from passwords on your LDAP directory server. You can use this method to
create a temporary password from any LDAP attribute that holds data in plain text format.
The most secure way to create a default password is to populate a custom attribute with a randomly
generated password. Alternately, you can use a private and unique field, such as employee ID number.
Avoid using a field that could be easily guessed, such as email address or last name, since this could
make it easier for other users to sign up using temporary credentials.
Use this option if you want users to have separate one-time passwords, and you have or can create an
appropriate LDAP field to use for temporary passwords.
•
Use a third-party utility to convert unsupported passwords to a supported format. Check the
Google Marketplace for third-party tools to help with synchronizing passwords. Use this option if you
need to have Google Apps use the same passwords as your LDAP directory server, but you are
unable to set up a SAML server. This may require you to set new passwords on your LDAP directory.
•
Specify a default password for new users. Every new user will have the same password until that
user logs in and changes the password. With this option, Google Apps passwords are separate from
passwords on your LDAP directory server. Set a default password for new users, and then set
Directory Sync to synchronize passwords for new users and force new users to change their
32
Release 4.0.2
passwords.
Because this password may be guessed by other users, this is not generally recommended as a
secure option.
Important: Be careful of the security considerations of passwords. Also, note that if you use a plaintext
password, be sure to set GADS to synchronize passwords only for new users, and to require new users to
change passwords.
Mapping
Decide how your LDAP directory server data should map to your Google Apps data. You should have a
clear picture of where every user, group, and resource in your LDAP directory server should be
synchronized in your Google Apps data.
For a chart of how your LDAP data maps to Google Apps, see “What Is Synchronized” on page 13.
Note that you may have some users who should not be synchronized, either on your LDAP server or in
Google Apps. Prepare a list of exceptions so that you know what rules to set up.
•
Mapping: For each group of users, decide whether those users should be imported, and where those
users should be imported. You can set up this mapping to a flat hierarchy, an automatic one-to-one
synchronization, or a manual set of custom rules.
•
Exceptions on Google Apps: Are there any exceptions on your Google Apps domain that you don’t
want to synchronize? Your Google Apps account may have users or groups that you don’t want to
synchronize with LDAP. This could include new users not listed in your LDAP directory, pilot test
accounts, shared Google Apps accounts, or other entries that belong in your Google Apps account but
not your LDAP directory. Find out which users and groups you’d like to exclude, and look for any
common pattern that may simplify exception rules.
•
Exceptions on LDAP Directory: Are there any exceptions on your LDAP directory that you don’t
want to synchronize? Your LDAP directory server may have obsolete users, suspended users, test
accounts, printers, defunct mailing lists, or other data that you do not want to import into Google Apps.
In most cases, you can set your LDAP search rules to ignore these users, but in some cases, you may
need to set up manual exception rules to skip specific users, or a pattern of users. Identify any
exceptions that you don’t want to synchronize, and note these so that you can create exceptions
during configuration.
Roadmap for Deployment
The best settings to use for synchronization depend on your situation, server, and stage in the life cycle of
using GADS. The following roadmap suggests likely settings for different stages of a deployment.
Getting Started
33
For more information about deployment phases and the 3-phase deployment model, see “Directory Sync
and Deployment” on page 15.
Goals in this
phase
Core IT
Early Adopter
Go Live
Maintenance
Clean up data
and prepare for
migration in Early
Adopter phase.
Test connectivity
and
synchronization.
By the end of the
Early Adopter
phase, you
should have
GADS ready for
your Global Go
Live date.
Switch users over
to Google Apps.
Set Google Apps
up as primary
service.
Keep Google
Apps data
synchronized with
your LDAP
directory.
The first
Synchronization
can take time.
Synchronize a
few days in
advance of your
Go Live date so
that users will be
ready. In some
cases, it may be a
good idea to
synchronize over
a weekend.
Plan a scheduled
synchronization
of Google Apps.
Scheduled
synchronization
will take less time
and resources
than the first
synchronization.
Optionally, you
can use a
“shadow” or test
domain, replacing
domain names
with a subdomain
of your existing
organization, like
test.exmpl.com.
Use your primary
domain for
synchronization.
Use your primary
domain for
synchronization.
Domains
34
Release 4.0.2
Core IT
Early Adopter
Go Live
Set up exceptions
for manuallyadded Core IT
users, temporary
administrators, or
other users that
are not part of
your LDAP
search rules.
Synchronize your
early adopters or
add them
manually. Mark
which users are
activated in your
LDAP directory.
Set up exceptions
for Google Apps
users that are not
listed in your
LDAP directory.
Maintenance
Users
Create an LDAP
OU, group, or
custom attribute
for users that will
be synced into
Google Apps.
Then, create a
group or custom
attribute for active
Google Apps
users.
Optionally, you
can synchronize
all users (but not
change their mail
flow or send
passwords), so
that all addresses
will be visible in
Autocomplete.
User Profiles
If your LDAP
directory includes
rich profile data,
you can
synchronize this
with Google
Apps.
Aliases
Passwords
If you are syncing
your users, sync
passwords as
well.
Getting Started
35
If your LDAP
directory includes
rich profile data,
you can
synchronize this
with Google
Apps.
If your LDAP
directory includes
rich profile data,
you can
synchronize this
with Google
Apps.
Core IT
Early Adopter
Go Live
Maintenance
You can
synchronize
Google Apps
users as
suspended users
for testing Google
Apps functionality.
Suspended users
can be used for
early migration of
data.
Usually not used
after go live date,
but available if
you want to
suspend users
instead of
deleting them.
Usually not used
after go live date,
but available if
you want to
suspend users
instead of
deleting them.
Most mailing lists
will still be
maintained on
legacy server.
Mailing lists
should now be
managed in
Google Apps as
groups.
Suspended
Users
Mailing Lists
GADS does not
synchronize or
overwrite usermanaged mailing
lists (groups).
Org Structure
Optionally, start
setting up your
org structure in
advance during
Early Adopter
phase.
36
Release 4.0.2
If you have a
large organization
or complex
hierarchy in your
LDAP directory
server that you
want to keep,
configure
Directory Sync to
synchronize Org
Structure.
Changes to your
Organization
Structure
Mapping rules will
move users within
Google Apps.
Core IT
Early Adopter
Go Live
Maintenance
Optionally, you
can synchronize
all users as
shared contacts
so that they will
be visible in
Autocomplete.
If your company
directory has
shared contacts,
you can
synchronize
these during your
Go Live
synchronization.
If your company
directory has
shared contacts,
you can
synchronize
these during your
Go Live
synchronization.
Note that
personal contacts
are not
synchronized.
Note that
personal contacts
are not
synchronized.
Shared
Contacts
Note that these
shared contacts
may lead to
duplicate contacts
if not removed
before your Go
Live date.
Calendar
Resources
Most calendar
resources will be
maintained on
legacy server.
Calendar
resources should
now be managed
in Google Apps.
Primary Key
Attribute
Set up Primary
Key Attribute for
easier ongoing
maintenance.
Primary Key
attributes help
users keep data
after a name
change.
Sample Scenario
The Google Apps administrator for MobiStep decides that the existing organization hierarchy on the LDAP
server should be copied onto Google Apps, and identifies the OUs that should be synchronized.
Getting Started
37
The administrator decides that MobiStep needs to synchronize:
•
OUs
•
Users
•
Aliases
•
Groups (mailing lists)
•
Shared contacts
•
Calendar resources
The mailing lists in the LDAP server use the attribute member to store the members of each mailing list, and
the member attribute contains the full DN of the mailing list members, rather than their email address. The
GADS administrator notes this attribute, and notes that it is a reference attribute, not a literal attribute.
Because the LDAP user profile information on the LDAP server is not in a standard format across
organizations, the Google Apps administrator decides not to synchronize this information.
The LDAP administrator creates a custom attribute and populates the attribute with a randomly-generated
one-time password. The Google Apps administrator sets up a mail merge to send out these passwords to
users along with information on how to activate their accounts.
The Google Apps identifies that there are some users in the contractors OU that are no longer with the
company and should not be synchronized. The administrator looks through these users and notes that all
of them match a regular expression (the user addresses all begin with “defunct”) and notes this to create
exceptions in Google Apps.
Step Four: Prepare Google Apps for Synchronization
Once you know what to synchronize, there are a few miscellaneous steps you’ll need to take to prepare for
synchronization.
Google Apps Authentication
GADS needs to log into Google Apps to update information. GADS will generate an OAuth token during
configuration, and use that token to connect and synchronize. To authorize GADS you will need a Google
Apps super administrator username and password.
For more information, see “Google Apps Connection Settings” on page 54.
Enable APIs
You must enable API access on your Google Apps domain for GADS to work. See Administrative APIs and
API and control panel configuration for Google Apps Directory Sync articles for more information.
38
Release 4.0.2
Step Five: Prepare Your Servers for Synchronization
Be sure that your servers and network are prepared for GADS.
Notifications Mail Server
GADS is designed to be used for scheduled synchronization without supervision, once synchronization
rules are set up. Because of this, you will need a mail server that can relay reports from GADS.
Collect the following information:
•
The addresses that should receive notifications.
•
The address the notifications should come from.
•
The SMTP relay host IP address or domain name.
•
The username and password for connecting to the SMTP relay host (if needed).
Sample Scenario
MobiStep’s Google Apps administrator decides to use OAuth, and collects a Google Apps administrator
username and password to configure this.
The administrator also contacts MobiStep’s mail administrator to set up notifications. The existing
MobiStep mail server has a rule to block all relay attempts, so the mail administrator sets up an exception
so that the machine running Directory Sync can relay mail through that server to send out notifications.
The server doesn’t use SMTP authentication, so no username or password are required. The MobiStep
administrator decides that the notifications should come from the address
[email protected] so that notifications can be filtered separately into a label.
Further Steps
Further steps are discussed in later chapters:
14. Install Directory Sync. This step is covered in “Installation” on page 45.
15. Configure Directory Sync. This step is covered in “Configuration” on page 49.
16. Simulate Synchronization. This step is covered in “Sync” on page 131.
17. Revise Configuration. This step is covered in “Configuration” on page 49.
18. Preview Synchronization. This step is covered in “Command Line Synchronization” on page 135.
19. Manual Synchronization. This step is covered in “Command Line Synchronization” on page 135.
20. Scheduled Synchronization. This step is covered in “Scheduling Synchronization” on page 137.
21. Monitoring. This step is covered in “Monitoring” on page 139.
Getting Started
39
40
Release 4.0.2
Chapter 4
LDAP Queries
Chapter 4
About LDAP Queries
GADS uses the LDAP query language to collect data from your directory server.
Before you can synchronize data from your directory server, you will need to
prepare LDAP queries.
The LDAP query language is a flexible standard that supports complex and
powerful logical queries, and is discussed in this section. Google Apps Directory
Sync strictly adheres to RFC 2254, which defines international standards on
LDAP filters.
To build your LDAP queries, you will need to know your LDAP structure. The best
way to collect directory server information is an LDAP browser. For more
information, see “Step One: Install LDAP Browser” on page 24.
Most of the search rules in GADS use LDAP queries for information. The only
exception to this are Exception Rules, which use substring or regular expressions
based on the text of email addresses, not LDAP fields.
Note: This document lists many common queries, but every directory server is
different, and many store information in different fields or formats. To develop
these queries, consult standard LDAP documentation and review your LDAP
structure with an LDAP browser. Google support cannot write LDAP queries for
your environment or debug your LDAP queries.
Syntax
The following syntax is used in LDAP filters:
Name of
Operator
Character
Use
Equals
=
Creates a filter which requires a field to have a
given value.
LDAP Queries
41
Name of
Operator
Character
Use
Any
*
Wildcard to represent that a field can equal
anything except NULL.
Parentheses
()
Separates filters to allow other logical
operators to function.
And
&
Joins filters together. All conditions in the
series must be true.
Or
|
Joins filters together. At least one condition in
the series must be true.
Not
!
Excludes all objects that match the filter.
For examples of how these operators are used, see the common LDAP queries
below.
Common LDAP Queries
The examples below show the most common LDAP queries. These queries are
the most common queries used, and are designed to work with most directory
server environments.
All objects (this may cause load problems):
objectclass=*
All user objects that are designated as a “person”
(&(objectclass=user)(objectcategory=person))
Mailing Lists only
(objectcategory=group)
Public Folders only
(objectcategory=publicfolder)
All user objects except for ones with primary email addresses that begin with
“test”
(&(&(objectclass=user)(objectcategory=person))(!(mail=test*)))
All user objects except for ones with primary email addresses that end with
“test”
(&(&(objectclass=user)(objectcategory=person))(!(mail=*test)))
42
Release 4.0.2
All user objects except for ones with primary email addresses that contain the
word “test”
(&(&(objectclass=user)(objectcategory=person))(!(mail=*test*)))
All user objects (users and aliases) that are designated as a “person” and all
group objects (distribution lists)
(|(&(objectclass=user)(objectcategory=person))(objectcategory=grou
p))
All user objects that are designated as a “person”, all group objects and all
contacts, except those with any value defined for extensionAttribute9:
(&(|(|(&(objectclass=user)(objectcategory=person))(objectcategory=
group))(objectclass=contact))(!(extensionAttribute9=*)))
All users who are members of the group identified by the DN of
“CN=GRoup,OU=Users,DC=Domain,DC=com”:
(&(objectcategory=user)(memberof=CN=Group,OU=Users,DC=Domain,DC=co
m))
Active Directory LDAP: All users
(objectClass=person)
Active Directory LDAP: All email users (alternate)
(&(objectclass=user)(objectcategory=person))
OpenLDAP: All users
(objectClass=inetOrgPerson)
Lotus Domino LDAP: All users
(objectClass=dominoPerson)
Lotus Domino LDAP: All objects with a mail address defined that are designated
as a “person “or “group”:
(&(|(objectclass=dominoPerson)(objectclass=dominoGroup)(objectclas
s=dominoServerMailInDatabase))(mail=*))
LDAP Queries
43
44
Release 4.0.2
Chapter 5
Installation
Chapter 5
About Installation
Google Apps Directory Sync (GADS) is designed to run on Windows or Linux
servers.
The installer is an executable program that installs all needed components on the
server, including managing libraries, classpath variables, and other components.
The installer also uninstalls any existing version of GADS in the same directory.
The sections below contain system requirements, and instructions on how to
install, upgrade or uninstall GADS on your server.
Install Google Apps Directory Sync
To install GADS:
1. Go to the GADS download page at:
http://google.com/apps/directorysync
2. Find the operating system and architecture (32-bit or 64-bit) of the server
where you plan to run GADS and click the corresponding Download link.
Installation
45
3. Download and run the installer.
4. Complete all the steps of the installer.
The installer contains all needed components and can be run offline without any
outside connection.
Note: To run synchronization, you must also enable APIs on your Google Apps
domain. See “Enable APIs” on page 38.
Upgrade Google Apps Directory Sync
GADS automatically checks to see if there are any updates available. If updates
are available, you will be prompted to upgrade when you start Configuration
Manager. When you install a new version of GADS, the installer wizard
automatically detects and uninstalls previous versions of the software in the same
directory.
46
Release 4.0.2
If you upgrade GADS and then open a configuration file that you created in a
previous version, you need to save that configuration file with the current version
before you can continue using it to sync. Before saving, make sure your
configuration was imported into the current version correctly.
Uninstall Google Apps Directory Sync
GADS also includes an uninstaller.
To remove GADS:
1. Open a command line interface and go to the directory that contains GADS.
2. Run the following command:
uninstall
3. In the uninstaller, click Next to uninstall GADS.
4. Once uninstallation has completed close the uninstaller.
All GADS utility files and all libraries not used by other programs will be removed.
Log files and XML configuration files will not be deleted.
Installation
47
48
Release 4.0.2
Chapter 6
Configuration
Chapter 6
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 (GADS).
To start the application, run the GADS Configuration Manager from the Start
menu, or run config-manager from the command line in the directory where you
installed Directory Sync.
Note: Before you use Configuration Manager, collect information about your LDAP
directory server and your Google Apps setup. For more information, see “Getting
Started” on page 23.
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.
•
Run a manual synchronization.
Once you have set up your configuration in Configuration Manager, you can run
your actual synchronization from the command line. See “Synchronization” on
page 135.
Configuration Manager walks you through each step of configuring GADS. 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.
Configuration
49
GADS includes several ways to customize search rules and filters. When
collecting information from your LDAP server, you can define LDAP queries to
extract information. Directory Sync supports RFC 2254, the international standard
on LDAP Filters. For the details, see RFC 2254:
http://www.ietf.org/rfc/rfc2254.txt
GADS 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 red 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.
Important: Store your configuration files in a safe and secure place. Exposed
configuration files are security risks.
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 grayed 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.
If you copy a configuration file to another server, use the Configuration Manager
on the new server to open the file and reenter sensitive data, such as passwords,
and OAuth reauthorization.
Multiple Configuration Files
If you want to use multiple configuration files, you may need extra planning and
preparation. You may wish to use multiple configuration files because of a large
deployment that needs to be split into smaller synchronizations, or to reduce
performance load, or to vary the rate of synchronization,
50
Release 4.0.2
An LDAP query that would return too many results may time out. If this happens,
do not create multiple configuration files to reduce load, because 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 135.
Default Configuration for Active Directory or OpenLDAP
If you’re using GADS with an Active Directory server, you may be able to use
default values provided by Configuration Manager for most of your configuration.
To use the default recommended values on a given page of Configuration
Manager, click the Use defaults button at the bottom of the page (pages without a
Use defaults button do not provide default values). If the Use defaults button is
grayed out, make sure you have selected MS Active Directory or OpenLDAP as
the Server Type on the LDAP Configuration page.
Configuration Best Practices
Follow these best practices to help ensure a speedy and secure GADS
configuration:
•
Use the 64-bit version of GADS if you plan to install GADS on a 64-bit
compatible server. The 64-bit GADS performs better than other versions.
•
Access your LDAP server with a user who has minimal permissions.
GADS reads data from your LDAP server but never modifies it, so you can
configure GADS with an LDAP user that only has read access to your LDAP
directory, or even anonymously if your LDAP setup allows that.
•
Never share your GADS configuration files. Your configuration contains
sensitive information about both your LDAP server and your Google Apps
domain. Don’t share it with anyone who doesn’t need to see it.
•
Simulate before you sync. Whenever you upgrade GADS or change your
configuration, you should simulate a sync before actually syncing. Failing to
do so may result in unintended consequences, such as account deletion or
lockout.
Configuration
51
General Settings
You specify which categories of object to synchronize from your LDAP server on
the General Settings page.
Specify the following:
General Setting
Description
Organizational Units
Whether GADS should synchronize
organizational units. Unchecked by default.
Users Accounts
Whether GADS should synchronize users.
Checked by default.
For more information, see “User Accounts” on
page 76.
Uncheck if you do not want to synchronize
users.
52
Release 4.0.2
General Setting
Description
Groups
Whether GADS should synchronize groups.
Checked by default.
For more information, see “Groups” on
page 91.
Uncheck if you do not want to synchronize
groups.
User Profiles
Whether GADS should synchronize user
profiles. Unchecked by default.
For more information, see “User Profiles” on
page 101.
Check if you want to synchronize user profiles.
Shared Contacts
Whether GADS should synchronize shared
contacts. Unchecked by default.
For more information, see “Shared Contacts”
on page 109.
Check if you want to synchronize shared
contacts.
Calendar Resources
Whether GADS should synchronize calendar
resources. Unchecked by default.
For more information, see “LDAP Calendar
Resources” on page 119.
Check if you want to synchronize calendar
resources.
Google Apps Configuration
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 “Getting Started” on page 23.
Configuration
53
Google Apps Connection Settings
Enter your Google Apps connection information in this section.
Specify the following:
Google Apps Setting
Description
Primary Domain
Name
The primary domain you want to synchronize. You
must use your primary domain in Google Apps, not a
domain alias.
If you enter a domain that is different from the domain
on your LDAP server and select the Replace domain
names in LDAP email addresses, Google Apps
Directory Sync renames all users and use the Domain
name listed here instead.
Example: example.com
54
Release 4.0.2
Google Apps Setting
Description
Replace domain
names in LDAP
email addresses (of
users and groups)
with this domain
name.
If checked, all LDAP email addresses are changed to
match the domain listed in Domain Name. For
instance, if your Domain Name is example.com, and
your LDAP query returns an email address
[email protected], then Directory Sync synchronizes
[email protected].
If unchecked, all LDAP email addresses keep their
original domain name.
Important: Note that if the domain is replaced, this may
affect exclusion rules that search for exact match of a
user name. If this setting is enabled, the domain name
is stripped for exclusion rules.
Note: Domain names for shared contacts are not
replaced.
Authorization
Authorize using OAuth: Connect to Google Apps
during synchronization using an OAuth token that you
generate in Google Apps.
Authorize Now
Click Authorize Now to create and enter your
validation token string.
Configuration
55
Authorizing using OAuth
Click Authorize Now to set up your Authorization settings and create a
verification code.
Note: Customer who already use OAuth will need to authorize again with existing
(or new) credentials. This is because GADS now uses the Directory API instead of
the deprecated Provisioning and Profiles Data APIs, which means the scope for
which the tokens were generated has also changed.
1. Click Sign In to open a browser window and sign in to Google Apps.
2. In the browser page, sign in to Google Apps using administrator credentials.
3. After you enter your credentials, Google Apps automatically displays a token.
Copy that token.
4. Enter the verification code you created in Google Apps in the Verification
Code field.
5. Click Validate to confirm that the code is valid.
56
Release 4.0.2
Google Apps Proxy Settings
Provide any necessary network proxy settings here. If your server does not
require a proxy to connect to the internet, skip this page.
Provide the following:
Google Apps Setting
Description
SSL Proxy Host
Name
If your server is running behind a firewall that requires
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
Your SSL proxy’s host port (if any).
(if needed)
Common ports for SSL proxy are 80, 8080, 3128 and
1080.
Example: 80
SSL Proxy User
Name
Your SSL proxy user name (if any).
Example: proxyuser01
(if required)
Configuration
57
Google Apps Setting
Description
SSL Proxy
Password
Your SSL proxy password (if any).
Example: swordfish
(if required)
HTTP Proxy Host
Name
(if needed)
Enter the HTTP proxy host you use for HTML
connections, even if it is the same as the proxy server
you use for SSL connections.
Example: firewall02-http.mixateriacorp.com
Note: Directory Sync always connects to Google Apps
on SSL. The only time Directory Sync sends traffic by
unencrypted HTTP is to validate a certificate with the
issuing authority.
HTTP Proxy Host
Port
Your HTTP proxy’s host port (if any).
Example: 80
(if needed)
HTTP Proxy User
Name
Your HTTP proxy user name (if any).
Example: proxyuser01
(if required)
HTTP Proxy
Password
Your HTTP proxy password (if any).
Example: swordfish
(if required)
Google Apps Exclusion Rules
Exclusion rules let you omit specific users, groups, org units, calendar resources,
and other Google Apps data from the synchronization process. Use exclusion
rules to preserve information in Google Apps that isn’t in your LDAP system.
Note: Exclusion rules control what GADS sees, not what GADS does. For
example, if you exclude a Google Apps user who is also in your LDAP, GADS tries
to create the user on every sync.
You should create exclusion rules for the following, along with any other Google
Apps data you want to preserve:
58
Release 4.0.2
•
Users that are not in your LDAP system
•
Any mailing list addresses you’ve manually added to 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 Add Exclusion Rule.
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.
Users under a particular organization
You can set up a rule to exclude an entire Google Apps organization path.
Note: You can only create Google Apps Organization Complete Path exclusion
rules if you've enabled Organizational Units in the General tab; otherwise, the
exclusion is ignored.
Configuration
59
For instance, if you add all your IT administrators to the organization path
“administrators/IT” and your security administrators in the organization path
“administrators/security” you could use the following rule to exclude both groups
of users, as well as any others under the administrators organization:
•
Type: Organization Complete Path
•
Match Type: Substring
•
Exclusion Rule: administrators
Users not in your LDAP Server
Directory Sync 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: [email protected]
Second rule:
•
Type: Member Name
•
Match Type: Exact Match
•
Exclusion Rule: [email protected]
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
[email protected] and [email protected].
First rule:
•
Type: User Name
•
Match Type: Substring
•
Exclusion Rule: appstrial
Second rule:
60
Release 4.0.2
•
Type: Member Name
•
Match Type: Substring
•
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, Directory Sync will delete them, Therefore, add the
following rule.
•
Type: Group Name
•
Match Type: Exact Match
•
Exclusion Rule: [email protected]
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:
•
Type: Member Name
•
Match Type: Substring
•
Exclusion Rule: @gmail.com
Second Rule:
•
Type: Member Name
•
Match Type: Substring
•
Exclusion Rule: @electric-automotive.com
Add Exclusion Rule
Click Add Exclusion Rule to create an exclusion rule.
Configuration
61
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.
•
Organization Complete Path: Do not delete any
user who is a member of an organization that
matches the complete path rule. Organization
paths are treated as strings with the format
organization/sub-organization/sub-suborganization. The interface displays this choice
as ORGUNIT_PATH.
62
Release 4.0.2
•
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.
•
Calendar Resource Id: Do not remove a calendar
resource if its resource ID matches the rule.
•
Calendar Resource Display Name: Do not
remove a calendar resource if its display name
matches the rule.
•
Calendar Resource Type: Do not remove a
calendar resource if its type matches the rule.
Exclusion Rule Setting
Description
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: [email protected] excludes that
single Google Apps user from user list
synchronization, but not group synchronization.
Group Name: [email protected]
excludes that Google Apps group from groups
synchronization.
Member Name: [email protected] 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
[email protected] and
[email protected].
Group Name: Sales excludes
[email protected] and
[email protected].
Member Name: sales excludes
[email protected] and
[email protected] from groups
synchronization.
•
Regular Expression: The address or organization
must match the regular expression in the rule.
Examples:
User Name the regular expression team[39]@example.com excludes [email protected]
through [email protected].
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[39]@example.com excludes [email protected]
through [email protected] from groups
synchronization.
Configuration
63
Exclusion Rule Setting
Description
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, Directory Sync will attempt to add the user and
fail.
LDAP Configuration
The LDAP Configuration section configures how Directory Sync 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.
64
Release 4.0.2
LDAP Connection Settings
Specify your LDAP connection and authentication in this page.
LDAP Connection
Setting
Description
Server Type
The type of LDAP server you are syncing.
Make sure to select the correct type for your LDAP
server; GADS interacts with each type of server slightly
differently.
Example: MS Active Directory
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
Configuration
65
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.
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
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.
LDAP Org Units
The LDAP Org Units section configures how Directory Sync 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 the Org Units
page, 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
“User Search Rules” on page 84.
66
Release 4.0.2
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.
.
If the Do not create or delete Google Organizations... checkbox isn’t checked,
GADS will add and delete organizations in Google Apps to match your LDAP
organization structure according to the mappings you specify. If the checkbox is
checked, Google Apps organizations aren’t synced with your LDAP server, but
users can still be added to existing Google Apps organizations as specified in
your user search rules.
In a new configuration, this page is an empty list. To add a mapping, click Add
Mapping.
On the list of mappings, you can change existing mappings:
•
Reorganize: Click the up arrow or down arrow icon to change the order of
mappings.
•
Edit: Click the notepad icon to edit the settings of a mapping.
•
Delete: Click the X icon to delete a mapping.
Mappings are processed in the order listed. If you would like one mapping to take
priority over another, move that mapping up using the up arrow icon on this page.
If two rules contradict each other, the first rule takes precedence.
Configuration
67
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: /
Third Rule (exception for Executives):
68
Release 4.0.2
•
(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.
Specify the following:
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)
Name
The name of the org unit in Google Apps to map.
To add users to the default Organization in Google
Apps, enter a single forward slash /.
Example: Melbourne
Configuration
69
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 Add Search Rule.
On the list of Search Rules, you can change existing rules:
•
Reorganize: Click the up arrow or down arrow icon to change the order of
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.
70
Release 4.0.2
Add Org Unit Search Rule
To add a new search rule, click Add Search Rule and specify the fields in the
dialog box. After specifying the fields, click Apply to submit your changes, or Test
LDAP Query to test the search rule.
LDAP Org Unit Search
Rule Setting
Description
Org Unit Description
Attribute
An LDAP attribute that contains the description of each
org unit.
This field is optional. If left blank, your Org Units will not
contain a description when created.
Example: description
Scope
This determines where in the LDAP directory this rule
applies. Choose which option to use:
•
Sub-tree: 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: Sub-tree
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 “About LDAP Queries”
on page 41.
Configuration
71
LDAP Org Unit Search
Rule Setting
Base DN
Description
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
Org Unit 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.
72
Release 4.0.2
Some examples of reasons for LDAP org unit exclusion rules:
•
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 rules. In a new configuration, this will be an
empty list. To add an exclusion rule, click Add Exclusion Rule.
In the list of exclusion rules, you can change existing rules 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.
As a recommended safeguard, you can limit how many of your organizations
GADS can delete during synchronization. Specify either a percentage or raw
number of your domain’s organizations in the corresponding field.
Example LDAP Org Unit 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
73
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:
•
Match Type: Exact Match
•
Rule: ou=earlystatements,u=finance,ou=users,dc=ad,dc=example,dc=com
Second rule:
•
Match Type: Exact Match
•
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.
•
74
Release 4.0.2
Match Type: Regular Expression
Rule: ou=internal-test[0-9]*,dc=ad,dc=example,dc=com
Add Rule
Click Add Exclusion Rule to exclude an org unit in your LDAP server from
synchronization.
Specify the following:
Exclusion Rule Setting
Description
Exclude Type
This Exclude Type is always Org Unit DN.
•
Match Type
Org Unit DN: Base the exclusion rule on the
Distinguished Name (DN) of the org unit to
exclude.
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
75
Exclusion Rule Setting
Description
Exclusion 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.*
User Accounts
The User Accounts 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.
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 136), the users must be
read in, in order to resolve Reference Attributes for group members or group
owners.
76
Release 4.0.2
User Attributes
Specify what attributes Google Apps Directory Sync will use when generating the
LDAP user list.
LDAP User Attribute
Setting
Description
Email Address
Attribute
The LDAP attribute that contains a user’s primary
email address.
Example: The default is mail.
Unique Identifier
Attribute
An LDAP attribute that contains a unique identifier for
every user entity on your LDAP server. Providing this
value enables GADS to detect when users are
renamed on your LDAP server and sync those
changes to Google Apps.
This field is optional, but recommended.
Example: objectGUID
Alias Address
Attributes
(if needed)
One or more attributes used to hold alias addresses.
These addresses will be added into Google Apps as
nicknames of the primary address listed in the Email
Address Attribute field.
Example: proxyAddresses
Configuration
77
LDAP User Attribute
Setting
Google Apps Users
Deletion /
Suspension Policy
Don’t suspend or
delete Google Apps
admins not found in
LDAP
78
Release 4.0.2
Description
Options for deleting and suspending users.
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.
If checked, prevents GADS from suspending or
deleting administrator accounts found in Google Apps
that don’t exist in your LDAP server.
Additional User 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, Directory Sync will not
import this information.
LDAP Extended Attribute
Setting
Given Name Attribute(s)
Description
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.
You can also use multiple attributes for the
given name. If you use multiple attributes,
place each attribute field name in square
brackets.
Examples: givenName,[cn]-[ou]
Configuration
79
LDAP Extended Attribute
Setting
Family Name Attribute(s)
Description
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.
Examples: surname,[cn]-[ou]
Synchronize Passwords
Indicates which passwords Directory Sync will
synchronize.
Options are:
•
Only for new users: When Directory Sync
creates a new user, it synchronizes that
user’s password. Existing passwords are
not synced. Use this option if you want
your users to manage their passwords in
Google Apps.
Note: If you are using a temporary or one-
time password for new users, use this
option.
•
For new and existing users: Directory
Sync always synchronizes all user
passwords. Existing passwords on Google
Apps are overwritten. This option is
appropriate for managing user passwords
on your LDAP server, but it is less efficient
than the Only changed passwords
option.
•
Only changed passwords: Directory
Sync only synchronizes passwords that
have changed since your previous sync.
This option is recommended if you want to
manage user passwords on your LDAP
server.
Note: If you use this option, you must also
provide a value for the Password
Changed Time Attribute.
Example: Only for new users
80
Release 4.0.2
LDAP Extended Attribute
Setting
Password Attribute
Description
An LDAP attribute that contains each user’s
password. If you set this attribute, your users’
Google Apps passwords will be synchronized
to match their LDAP passwords.
The password field supports string or binary
attributes.
Example: CustomPassword1
Password Timestamp
Attribute
An LDAP attribute that contains a timestamp
indicating the last time a user’s password was
changed. Your LDAP server updates this
attribute whenever a user changes their
password.
Use this field only if you select the Only
changed passwords option for the
Synchronize Passwords field.
This field supports string attributes.
Example: PasswordChangedTime
Configuration
81
LDAP Extended Attribute
Setting
Password Encryption Method
Description
The encryption algorithm that the password
attribute uses.
•
SHA1: Passwords in your LDAP directory
server hashed using SHA1.
•
MD5: Passwords in your LDAP directory
server hashed using MD5.
•
Base64: Passwords in your LDAP
directory server use Base64 encoding.
•
Plaintext: Passwords in your LDAP
directory server are not encrypted.
Directory Sync will read the password
attribute as unencrypted text, then
immediately encrypt the password using
SHA1 encryption and synchronize with
Google Apps.
Note: Directory Sync never saves, logs, or
transmits passwords unencrypted. If
passwords in your LDAP directory are
Base64-encoded or plaintext, Directory
Sync immediately encrypts them with
SHA1 encryption and synchronizes them
with Google Apps. 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
82
Release 4.0.2
LDAP Extended Attribute
Setting
Description
Force new users to change
password
If checked, new users must change 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.
Use this option if you are using temporary or
one-time passwords.
Default password for new
users
Enter a text string that will serve as the default
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!
Generated password length
The length, in characters, of randomly
generated passwords. A password is randomly
generated for a user if their password is not
found on your LDAP server and you have not
specified a default password.
Configuration
83
User Search Rules
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.
This page shows the list of search rules. In a new configuration, this will be an
empty list. To add a search rule, click Add Search Rule.
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.
On the list of Search Rules, you can change existing rules:
•
Reorganize: Click the up arrow or down arrow icon to change the order of
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.
84
Release 4.0.2
Add Search Rule
To add a new search rule, click Add Search Rule and specify the fields in the
dialog box. After specifying the fields, click Apply to submit your changes, or Test
LDAP Query to test the search rule. The fields are as follows:
LDAP User Sync
Setting
Place users in the
following Google
Apps Org Unit
Description
This option only shows if you have Synchronization of
Google Organizations set to “Sync LDAP Org Units” or
“Do not create or delete Google Organizations, but
move users between existing Organizations” in the Org
Units page.
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 “User
Accounts” on page 76.
•
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
Configuration
85
LDAP User Sync
Setting
Suspend these
users in Google
Apps
Description
Suspend all users that match this LDAP user sync rule.
Directory Sync suspends users that already exist in
Google Apps. User data is retained.
Directory Sync 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.
Choose which option to use:
•
Sub-tree: 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
86
Release 4.0.2
LDAP User Sync
Setting
Rule
Description
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 “About LDAP Queries”
on page 41.
Example 1: To match all objects (this may cause load
problems):
objectclass=*
Example 2: To match all human users:
•
For OpenLDAP:
(objectClass=inetOrgPerson)
•
For Active Directory:
(objectClass=person)
•
for Lotus Domino:
(objectClass=dominoPerson)
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
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
Configuration
87
Exclusion rules are based on string values and regular expressions, not LDAP
settings.
Note: To exclude individual users, add a separate rule for each user.
This page shows the list of exclusion filters. In a new configuration, this is an
empty list. To add exclusion filters, click Add Exclusion Rule.
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.
As a recommended safeguard, you can limit how many of your users GADS can
delete or suspend during synchronization. Specify either a percentage or raw
number of your domain’s users in the corresponding fields.
Example LDAP User Exclusion Rules
Listed below are samples of common exclusion rules. Note that the exact text of
these rules will vary based on your needs.
88
Release 4.0.2
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.
•
Match Type: Substring Match
•
Exclude Type: Primary Address
•
Rule: printer
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
•
Exclude Type: Primary Address
•
Rule: atif
Second rule:
•
Match Type: Substring Match or Exact Match
•
Exclude Type: Primary Address
•
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: internaltestX, where X is a number, and all test users are in the same domain.
•
Match Type: Regular Expression
•
Rule: internal-test[0-9]*@example.com
Configuration
89
Add Exclusion Rule
Click Add Exclusion Rule to exclude a user or organization in your LDAP server
from synchronization, and specify the fields in the dialog box. After specifying the
fields, click Apply to submit your changes, or Test LDAP Query to test the search
rule. The fields are as follows:
Exclusion Rule Setting
Description
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.
Match Type
The type of rule to use for the filter.
•
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
[email protected].
•
Substring Match: The address or organization
name must contain the text of the rule as a
substring.
Example: “test” would exclude
[email protected] and
[email protected].
•
Regular Expression: The address or organization
must match the regular expression specified.
Example: internal.*@example.com would exclude
[email protected] and
[email protected].
90
Release 4.0.2
Exclusion Rule Setting
Description
Exclusion 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: maria
•
Substring Match: internal-list
•
Regular Expression: internal.*@example.com
Groups
Set up synchronization for Google Groups for Work in the LDAP Groups page.
Google Groups for Work 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 docs and sites in Google Drive.
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.
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.
Directory Sync will automatically detect groups that users create, and will not
delete or overwrite them.
If a group with the same email address exists in your LDAP directory, Directory
Sync adds new members from Google Apps but doesn’t remove members you
remove from the LDAP directory.
Configuration
91
Group Search Rules
Google Apps Directory Sync can synchronize Google Groups with your LDAP
server’s mailing lists.
This page shows the list of LDAP Group Sync rules. In a new configuration, this is
an empty list. To add mail lists, click Add Search Rule.
In the list of Mail List rules, you can change existing filters as follows:
92
Release 4.0.2
•
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.
Add Group Search Rule (LDAP)
To synchronize one or more mailing lists as Google Groups, click Add Search
Rule and specify the fields in the dialog box. After specifying the fields, click
Apply to submit your changes, or Test LDAP Query to test the search rule.
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 [email protected] 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.
Configuration
93
Specify the following:
LDAP Group Rule
Setting
Description
Scope
Where to apply the mail list rule.
Choose which option to user:
•
Sub-tree: 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 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: Sub-tree
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
“About LDAP Queries” on page 41.
Example: (objectclass=dominoGroup)
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
Group Email
Address Attribute
An LDAP attribute that contains the email address of
the group. This will become the group email address in
Google Apps.
Example: mail
94
Release 4.0.2
LDAP Group Rule
Setting
Description
Group Display Name
Attribute
An LDAP attribute that contains the display name of
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
Attribute
An LDAP attribute that contains the full-text description
of the group. This will become the group description in
Google Apps.
This field is optional.
Example: extendedAttribute6
User Email Address
Attribute
An LDAP attribute that contains users’ email
addresses. This is used to retrieve the email
addresses of group members and owners given their
DN
Example: mail
Dynamic (Querybased) group?
If checked, all mailing lists matching this search rule
are treated as dynamic (query-based) groups, and the
value of the Member Reference Attribute is treated
as the query that specifies the membership of the
group.
Check this box if your search rule is for Exchange
dynamic distribution groups.
Note: If you manually enable DYNAMIC_GROUP_SYNC in
your XML config file but leave out
INDEPENDENT_GROUP_SYNC, make sure your dynamic
group search rule is the first group search rule.
Otherwise, you may encounter issues with group
membership resolution. Such a configuration isn't
recommended; we suggest enabling
INDEPENDENT_GROUP_SYNC in your configuration.
See Advanced GADS Troubleshooting.
Member Reference
Attribute
(Either this field or
Member Literal
Attribute is required.)
If Dynamic (Query-based) group is not checked, this
should be an LDAP attribute that contains the DN of
mailing list members in your LDAP directory server.
Google Apps Directory Sync looks up the email
addresses of these members and adds each member
to the group in Google Apps.
If Dynamic (Query-based) group is checked, this
should be an LDAP attribute that contains the filter that
GADS uses to determine group membership.
Example (non-dynamic): memberUID
Example (dynamic): msExchDynamicDLFilter
Configuration
95
LDAP Group Rule
Setting
Description
Member Literal
Attribute
An attribute that contains the full email address of
mailing list members in your LDAP directory server.
(Either this field or
Member Reference
Attribute is required.)
Google Apps Directory Server adds each member to
the group in Google Apps.
Dynamic group
Base DN attribute
If Dynamic (Query-based) group is checked, this
needs to be an LDAP attribute that contains the base
DN from which the query specified in Member
Reference Attribute is applied.
Example: memberaddress
Example: msExchDynamicDLBaseDN
Owner Reference
Attribute
An attribute that contains the DN of each group’s
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.
This field is optional.
Example: ownerUID
Owner Literal
Attribute
An attribute that contains the full email address of each
group’s owner.
Google Apps Directory Server adds that address as
the group owner in Google Apps.
This field is optional.
Example: owner
96
Release 4.0.2
Add Group Search Rule (Prefix-Suffix)
You may need Directory Sync to add a prefix or suffix to the value your LDAP
server provides for a mailing list’s email address or its members’ email addresses.
Specify any prefixes or suffixes here.
LDAP Group Rule Setting
Description
Group Email Address Prefix
Text to add at the beginning of a mailing list’s
email address when creating the
corresponding group email address.
Example: groups-
Group Email Address Suffix
Text to add at the end of a mailing list’s email
address when creating the corresponding
group email address.
Example: -list
Invalid characters
replacement
If a mailing list name in your LDAP server
contains any spaces or other invalid
characters, they will be replaced with this
character string.
If you leave this blank, Directory Sync removes
spaces and concatenates group names.
Example: underscore (_)
Configuration
97
LDAP Group Rule Setting
Description
Member Name Prefix
Text to add at the beginning of each mailing list
member’s email address when creating the
corresponding group member email address.
Member Name Suffix
Text to add at the end of each mailing list
member’s email address when creating the
corresponding group member email address.
Owner Name Prefix
Text to add at the beginning of each mailing list
owner’s email address when creating the
corresponding group owner email address.
Owner Name Suffix
Text to add at the end of each mailing list
owner’s email address when creating the
corresponding group owner email address.
Group Exclusion Rules
You can exclude particular mailing lists 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:
98
Release 4.0.2
•
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.
Exclusion rules are based on string values and regular expressions, not LDAP
settings.
This page shows the list of exclusion rules. In a new configuration, this will be an
empty list. To add exclusion rules, click the Add Exclusion Rule button at the
bottom of the screen.
In the list of exclusion rules, 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.
As a recommended safeguard, you can limit how many of your groups GADS can
delete during synchronization. Specify either a percentage or raw number of your
domain’s groups in the corresponding field.
Example Group 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
99
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.
•
Match Type: Substring Match
•
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:
•
Match Type: Exact Match
•
Rule: finance-early-statements
Second rule:
•
Match Type: Exact Match
•
Rule: internal-security
Third rule:
•
Match Type: Exact Match
•
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
internal load testing. All the test users follow the same name pattern: internaltestX, where X is a number, and all test users are in the same domain.
100
Release 4.0.2
•
Match Type: Regular Expression
•
Rule: internal-test[0-9]*@example.com
Add Group Exclusion Rule
Click Add Exclusion Rule to prevent an address from being treated as a mailing
list, and specify the following:
Exclusion Rule Setting
Description
Exclude Type
Sets the type of exclusion filter to create:
Match Type
Exclusion Rule
•
Group Name: Do not sync any group that has a
name that matches the rule.
•
Group Address: Do not sync any group that has
an email address that matches the rule.
•
Member Address: Do not sync the membership of
any user whose primary email address matches
this rule from any groups.
The type of rule to use for the filter.
•
Exact Match: The address or organization name
(minus domain name) must match the rule exactly.
•
Substring Match: The address or organization
name must contain the text of the rule as a
substring.
•
Regular Expression: The address or organization
must match the regular expression specified.
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.
User Profiles
Set up synchronization for Google Apps user profiles in the User Profiles page.
User Profiles contain extended information about users, such as phone number
and title.
The 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
101
User Profile Attributes
Specify what attributes Google Apps Directory Sync will use when generating the
LDAP user profiles.
102
Release 4.0.2
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.
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
mobile phone number.
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.
City
LDAP attribute that contains the city of a user’s
primary work address.
Configuration
103
LDAP Profile User Attribute
Description
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.
User Profile Search Rules
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.
104
Release 4.0.2
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 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.
On the list of Search Rules, you can change existing rules:
•
Reorganize: Click the up arrow or down arrow icon to change the order of
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.
Add User Profile Search Rule
To add a new search rule, click Add User Profile Search Rule and specify the
fields in the dialog box. After specifying the fields, click Apply to submit your
changes, or Test LDAP Query to test the search rule. The fields are as follows:
LDAP User Profile Search Rule
Field
Scope
Description
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
Configuration
105
LDAP User Profile Search Rule
Field
Rule
Description
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 “About LDAP Queries” on
page 41.
Example 1: To match all objects (this may
cause load problems):
objectclass=*
Example 2: To match all human users:
•
For OpenLDAP:
(objectClass=inetOrgPerson)
•
For Active Directory:
(objectClass=person)
•
for Lotus Domino:
(objectClass=dominoPerson)
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
106
Release 4.0.2
User Profile Exclusion Rules
If you have any existing user profile information in Google Apps that you do not
want to synchronize, specify it here.
This page shows the list of exclusion filters. In a new configuration, this will be an
empty list. To add exclusion filters, click Add Exclusion Rule.
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 User Profile Exclusion Rules
Listed below are samples of common exclusion rules. Note that the exact text of
these rules will vary based on your needs.
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.
•
Match Type: Substring Match
•
Rule: printer
Configuration
107
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: Exact Match
•
Rule: [email protected]
Second rule:
•
Match Type: Exact Match
•
Rule: [email protected]
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: internaltestX, where X is a number, and all test users are in the same domain.
•
Match Type: Regular Expression
•
Rule: internal-test[0-9]*@example.com
Add Exclusion Rule
Click Add Exclusion Rule to exclude a user or organization in your LDAP server
from synchronization.
108
Release 4.0.2
Specify the following:
Exclusion Rule Setting
Description
Match Type
The type of rule to use for the filter.
•
Exact Match: The address must match the rule
exactly.
Example: [email protected] would exclude only
the user [email protected].
•
Substring Match: The address or organization
name must contain the text of the rule as a
substring.
Example: “test” would exclude
[email protected] and
[email protected].
•
Regular Expression: The address or organization
must match the regular expression specified.
Example: internal.*@example.com would exclude
[email protected] and
[email protected].
Exclusion 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: [email protected]
•
Substring Match: listinternal
•
Regular Expression: internal.*@example.com
Shared Contacts
Set up synchronization for Google Apps shared contacts in the LDAP Shared
Contacts 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.
Configuration
109
You can see Shared Contacts in Google Apps by going to your Inbox and clicking
the Contacts link.
The 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:
110
Release 4.0.2
•
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, even those external to your domain,
appear in the 'Directory' label when users navigate to Contacts in the Gmail
web interface or contacts.google.com..
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.
Shared Contact Attributes
Specify what attributes Google Apps Directory Sync will use when generating the
LDAP shared contacts.
Configuration
111
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
The LDAP attribute or attributes that contain
the contact’s full name.
Example: [prefix] - [givenName] [sn] [suffix]
112
Release 4.0.2
Job title
LDAP attribute that contains a contact’s job
title. This field can be comprised of multiple
concatenated fields, using the same syntax as
the Full Name attribute above.
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. This field can be comprised of
multiple concatenated fields, using the same
syntax as the Full Name attribute above.
Office location
LDAP attribute that contains a contact’s office
location. This field can be comprised of
multiple concatenated fields, using the same
syntax as the Full Name attribute above.
Work email address
LDAP attribute that contains a contact’s email
address
Employee ids
LDAP attribute that contains a contact’s
employee ID number.
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 numbers
LDAP attribute that contains a contact’s fax
number.
LDAP Shared Contact Attribute
Description
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
mobile phone number.
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.
Shared Contact Search Rules
This shows a list of rules used when determining which shared contacts to import.
Configuration
113
By default, shared contacts are 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.
This page shows the list of search rules. In a new configuration, this is an empty
list. To add a search rule, click Add Search Rule.
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.
On the list of Search Rules, you can change existing rules:
•
Reorganize: Click the up arrow or down arrow icon to change the order of
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.
Add Shared Contact Search Rule
To add a new search rule, click Add Shared Contact Search Rule.
Specify the following:
114
Release 4.0.2
LDAP Shared Contacts Search
Rule Field
Scope
Description
This determines where in the LDAP directory
this rule applies.
Choose which option to use:
•
Sub-tree: All objects matched by the
search, and anything under those objects,
recursively. Sub-tree 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: Sub-tree
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 “About LDAP
Queries” on page 41.
Example 1: To match all contacts:
(objectclass=contact)
Example 2: To match all human users:
•
For OpenLDAP:
(objectClass=inetOrgPerson)
•
For Active Directory:
(objectClass=person)
•
for Lotus Domino:
(objectClass=dominoPerson)
Configuration
115
LDAP Shared Contacts Search
Rule Field
Base DN
Description
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
Shared Contact Exclusion Rules
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.
Exclusion rules are based on string values and regular expressions, not LDAP
settings.
Note: To exclude individual contacts, add a separate rule for each contact.
116
Release 4.0.2
This page shows the list of exclusion filters. In a new configuration, this will be an
empty list. To add exclusion filters, click Add Exclusion Rule.
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.
As a recommended safeguard, you can limit how many of your shared contacts
GADS can delete during synchronization. Specify either a percentage or raw
number of your domain’s shared contacts in the corresponding field.
Example Shared Contact Exclusion Rules
Listed below are samples of common exclusion rules. Note that the exact text of
these rules will vary based on your needs.
Sample Exact Match: Private Contacts
Two contacts have opted out of Google Apps and should not be synchronized.
Add a separate rule for each special user.
First rule:
•
Match Type: Exact Match
•
Rule: [email protected]
Second rule:
•
Match Type: Exact Match
•
Rule: [email protected]
Sample Regular Expression Match: Test Contacts
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: internaltestX, where X is a number, and all test users are in the same domain.
•
Match Type: Regular Expression
•
Rule: internal-test[0-9]*@example.com
Configuration
117
Add Exclusion Rule
Click Add Exclusion Rule to exclude a shared contact in your LDAP server from
synchronization.
Specify the following:
Exclusion Rule Setting
Description
Match Type
The type of rule to use for the filter.
•
Exact Match: The address must match the rule
exactly.
Example: [email protected] would exclude only
the user [email protected].
•
Substring Match: The address or organization
name must contain the text of the rule as a
substring.
Example: “test” would exclude
[email protected] and
[email protected].
•
Regular Expression: The address or organization
must match the regular expression specified.
Example: internal.*@example.com would exclude
[email protected] and
[email protected].
118
Release 4.0.2
Exclusion Rule Setting
Description
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: [email protected]
•
Substring Match: listinternal
•
Regular Expression: internal.*@example.com
LDAP Calendar Resources
This section configures how Google Apps Directory Sync generates your LDAP
calendar resources list for comparison. You may need to collect information from
your LDAP directory server before you can enter details in this section.
Configuration
119
Calendar Resource Attributes
Specify the attributes you want Google Apps Directory Sync to use when
generating the LDAP calendar resources list.
LDAP User Attribute
Setting
Resource Id
Description
The LDAP attribute or attributes that contain the ID of
the calendar resource.
This is a field managed on your LDAP system, which
may be a custom attribute. This field must be unique.
Important: Calendar Resources does not sync an
LDAP attribute which contains spaces or characters
such as the at sign (@) or colon (:).
For more information on this calendar resource
naming, see the Google Code site article Developing
a naming strategy for your calendar resources.
Display Name
(optional)
The LDAP attribute or attributes that contain the
domain name for the calendar resource.
Example: [city]-[building]-[floor]-Boardroom[roomnumber]
Important: Calendar Resources does not sync an
LDAP attribute which contains spaces or characters
such as the at sign (@) or colon (:).
For more information on this calendar resource
naming, see the Google Code site article Developing
a naming strategy for your calendar resources.
Description
(optional)
The LDAP attribute or attributes that contain a
description of the calendar resource.
Example: [description]
Resource Type
(optional)
The LDAP attribute or attributes that contain the
calendar resource type.
Important: Calendar Resources does not sync an
LDAP attribute which contains spaces or characters
such as the at sign (@) or colon (:).
Mail
(optional)
120
Release 4.0.2
The LDAP attribute or attributes that contain the
calendar resource email address. This attribute is only
for use with the Export Calendar resource mapping
CSV export option. GADS does not set the email
address of Google Calendar resources.
LDAP User Attribute
Setting
Export Calendar
resource mapping
(optional)
Description
Generates a CSV file listing LDAP calendar resources
and their Google Apps equivalents. Use the CSV file
with Google Apps Migration for Microsoft Exchange to
migrate the contents of your Microsoft Exchange
calendar resources to the appropriate Google Apps
calendar resources.
Note: Calendar resource attributes use a different syntax than other Directory
Sync attributes.
All attributes in the LDAP Calendar Resources Attributes page can include fixed
strings and multiple LDAP attributes. Each LDAP attribute should be marked with
square brackets.
For instance, if you wanted to use the LDAP attributes city, building, floor,
and roomnumber from your LDAP directory, and combine them into a single display
name, you might use the following setting for Display Name:
[city]-[building]-[floor]-Boardroom-[roomnumber]
All LDAP attributes should be inside square brackets. All fixed text should be
outside the square brackets, in the format in which it should appear in your
Google Apps calendar resources.
Calendar Resource Search Rules
This shows a list of rules used when generating the LDAP calendar resource list.
Configuration
121
By default, all calendar resources that match these search rules will be added to
the Google Apps calendar resources, and all calendar resources 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 Add Search Rule.
On the list of Search Rules, you can change existing rules:
•
Reorganize: Click the up arrow or down arrow icon to change the order of
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.
Add Search Rule
To add a new search rule, click Add Search Rule and specify the fields in the
dialog box. After specifying the fields, click Apply to submit your changes, or Test
LDAP Query to test the search rule. The fields are as follows:
LDAP User Sync
Setting
Scope
Description
This determines where in the LDAP directory this rule
applies.
Choose which option to use:
•
Sub-tree: 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
122
Release 4.0.2
LDAP User Sync
Setting
Rule
Description
The search rule for calendar resources 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
“About LDAP Queries” on page 41.
Example 1: To match all objects (this may cause load
problems):
objectclass=*
Example 2: To match all users:
•
For OpenLDAP:
(objectClass=inetOrgPerson)
•
For Active Directory:
(objectClass=person)
•
for Lotus Domino:
(objectClass=dominoPerson)
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. If your calendar resources are
sorted in a particular OU, this may be a helpful field to
use. If you want this rule to use a different Base DN
than the default, specify an alternate base DN.
Example:
ou=Rooms,ou=melbourne,dc=ad,dc=example,dc=com
Calendar Resource Exclusion Rules
If you have any entities on your LDAP directory server that match your calendar
resource search rules but should not be added to Google Apps as calendar
resources, add an LDAP user exclusion rule.
Some examples of reasons for LDAP user exclusion rules:
•
User accounts that seem to match calendar resource query patterns
•
Printers, computers, and other non-calendar resources
•
Test resources on your LDAP directory server
•
Obsolete calendar resources that are still listed in your LDAP directory
Configuration
123
Exclusion rules are based on string values and regular expressions, not LDAP
settings.
Note: To exclude individual calendar resources, add a separate rule for each user.
This page shows the list of exclusion filters. In a new configuration, this will be an
empty list. To add exclusion filters, click Add Exclusion Rule.
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.
As a recommended safeguard, you can limit how many of your calendar
resources GADS can delete during synchronization. Specify either a percentage
or raw number of your domain’s calendar resources in the corresponding field.
Example Calendar Exclusion Rules
Listed below are samples of common exclusion rules. Note that the exact text of
these rules will vary based on your needs.
124
Release 4.0.2
Sample Substring Match: Printers
In this example, printers are listed as LDAP resources and would match the LDAP
query given. However, the printers all have the word “printer” in the name. The
rule looks for that substring.
•
Match Type: Substring Match
•
Exclude Type: Calendar Resource Id
•
Rule: printer
Sample Exact Match: Opt-Out Users
Two conference rooms have been converted into offices and should not be
imported as Google Apps calendar resources.
Add a separate rule for each special user.
First rule:
•
Match Type: Substring Match or Exact Match
•
Exclude Type: Calendar Resource Display Name
•
Rule: ConferenceRoom-BlueSkyMontana
Second rule:
•
Match Type: Substring Match or Exact Match
•
Exclude Type: Calendar Resource Display Name
•
Rule: ConferenceRoom-BigPlains
Sample Regular Expression Match: Test Users
About five hundred test calendar resources are listed in LDAP, but they are only
used for internal load testing. All the test resources follow the same name pattern:
internal-testX, where X is a number, and all test users are in the same domain.
•
Match Type: Regular Expression
•
Exclude Type: Calendar Resource Id
•
Rule: internal-test[0-9]*@example.com
Configuration
125
Add Exclusion Rule
Click the Add Exclusion Rule at the bottom of the page to exclude a user or
organization in your LDAP server from synchronization.
Specify the following:
Exclusion Rule Setting
Description
Exclude Type
What kind of LDAP data to exclude.
•
Calendar Resource Id: Directory Sync will
exclude calendar resources where the Calendar
Resource Id attribute specified in LDAP Calendar
Resources Attributes matches this pattern. The
interface displays this choice as
CALENDAR_RESOURCE_ID.
•
Calendar Resource Display Name: Directory
Sync will exclude calendar resources where the
Calendar Resource Display Name attribute
specified in LDAP Calendar Resources Attributes
matches this pattern. The interface displays this
choice as
CALENDAR_RESOURCE_DISPLAY_NAME
If you want to exclude both resource IDs and resource
display names create two exclusion rules.
126
Release 4.0.2
Exclusion Rule Setting
Description
Match Type
The type of rule to use for the filter.
•
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
[email protected].
•
Substring Match: The address or organization
name must contain the text of the rule as a
substring.
Example: “test” would exclude
[email protected] and
[email protected].
•
Regular Expression: The address or organization
must match the regular expression specified.
Example: internal.*@example.com would exclude
[email protected] and
[email protected].
Rule
The match string or regular expression for the
exclusion rule. Behavior of this field depends on the
Match Type you choose.
Calendar Resource Ids or Display Names 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: NewYork-NYC-23-Conference-2
•
Substring Match: internal-list
•
Regular Expression: internal.*@example.com
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.
Configuration
127
Consider adding a notification to send mail to your own address, and possibly the
addresses of any concerned parties in your company.
Specify the following:
Notifications Setting
Description
SMTP Relay Host
The SMTP mail server to use for notifications.
Directory Sync uses this mail server as a relay host.
Example: 127.0.0.1 to run the mail server on the
same machine.
Example: smtp.gmail.com
Use SMTP with TLS
Check this box to use SMTP with TLS.
User Name
If the SMTP server you specify requires SMTP
authentication, enter the user name to use here.
(if needed)
Example: [email protected]
Password
(if needed)
If the SMTP server you specify requires SMTP
authentication, enter the Password to use here.
Example: swordfish
Passwords are stored in the configuration file in an
encrypted format.
128
Release 4.0.2
Notifications Setting
Description
From address
Enter the “From:” address for the notification mail.
Recipients will see this address as the notification
sender. For instance, you might use your own email
address.
Example: [email protected]
To addresses
(recipients)
Notifications will be sent to all addresses on this list.
Enter any valid email address on any domain. Enter
each recipient email address individually, then click the
Add button.
Depending on your mail server settings, Directory Sync
may be unable to send mail to external email
addresses. Run a test notification to confirm that mail
is sent properly.
Example: [email protected]
Do not include in
notifications
(Optional)
You can limit the information sent in notifications by
checking any of the three checkboxes. All checkboxes
are 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.
Configuration
129
Logging Settings
You can specify the file name and level of detail of logging for Google Apps
Directory Sync.
Specify the following:
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.
130
Release 4.0.2
•
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.
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
Sync
After you enter configuration information, use this section to verify and test your
GADS 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 141.
Configuration
131
Validation Results
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.
After you’ve completed all required fields, you will be able to use the Simulate
Sync button to simulate a synchronization.
After you complete a test synchronization, results from the Google Apps server
are cached. To flush the remote cache for the next synchronization, check the
Clear Cache checkbox.
When you’re ready, click Simulate Sync.
132
Release 4.0.2
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 135 for more.
Review the log file generated by the test sync 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 “Release 4.0.2 Troubleshooting” on page 141.
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 135.
Configuration
133
134
Release 4.0.2
Chapter 7
Synchronization
Chapter 7
About Synchronization
Run the synchronization command to push your LDAP directory server user
information to Google Apps.
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 49.
Most administrators run their first synchronization manually to test the process,
import an initial set of users, and confirm the changes. After initial synchronization
from the Configuration Manager, you can set up automatic scheduling for future
synchronization.
Note: GADS caches Google Apps data for a maximum of eight days. If the size of
the cached data is too small to impact synchronization speed, GADS clears the
cache even more frequently to keep the data fresh.
Synchronizing from the Configuration Manager
You can perform a manual synchronization from the Sync section of the
Configuration Manager by clicking Sync & apply changes. Use this feature to
perform a new sync after setting up or modifying your configuration. After you’re
done making configuration changes, you should automate your sync process by
instead using command line synchronization.
Command Line Synchronization
GADS 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.
The command line to use for all platforms is
Synchronization
135
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, check
to be sure that a sync is not already running, connect to both servers, generate a
list of changes, and apply those changes:
sync-cmd -a -o -c [filename]
Replace [filename] with the name of the XML file you created in the
Configuration Manager.
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 GADS is installed.
Option
Values
-o,--oneinstance
Restrict to one instance per config file. Only
valid with -a.
-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.
136
Release 4.0.2
Option
Values
-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.
-s, --sharedcontacts
Do not analyze shared contacts.
Note: Do not use this option. It is intended for
other versions of Directory Sync, 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, scheduled synchronization runs every one to six hours. 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 Directory Sync multiple times 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
Directory Sync is installed. In Microsoft Windows, use Scheduled Tasks. In Linux,
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.
Important: When scheduling synchronization, be sure to schedule regular use of
the checkforupdate.exe command as well, so that you can regularly check for
new versions of Google Apps Directory Sync.
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.
Synchronization
137
To schedule a task
1. In Control Panel, open Scheduled Tasks.
2. Double-click Add Scheduled Task.
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 Directory Sync is
installed.
•
The frequency of the task depends on your synchronization needs. A
large company with many users changing frequently may need to run
Directory Sync multiple times daily, while a small company with few
changes may not need to run the utility more than once a week.
•
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 Directory Sync 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: cron
In a Linux environments, schedule synchronization using crontab.
Note: These steps apply to most common Linux configurations. Linux is a third-
party product 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 Directory Sync was installed.Replace
[filename] with the name of the XML file you created in the Configuration
Manager.
3. Save the crontab file and exit your text editor.
138
Release 4.0.2
Monitoring
After you have set up scheduled synchronization, make a policy of regularly
checking the status of your synchronizations.
Check Notification messages on a regular basis for signs of any problems.
Notifications will be sent to an address that you specify. For more information
about Notifications, see “Notifications” on page 127.
When looking through notifications logs, look for messages that indicate that
users were synchronized. If you expect that a particular user will be synchronized
and the user isn’t, check the notifications for information.
Also, check for new updates regularly. You can use the command
checkforupdate.exe in the same directory as sync-cmd.exe, to check online for
new versions of Google Apps Directory Sync.
Synchronization
139
140
Release 4.0.2
Chapter 8
Release 4.0.2 Troubleshooting
Chapter 8
About Troubleshooting
This chapter covers information about how to troubleshoot problems that may occur with Google Apps
Directory Sync (GADS).
Troubleshooting information includes information about common issues, system tests and researching
issues.
For information about LDAP queries, see “About LDAP Queries” on page 41.
Troubleshooting With Log Files
If you encounter problems with GADS, you should double-check your configuration settings and submit the
generated logs to the Google Apps Directory Sync Log Analyzer (https://toolbox.googleapps.com/apps/
loganalyzer).
Most issues can be identified within a few moments of submission.
Common Issues
The following describes common issues and questions related to GADS.
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.
Release 4.0.2 Troubleshooting
141
What port numbers should be used in GADS when connecting to Global Catalog server?
By default, GADS 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
GADS to connect to a Global Catalog server with the standard Global Catalog server port 3268.
User Sync Errors
Error Message: You are not authorized to access this API
Confirm that you are using Google Apps for Work, Partners, Government, or Education.
Enable APIs on your Google Apps domain, as described in “Enable APIs” on page 38.
Error Message: Domain User Limit Exceeded
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.
Group Sync Errors
Groups with over 1500 members in my Active Directory server members aren’t syncing correctly.
Make sure you have selected MS Active Directory in the Server Type field of the LDAP Configuration
section.
Synchronization Rules
Users are getting recreated on every sync
This happens when the LDAP attribute configured as the Group Name Attribute does not contain a full
email address.
To resolve this issue, check your Group Search rules and make sure that GADS uses a full email address
for the group names. Use one of the following methods:
•
Set the Group Name Attribute to a different LDAP attribute that specifies a full email address for each
group, such as mail.
•
Enable “Replace domain named in LDAP email addresses (of users and groups) with this domain
name” in Google Apps Settings, so that your Group Name Attribute matches the Google-side group
names.
•
Add the domain name to the group name by specifying a Group Name Suffix in your Group Search
Rule.
142
Release 4.0.2
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.
Connections and Security
What specific ports and URLs need to be accessible for Directory Sync to function?
Please note that this information can change over time. For the latest information, check for updates.
Directory Sync currently accesses the following URLs:
Purpose
URL
Port Number
Authentication
https://www.google.com
https://www.googleapis.com
443
API access
https://apps-apis.google.com,
https://www.googleapis.com
443
Certificate Revocation
List Processing
http://crl.geotrust.com/crls/gtglobal.crl
80
http://pki.google.com/GIAG2.crl
http://g.symcb.com/crls/gtglobal.crl
Online Certificate Status
Protocol
http://g.symcd.com
Certificate Authority
http://crl.verisign.net
80
http://clients1.google.com/ocsp
80
For information on how to create an up-to-date list of Google IP addresses, see the help center article,
Google IP address ranges.
If GADS is unable to connect to the revocation list providers, you may see the following error in your GADS
log file:
PKIX path validation failed: java.security.cert.CertPathValidatorException: revocation
status check failed: no CRL found
Release 4.0.2 Troubleshooting
143
The proxy environment requires a password challenge for external web access.
GADS can use a proxy server but cannot respond to password challenges. To run synchronization, you will
need to change your network setup to allow Directory Sync to connect without a password challenge, or
without a proxy server.
I cannot simulate a synchronization because the notifications server is 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?
GADS 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 “Step One: Install LDAP Browser” on page 24.
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.
144
Release 4.0.2
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.
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 GADS, 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 Directory Sync is installed. Support will often
request that you capture log file information with your log level set to TRACE to collect more
information.
•
The version number of Directory Sync 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 Directory Sync is installed.
•
The brand and version of the LDAP directory server you're using.
•
The operating system on the machine where Directory Sync 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 Google Apps for Work,
Education, or Government customer, find your Support PIN. Information on how to collect this information
is available in the help center here:
http://support.google.com/a/bin/answer.py?answer=60233
Release 4.0.2 Troubleshooting
145
146
Release 4.0.2