prueba ricardo pelaez by Ricardo Pelaez

Google Apps Directory Sync Administration Guide Release 1.6.10

Google, Inc. 1600 Amphitheatre Parkway Mountain View, CA 94043 www.google.com

Part number: GADS_1.6.10_13 October 27, 2009 © Copyright 2009 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

Release 1.6.10

Copyright 2004-2007 The Apache Software Foundation 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

Release 1.6.10

Contents

Release 1.6.10

About This Guide

What This Guide Contains The Google Apps Directory Sync Administration Guide provides information about: •

Google Apps Directory Sync features.

•

Basic steps for installing the directory sync utility on your server.

•

Configuration for the directory sync utility.

•

Synchronizing users, groups, and shared contacts.

•

Troubleshooting the directory sync utility.

This guide is intended for administrators who are already familiar with Google Apps and with LDAP directory servers.

Related Documentation For additional information about Google Apps and about related products, refer to the following documents. Document

Description

Directory Sync Admin Help 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.

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. If you have comments about this guide, please send an email message to: postini-doc_comments@google.com

Please specify in your email message the section to which your comment applies. If you want to receive a response to your comments, ensure that you include your name and contact information.

Release 1.6.10

Chapter 2

Introduction

Chapter 2

About Google Apps Directory Sync Google Apps Directory Sync is a utility that adds and deletes your users, groups, and shared contacts in Google Apps to match your LDAP directory server. When you synchronize, any changes on your LDAP server are reflected in Google Apps. The directory sync utility runs on a server machine in your network environment. You can use any machine that is able to connect to your LDAP server and to Google Apps. Use Google Apps Directory Sync to synchronize information so that your Google Apps users, groups, and shared contacts are automatically kept up to date with your LDAP directory server.

Introduction

Features and Benefits Google Apps Directory Sync offers the following features and benefits: •

Updates your Google Apps user and groups to match your LDAP data.

•

A local on-site utility that runs in your server environment. No machine outside your perimeter will access your LDAP directory server data.

•

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

•

All needed components included in installation.

•

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

•

Advanced LDAP query capabilities to handle irregular LDAP environments.

•

Extensive tests and simulations to ensure correct synchronization.

System Requirements Using Google Apps Directory Sync requires the following: •

Release 1.6.10

A Google Apps domain running Premier Edition, Partner Edition or Education Edition. Google Apps Directory Sync is not available with Standard Edition or Team Edition of Google Apps.

Note: Google Apps Directory Sync only synchronizes primary domains, not

domain aliases. •

An administrator account on your Google Apps domain.

•

User APIs enabled on your Google Apps domain. For steps on how to do this, see “Enable APIs” on page 27.

•

A server on which to install Google Apps Directory Sync, running Microsoft Windows (tested on XP and Vista), Linux or Solaris (version 8+, no support for x86).

•

At least 5GB of disk space for log files and data. If you are running with DEBUG or INFO level of logging, you may need more free space than this for additional log data.

•

At least 256MB of free RAM. At least 1GB of free RAM is suggested if you have less than 10,000 users, or 2GB of free RAM if you have more than 10,000 users. For very large organizations (over 250,000) further tuning may be needed.

•

An LDAP server with user information which is accessible to the directory sync utility. All versions of the LDAP protocol are supported.

•

Network access to your LDAP server. You do not need to run the directory sync utility on your LDAP server.

•

Read and execute administrative access over the appropriate OU structure of the LDAP server.

•

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

•

A mail server able to accept and relay notifications from the directory sync utility.

Comparison with Google Apps Directory Sync for Email Security Google Apps Directory Sync is a utility that synchronizes your LDAP directory server with Google Apps, and lets you control users for applications like Gmail, Google Docs and Google Spreadsheet for your domain. There is another utility with a similar name, Google Apps Directory Sync for Email Security. This utility is used with Google Message Security, powered by Postini. Despite the similar names, the utilities are completely separate. Google Apps Directory Sync cannot be used with the message security service, and Google Apps Directory Sync for Email Security cannot be used with Google Apps for your domain. You can use both utilities in the same environment. To find out more about Google Apps Directory Sync for Email Security, see the Google Apps Directory Sync for Message Security web site here: http://www.postini.com/dir_sync

Introduction

Architecture Google Apps Directory Sync runs on your server and updates Google Apps to match your LDAP server. The directory sync utility never updates or changes your LDAP server. The following steps describe how the data flow of directory sync works. 1. The directory sync utility connects to your LDAP server and generates a list of users, groups, and shared contacts on your directory. You can set up rules to specify how this list is generated.

2. The directory sync utility connects to Google Apps and generates a list of users, groups, and shared contacts in Google Apps. You can set up rules to specify how this list is generated.

Release 1.6.10

3. The directory sync utility compares these lists, and generates a list of changes.

4. The directory sync utility then updates Google Apps to match your LDAP server settings.

Introduction

Utility Overview The directory sync utility includes several components, designed to work together. These components are:

Release 1.6.10

•

Configuration Manager - Use this graphical UI to configure how the directory sync utility will connect to Google Apps and to your LDAP server. You can also create rules for user lists, search queries, organization mapping, aliases, distribution lists and exceptions. For more information, see “Configuration” on page 31.

•

XML Configuration File - Save configuration information from Configuration Manager in an XML file. Use this file during synchronization.

•

Synchronization Command Line - Use the command-line utility sync-cmd to perform actual synchronization. This utility uses settings in your XML configuration file to connect to Google Apps and your LDAP server, and updates your users and aliases in Google Apps. For more information, see “Synchronization” on page 93.

•

Scheduling - Once you have used sync-cmd successfully, use your operating system’s scheduling functionality to schedule future synchronization. Depending on the server you use, this might be a cron job, a Windows Scheduled Service utility, or any other scheduling tool. For more information, see “Synchronization” on page 93.

Chapter 3

Preparation and Planning

Chapter 3

About Preparation Before you install Google Apps Directory Sync and configure synchronization, you should plan how you will synchronize your LDAP structure with Google Apps. Many steps in the configuration and synchronization process assume you already have available key information about your LDAP directory server, mail server, and Google Apps domain. This chapter includes a checklist of information you’ll need before you begin, strategy tips, LDAP browser information, and some sample LDAP queries. For information on system requirements, see “System Requirements” on page 10.

Overview You can expect the following steps when configuring a typical setup for Google Apps Directory Sync. 1. Identify your LDAP resources, including LDAP servers and expert administrators. 2. Plan which users, aliases, and groups you want to synchronize with Google Apps. Note: You may need to purchase additional licenses in Google Apps if you add users above your current number of licenses.

3. Collect required information about your LDAP server and your Google Apps domain. You may need to download and set up an LDAP Browser to do this. For links to LDAP browsers, see “Useful LDAP Tools” on page 16. 4. Make any necessary changes to clean up extraneous or problematic data in your LDAP server. 5. Install the directory sync utility. For information about installation prerequisites, see “System Requirements” on page 10.

Preparation and Planning

6. Run Configuration Manager (part of Google Apps Directory Sync) to configure synchronization. 7. In Configuration Manager, simulate a synchronization and review the results. 8. If needed, revise your configuration in Configuration Manager based on the simulation. This could take several revisions for complex environments. 9. When the simulation is successful, save your final copy of the configuration file and exit Configuration Manager. 10. At the command line, run a synchronization in preview mode with the configuration file you created. Check the results. 11. At the command line, run a manual synchronization to update Google Apps. The first synchronization, which imports all information, is likely to take much longer than later synchronizations. 12. Using your serverâ&#x20AC;&#x2122;s scheduling tools, set up automatic scheduled synchronization.

Useful LDAP Tools By default, most LDAP directory servers do not include a way to view or modify your LDAP structure directly. To collect information about your LDAP structure, download and install an LDAP browser. Two such browsers are listed below. Note that these are third-party browsers, and this document does not include instructions or support on the use of an LDAP browser.

Softerra LDAP Administrator To download Softerra LDAP Administrator, go to: http://www.ldapbrowser.com

JXplorer To download the JXplorer Java Ldap Browser, go to: http://www.jxplorer.org

Planning Your Synchronization Strategy Plan your synchronization strategy before you start configuring Google Apps Directory Sync. Gathering information about your LDAP directory server and data beforehand helps ensure a smoother and easier synchronization. When planning your synchronization strategy, consider the following factors.

Release 1.6.10

LDAP Data Evaluation and Cleanup Use an LDAP browser to examine your directory server data before you install Google Apps Directory Sync or begin synchronizing. For more information on downloading an LDAP browser, see “Useful LDAP Tools” on page 16. You may find, while preparing for synchronization, that you have unexpected or non-standard data in your LDAP directory server. It is always better to find and address this before you begin synchronizing. 1. If you have the ability to modify or format your LDAP directory server, consider cleaning up your LDAP server for easier synchronization. Look through your data, and consider any data you may want to alter. 2. Check your LDAP directory server to find out which attributes contain the data you need. In some cases, this data may include spaces. Google Apps stores group names as email addresses, which cannot contain spaces, so note if any of your group names require cleanup.

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

Concept in LDAP

Corresponding Concept in Google Apps

Users

Aliases

Nicknames

Mailing Lists

Groups (all groups are added as Public groups)

Preparation and Planning

Decisions You’ll Need To Make Before you install Google Apps Directory Sync, review your LDAP structure and consider the following decisions you’ll need to make.

Release 1.6.10

•

Which users do you want to synchronize? Look through your whole set of users with an LDAP browser. You may have internal-only users, or special users that should not have external email (such as conference rooms). You may also decide to start by synchronizing only a small trial group of users. Construct an LDAP query for the users you want to synchronize.

•

Do you want to use the same domain or a pilot domain? If you specify another domain in Configuration Manager, you can import a full list of users into a different domain. You can use this method to test out Google Apps with a trial domain that is different from the domain in your LDAP server. For more information on pilot domains, see “Pilot Domain” on page 22.

•

What LDAP attribute contains a user’s mail address? In many cases, this will be the mail attribute. Use an LDAP browser to confirm the LDAP attribute you want to use for mail addresses.

•

What LDAP attribute(s) contain a user’s aliases? You can synchronize one or more attributes for aliases in your LDAP Server into Google Apps nicknames. Use an LDAP browser to confirm the LDAP attribute you want to use. Be sure that the attribute contains only an email address, and not other data such as a phone number.

•

Do you want to import user names? You can use Google Apps Directory Sync to import the full names of your users into Google Apps. If you want to do this, find the LDAP attribute(s) that contains this information. User names are often stored in two attributes: one for the first name and one for the last name. If you do not have an LDAP attribute with the appropriate information, you can skip this step.

•

Do you want to import passwords? You can also use Google Apps Directory Sync to import passwords from your LDAP directory server into Google Apps. The password field must be a string, not a sequence of bytes. The string is the hex encoding of the password, plaintext or encrypted. Changes on your LDAP directory server will not take effect on Google Apps until you synchronize. If you import passwords, future scheduled syncs will overwrite any changes your users make in Google Apps. If you do not set up password synchronization, Google Apps Directory Sync will create accounts without a usable password.

Note: For Active Directory and Lotus Notes, the default password field is userPassword. This field is a binary and cannot be used. Alternately, you can

set up Single Sign-On (SSO) and leave password synchronization off. After you set up Single Sign-On, you will not need to synchronize passwords. For more information about SSO, see Single Sign-On in Google Apps Admin Help. If you need to update passwords automatically, the best way to import a password might be to set up an application or utility to connect with the Provisioning API to synchronize passwords. •

What mailing lists do you want to import? Mailing lists on your LDAP directory server will be imported as groups in Google Apps. You may not want to import all mailing lists, since some lists may be internal lists, or company resources such as rooms or printers, or may contain unusable data.

•

What LDAP attribute contains mailing list members? Find out what attribute lists the members of your mailing lists. This is often the member attribute or the mailAddress attribute, but your LDAP directory server may be different. If this attribute is also used for other data, you may need to use another attribute or to clean up your LDAP directory server. If this field contains any spaces, choose a substitution character to replace spaces, since Google Apps mailing addresses cannot contain spaces.

•

Is the LDAP attribute for mailing list members a literal email address, or a user DN reference? Some mailing list attributes describe members by email address (literal), and some describe members by a Distinguished Name (reference). Google Apps Directory Sync can work with either, but you’ll need to know which you’re using beforehand.

•

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

•

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

Preparation and Planning

Important: Shared Contacts do not show immediately. After you synchronize

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

Do you want to replace domain names? By default, all synchronized users will have their domains changed to match the domain name you are using in Google Apps. This can be very helpful if you are running a trial using a different domain name. If all your users in your LDAP directory server have the same domain name as your Google Apps domain, it doesn’t matter whether you replace domain names or not.

•

Do you want to delete users who are not in your LDAP directory server, or just suspend them? By default, users not found on your LDAP directory server will be deleted. If you are worried about losing user data, you can set the directory sync utility to suspend users instead of deleting them. This allows for data recovery if users are later recovered.

•

Do you want to delete suspended users, or leave them alone? By default, the directory sync utility will ignore suspended users. You can instead set directory sync to delete any suspended users that are not found in your LDAP directory server query. Note: You cannot use this setting if you set directory sync to suspend users in LDAP directory server instead of deleting them.

•

Are there any exceptions on your LDAP directory server that you don’t want to synchronize? Your LDAP directory server may contain users or groups that you don’t want to synchronize with Google Apps. This could include internal users, resources like printers or conference rooms, archived or deleted users, test accounts, or other entries that belong in your LDAP directory server but not in Google Apps. Find out which users and groups you’d like to exclude, and look for any common pattern that may simplify exception rules.

•

Are there any exceptions on your Google Apps domain that you don’t want to synchronize? Your Google Apps account may have users or groups that you don’t want to synchronize with LDAP directory server. This could include new users not listed in your LDAP directory server, pilot test accounts, shared Google Apps accounts, or other entries that belong in your Google Apps account but not your LDAP directory server. Find out which users and groups you’d like to exclude, and look for any common pattern that may simplify exception rules. WARNING: Currently, there is no mechanism to add exclusion rules for shared contacts or user profiles in Google Apps Directory Sync. If you are synchronizing user profiles or shared contacts, check your synchronization tests carefully.

Checklist: Before You Begin Before you configure synchronization, gather the information you need from Google Apps, as well as your own LDAP server and mail server.

Release 1.6.10

Each item on the checklist is detailed below: •

Google Apps Directory Sync Domain: Before you configure synchronization, set up your domain in Google Apps. Note: The directory sync utility does not create a domain for you, so you will

need to add it beforehand. Collect the exact domain name from the Google Apps Control Panel. Note that you can only synchronize a primary domain, not a domain alias.

•

Google Apps Administrator: Note the administrator username and password for an administrator in Google Apps.

•

LDAP Structure Information: Gather information about your LDAP directory server. You will need to know what OUs contain users you want to sync and which LDAP attributes contain important information. To collect this information, use an LDAP browser. For more information, see “Useful LDAP Tools” on page 16.

•

LDAP Base DN: The directory sync utility will use this Base DN as the top level for all LDAP queries. You can use an LDAP browser to collect this information. If your LDAP directory server includes OUs that you do not want to sync, consider a Base DN that doesn’t include these OUs. Since the directory sync utility searches for both users and groups from the Base DN, specify a Base DN on a level that includes the users and groups you want to synchronize. A typical Base DN for a domain called ad.example.com might be as follows: ou=test,ou=sales,ou=melbourne,dc=ad,dc=example,dc=com

Preparation and Planning

Note: You can use multiple Base DNs in a configuration. You can specify a

separate Base DN for each synchronization rule. •

LDAP Administrator: Collect the username and password of an administrator for Google Apps Directory Sync to use when connecting to your LDAP directory server. This user should have read and execute permissions for the whole LDAP subtree you want to synchronize. If you want to limit what users and OUs you want to synchronize, you can set up an LDAP administrator with limited permissions on your directory server. See your directory server documentation for steps on how to do this.

•

LDAP Queries: Decide which users to synchronize from your LDAP directory server, and create one or more LDAP queries that will find those users. For more information, see “LDAP Queries” on page 23.

•

Mapping: Plan which users will go into Google Apps. Note that you may have some users who should not be synchronized, either on your LDAP server or in Google Apps. Prepare a list of exceptions so that you know what rules to set up.

•

Mail Server: The SMTP mail server to use for notifications. The directory sync utility connects to the mail server you specify. You will need the domain name or IP address of a mail server that will relay messages from the directory sync server. If the SMTP server you plan to use requires SMTP authentication, find or create a username and password for SMTP authentication.

Once you have collected this information and decided on how you want to synchronize users in different organizations, you’re ready to begin with Configuration Manager. If you begin using Configuration Manager and find you need more information, save your configuration file. You can return to Configuration Manager and load your XML file after you collect the needed information.

Pilot Domain You may decide to run a pilot program, using a test domain instead of your LDAP primary domain to try Google Apps and Google Apps Directory Sync. Using Google Apps Directory Sync, this is very easy. Set up the pilot domain as a primary domain in Google Apps. Then, in Configuration Manager, enter the pilot domain as your Google Apps domain, and use a Google Apps administrator for that domain. Google Apps Directory Sync will rename all your accounts to that pilot domain during synchronization. After your pilot period is complete, you can change the domain name (and Google Apps administrator) to your actual primary domain, and keep all other configuration options the same. For more information on setting up your domain name, see “LDAP Connection” on page 44.

Release 1.6.10

Planning for Large or Complex Deployments If your deployment is large enough or complex enough to require multiple configuration files, you may need extra planning and preparation. An LDAP query that returns too many results may time out before returning results. If this happens, do not create multiple configuration files to reduce load, since this will actually slow down performance of Google Apps Directory sync. Instead, consider using a single configuration file with multiple LDAP queries. For instance, instead of looking for all users in an organization with a single query, create two rules, one to search for users with an address that starts with any letter A through M, and another that starts with any letter N through Z (plus any numbers or other supported characters). Splitting up your LDAP query into multiple queries with fewer results is called sharding. Sharding is a common solution to LDAP timeout issues for large deployments. You can also run the same configuration file, and synchronize only groups, or synchronize only users. For more information on how to do this, see “Command Line Synchronization” on page 93.

LDAP Queries The directory sync utility uses the LDAP query language to gather information from your directory server. The LDAP query language is a flexible standard that supports complex and powerful logical queries. To build your LDAP queries, you will need to know your LDAP structure. The best way to collect directory server information is an LDAP browser. For more information, see “Useful LDAP Tools” on page 16. Google Apps Directory Sync strictly adheres to RFC 2254, which defines international standards on LDAP filters. Most of the search rules in the directory sync utility use LDAP queries for information. The only exception to this are Exception Rules, which use substring or regular expressions based on the text of email addresses, not LDAP fields. Note: This document lists many common queries, but every directory server is

different, and many store information in different fields or formats. To develop these queries, consult standard LDAP documentation and review your LDAP structure with an LDAP browser. Google Support cannot write LDAP queries for your environment or debug your LDAP queries.

Preparation and Planning

Syntax The following syntax is used in LDAP filters: Name of Operator

Character

Use

Equals

Creates a filter which requires a field to have a given value.

Any

Wildcard to represent that a field can equal anything except NULL.

Parentheses

()

Separates filters to allow other logical operators to function.

And

Joins filters together. All conditions in the series must be true.

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 â&#x20AC;&#x153;personâ&#x20AC;? (&(objectclass=user)(objectcategory=person))

Mailing Lists only (objectcategory=group)

Public Folders only (objectcategory=publicfolder)

Release 1.6.10

All user objects except for ones with primary email addresses that begin with “test” (&(&(objectclass=user)(objectcategory=person))(!(mail=test*)))

All user objects except for ones with primary email addresses that end with “test” (&(&(objectclass=user)(objectcategory=person))(!(mail=*test)))

All user objects except for ones with primary email addresses that contain the word “test” (&(&(objectclass=user)(objectcategory=person))(!(mail=*test*)))

All user objects (users and aliases) that are designated as a “person” and all group objects (distribution lists) (|(&(objectclass=user)(objectcategory=person))(objectcategory=grou p))

All user objects that are designated as a “person”, all group objects and all contacts, except those with any value defined for extensionAttribute9: (&(|(|(&(objectclass=user)(objectcategory=person))(objectcategory= group))(objectclass=contact))(!(extensionAttribute9=*)))

Active Directory LDAP: All users (objectClass=person)

Active Directory LDAP: All email users (alternate) (&(objectclass=user)(objectcategory=person))

OpenLDAP: All users (objectClass=inetOrgPerson)

Lotus Domino LDAP: All users (objectClass=dominoPerson)

Lotus Domino LDAP: All objects with a mail address defined that are designated as a “person “or “group”: (&(|(objectclass=dominoPerson)(objectclass=dominoGroup)(objectclas s=dominoServerMailInDatabase))(mail=*))

Preparation and Planning

Release 1.6.10

Chapter 4

Installation

Chapter 4

About Installation To run Google Apps Directory Sync, install the directory sync utility on your server. The directory sync utility is designed to run on Windows, Linux or Solaris machines. The installer is an executable program that installs all needed components on the server, including managing libraries, classpath variables, and other components. The installer also uninstalls any existing version of the directory sync utility in the same directory. The sections below contain system requirements, and instructions on how to install, upgrade or uninstall the directory sync utility on your server.

Enable APIs Google Apps Directory Sync uses the Google Apps User API to update your Google Apps domain. For successful synchronization, log in to Google Apps and enable the User API. To enable the User API access for your domain: 1. Log in to your control panel. 2. Click Users and Groups. 3. Click the Settings tab. 4. For Provisioning API: Check the box next to Enable provisioning API. 5. Click Save changes. For more information, see the Google Apps Help Center.

Installation

Install Google Apps Directory Sync To install the directory sync utility: 1. Go to the Directory Sync microsite at: http://google.com/apps/directorysync

2. Choose the operating system of the server where you plan to run the directory sync utility and click Download. 3. Download and run the installer.

4. Complete all the steps of the installer.

Release 1.6.10

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 â&#x20AC;&#x153;Enable APIsâ&#x20AC;? on page 27.

Upgrade Google Apps Directory Sync Google Apps Directory Sync automatically checks to see if there are any updates available. If updates are available, you will be prompted to upgrade when you start Configuration Manager. Configuration files are backward-compatible. Future versions of the directory sync utility can run configuration files created in earlier versions. The installer wizard automatically detects and uninstalls previous versions of the software in the same directory.

Uninstall Google Apps Directory Sync The directory sync utility also includes an uninstaller. To remove the directory sync utility: 1. Open a command line interface and go to the directory that contains the directory sync utility. 2. Run the following command: uninstall

3. In the uninstaller, click Next to uninstall the directory sync utility. 4. Once uninstallation has completed close the uninstaller. All directory sync utility files and all libraries not used by other programs will be removed. Log files and XML configuration files will not be deleted.

Installation

Release 1.6.10

Chapter 5

Configuration

Chapter 5

About Configuration Configuration Manager is a step-by-step graphical user interface that walks you through creating and testing an XML configuration file for Google Apps Directory Sync. Note: Before you use Configuration Manager, collect information about your LDAP directory server and your Google Apps setup. For more information, see “Planning Your Synchronization Strategy” on page 16.‘

In Configuration Manager, you can: •

Set up and test a connection to Google Apps.

•

Configure which users, groups, and shared contacts in Google Apps to synchronize.

•

Set up and test a connection to your LDAP server.

•

Configure LDAP search criteria for synchronization.

•

Set up notifications and logging.

•

Run a simulated synchronization to verify your settings.

Once you have set up your configuration in Configuration Manager, you can run your actual synchronization from the command line. See “Synchronization” on page 93. Configuration Manager does not change the data in your LDAP directory server or Google Apps. It is strictly used to configure and simulate synchronization. Configuration Manager walks you through each step of configuring Google Apps Directory Sync. Once you have finished each page, click Next to go to the next step. You can also go back to previous steps with the Previous button, or jump directly to any step using the left side navigation menu. The directory sync utility includes several ways to customize search rules and filters. When collecting information from your LDAP server, you can define LDAP queries to extract information. The directory sync utility supports RFC 2254, the international standard on LDAP Filters. For the details, see RFC 2254:

Configuration

http://www.ietf.org/rfc/rfc2254.txt

The directory sync utility also includes some non-LDAP filters. In these, you can use regular expressions to filter for patterns of text. Regular expressions use standard Java regular expression syntax, which is similar to most standard regular expression syntax standards.

Configuration Files In Configuration Manager, you can save or load configuration files to manage multiple configuration files and store settings for later. All configuration files are XML files. To save configuration settings under a new name, select File->Save As from the top menu and specify the directory and filename you wish to use. If you overwrite an existing file, Configuration Manager will save the existing file as a copy with the timestamp in the file name. To save configuration settings under the existing name, select File->Save from the top menu. If you are editing a new configuration file you havenâ&#x20AC;&#x2122;t saved yet, this option will be greyed out. If you overwrite an existing file, Configuration Manager will save the previous file as a copy with the timestamp of when the file was overwritten. To open a configuration file, select File->Open from the top menu and choose the configuration file. The user interface will then show the settings for that configuration file. To open a recent configuration file, select File->Open Recent and choose the configuration file. To start a new configuration file, select File->New from the top menu. Configuration Manager will load a new file with no configuration rules specified.

General Settings On the General Settings page, specify which categories of object to synchronize.

Release 1.6.10

The General Settings page also includes a reminder to enable the Provisioning API. For more information about the Provisioning API, see “Enable APIs” on page 27.

On the General Settings page, specify the following: General Setting

Description

Users

Whether Google Apps Directory Sync should synchronize users. Checked by default. For more information, see “LDAP Users” on page 46. Uncheck if you do not want to synchronize users.

Groups

Whether Google Apps Directory Sync should synchronize groups. Checked by default. For more information, see “LDAP Groups” on page 58. Uncheck if you do not want to synchronize groups.

Profiles

Whether Google Apps Directory Sync should synchronize user profiles. Unchecked by default. For more information, see “LDAP User Profiles” on page 67. Check if you want to synchronize user profiles.

Configuration

General Setting

Description

Contacts

Whether Google Apps Directory Sync should synchronize shared contacts. Unchecked by default. For more information, see “LDAP Shared Contacts” on page 76. Check if you want to synchronize user profiles.

Google Apps Configuration The first step in Configuration Manager is to set how Directory Sync will connect to Google Apps. To start the application, run Google Apps Directory Sync Config Manager from the Start menu, or run config-manager from the command line in the directory where you installed the directory sync utility. Before you begin setup in Google Apps Configuration, collect information about your Google Apps domain and your LDAP directory server. For details on what information you’ll need, see “Planning Your Synchronization Strategy” on page 16.

Release 1.6.10

Google Apps Settings Enter your Google Apps login and connection information in this section.

Specify the following: Google Apps Setting

Description

Admin Email Address

The email address used to log into Google Apps. This address should be a valid Google Apps administrator in the domain that you are synchronizing. The domain must match the Domain name. Example: admin@example.com

Admin Password

Enter the password for the Google Apps administrator. Example: swordfish Passwords are stored in an encrypted format.

Domain Name

Enter the domain you wish to synchronize. You must use the primary domain in Google Apps, not a domain alias. If you enter a domain that is different from the domain on your LDAP server, Google Apps Directory Sync will rename all users and use the Domain name listed here instead. Example: example.com

Configuration

Google Apps Setting

Description

Replace domain names in LDAP email addresses 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 user23@domain.com, then the directory sync utility synchronizes user23@example.com. If unchecked, all LDAP email addresses keep their original domain name. Note: Domain names for shared contacts and user

profiles are not replaced. By default, this is checked. SSL Proxy Host Name (if needed)

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 you can connect directly to the internet from this machine, leave this field blank. Example: firewall02-http.mixateriacorp.com

SSL Proxy Host Port (if needed)

If your server is running behind a firewall that requires an SSL Proxy to connect to an outside server, enter the proxy host port here. Otherwise, leave this field blank. Common ports for SSL proxy are 80, 8080, 3128 and 1080. Example: 80

SSL Proxy User Name (if required)

If your server is running behind a firewall that requires an SSL Proxy to connect to an outside server, and that proxy requires authentication, enter the proxy authentication user name here. Otherwise, leave this field blank. Example: proxyuser01

SSL Proxy Password (if required)

If your server is running behind a firewall that requires an SSL Proxy to connect to an outside server, and that proxy requires authentication, enter the proxy authentication password here. Otherwise, leave this field blank. Example: swordfish

Release 1.6.10

Google Apps Setting

Description

HTTP Proxy Host Name

If you use a different proxy server for HTML connections than SSL connections, enter the HTTP proxy host here.

(if needed)

Directory Sync always connects to Google Apps on SSL. The only time the directory sync utility sends traffic by unencrypted HTTP is to validate a certificate with the issuing authority. If you do not use a proxy server, or you use the same proxy server for HTML and SSL connections, leave this field blank. If blank, this field defaults to the value of the SSL Proxy Host Name field. Example: firewall02-http.mixateriacorp.com HTTP Proxy Host Port (if needed)

If you use a different proxy server for HTML connections than SSL connections, enter the HTTP proxy host port number here. If you do not use a proxy server, or you use the same proxy server for HTML and SSL connections, leave this field blank. If blank, this field defaults to the value of the SSL Proxy Host Port field. Example: 80

HTTP Proxy User Name (if required)

If you use a different proxy server for HTML connections than SSL connections, and your HTML proxy requires authentication, enter the proxy authentication user name here. Otherwise, leave this field blank. Example: proxyuser01

HTTP Proxy Password (if required)

If you use a different proxy server for HTML connections than SSL connections, and your HTML proxy requires authentication, enter the proxy authentication password here. Otherwise, leave this field blank. Example: swordfish

Exclusion Filters for Google Apps If you have any users on your Google Apps user list who should not be deleted or moved by the synchronization, add an exclusion filter to protect those users.

Configuration

Other exclusion filters you might want to include are: •

Administrators who are not in your LDAP system

•

Users listed in Google Apps but not your LDAP server

•

Mailing list addresses you’ve manually added in your Google Apps groups that are not in your LDAP server

WARNING: Currently there is no way to exclude User Profiles or Shared Contacts

in Google Apps. If you synchronize User Profiles or Shared Contacts, check your test synchronizations closely to be sure you do not remove information inadvertently. Exclusion rules are based on string values and regular expressions, not LDAP settings.

This page shows the list of exclusion filters. In a new configuration, this contains no exclusion rules. To add new exclusion filters, click the Add Rule button at the bottom of the screen. In the list of Exclusion Filters, you can change existing filters as follows: •

Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters.

•

Edit: Click the notepad icon to edit the settings of an exclusion filter.

•

Delete: Click the X icon to delete the exclusion filter.

Example Google Apps Exclusion Rules Listed below are samples of common exclusion rules. Note that the exact text of these rules will vary based on your needs.

Release 1.6.10

Users not in your LDAP Server

The directory sync utility will delete users from your list of Google Apps users and from all Google Apps groups if they are not listed in your LDAP directory server. Therefore, for single users not listed in your LDAP, add the following two rules. First rule: •

Type: User Name

•

Match Type: Exact Match

•

Exclusion Rule: username@example.com

Second rule: •

Type: Member Name

•

Match Type: Exact Match

•

Exclusion Rule: username@example.com

Pattern of users

If your Google Apps users list includes users that aren’t in your LDAP directory server, and they all match a specific text pattern, you can use a substring or regular expression instead of creating a rule for each user. In this example, all these users have the name “appstrial” in their primary address, such as appstrial-lydia@example.com and appstrial-manesh@example.com. First rule: •

Type: User Name

•

Match Type: Substring

•

Exclusion Rule: appstrial

Second rule: •

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, the directory sync utility will delete them, Therefore, add the following rule. •

Type: Group Name

•

Match Type: Exact Match

•

Exclusion Rule: FloridaSalesTeam@example.com

Configuration

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 Rule Click Add Rule at the bottom of the page to create an exclusion rule.

Release 1.6.10

In the Add Exclusion Rule panel, specify the following to add an exclusion rule. Keep in mind that this is information on your Google Apps account, not your LDAP directory server. Exclusion Rule Setting

Description

Type

Sets the type of exclusion filter to create: User Name, Group Name, or Member Name. •

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

•

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.

Configuration

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: user1@example.com excludes that single Google Apps user from user list synchronization, but not group synchronization. Group Name: FloridaSalesGroup@example.com excludes that Google Apps group from groups synchronization. Member Name: user1@example.com excludes that single Google Apps user from groups synchronization.

•

Substring Match: The address or organization name must contain the text of the rule as a substring. Examples: User Name: sales excludes sales_questions@example.com and amanda@sales.example.com.

Group Name: Sales excludes FloridaSalesGroup@example.com and NorthAmericaSalespeople@example.com.

Member Name: sales excludes sales_questions@example.com and amanda@sales.example.com from groups

synchronization. •

Regular Expression: The address or organization must match the regular expression in the rule. Examples: User Name the regular expression team[39]@example.com excludes team3@example.com through team9@example.com. Group Name: the regular expression Local Team [A-Z][A-Z] excludes the “Local Team - NJ” and “Local Team - AZ” groups. Member Name: the regular expression team[39]@example.com excludes team3@example.com through team9@example.com from groups synchronization.

Release 1.6.10

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, the directory sync utility will attempt to add the user and fail.

LDAP Settings The LDAP Settings section configures how the directory sync utility connects to your LDAP directory server and generates your LDAP user list for comparison.

You may need to collect information from your LDAP directory server before you can enter details in this section.

Configuration

LDAP Connection Specify your LDAP connection and authentication in this page.

LDAP Connection Setting

Description

Connection Type

Choose whether to use an encrypted connection. If your LDAP server supports an SSL connection and you wish to use it, choose LDAP + SSL. Otherwise, choose Standard LDAP. Example: Standard

Host Name

Enter the domain name or IP address of your LDAP directory server. Example: ad.example.com, or 10.22.1.1.

Port

Specify the host port. The default is 389. Example: 389

Base DN

Enter the Base DN for the subtree to synchronize. Do not include spaces between commas. If you donâ&#x20AC;&#x2122;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

Release 1.6.10

LDAP Connection Setting

Description

Authentication Type

The authentication method for your LDAP server If your LDAP server allows anonymous connections and you want to connect anonymously, select Anonymous. Otherwise, select Simple. Example: Simple

Authorized User

Enter the user who will connect to the server. This user should have read and execute permissions for the whole subtree. If your LDAP directory server requires a domain for login, include the domain for the user as well. Example: admin1

Password

Enter the password for the authorized user. Example: swordfishX23 Passwords are stored in an encrypted format.

Test Connection Once you have configured LDAP Authentication settings, click Test Connection. Configuration Manager will connect to your LDAP server and attempt to log in, to verify the settings you entered.

Configuration

LDAP Users The LDAP Settings section configures how Google Apps Directory Sync generates your LDAP user list for comparison. You may need to collect information from your LDAP directory server before you can enter details in this section. WARNING: After you delete a user, you can’t add the same user for 5 days.

Important: You must add at least one LDAP User Sync rule to run Google Apps

Directory Sync. This determines which users are synchronized and added in Google Apps. Even if you only use Google Apps Directory Sync to sync groups and not users (See “Synchronization options” on page 94), the users must be read in, in order to resolve Reference Attributes for group members or group owners.

Release 1.6.10

LDAP User Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP user list.

LDAP User Attribute Setting

Server Type

Description

The type of LDAP server that you are using with the directory sync utility. If you are using a Lotus Domino, Microsoft Active Directory, or Open LDAP directory server, select that server type. Otherwise, select Other. Example: Microsoft Active Directory

Email Address Attribute

The LDAP attribute that contains a userâ&#x20AC;&#x2122;s primary email address. Example: The default is mail.

Alias Address Attribute (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

LDAP User Attribute Setting

Domino Alias Address Attribute (if needed)

Description

Only for Lotus Domino servers. One or more attributes used to hold internal Domino alias attributes, which are stored as usernames without domain information. These addresses will be formatted as email addresses and placed as aliases to the primary address listed in the Email Address Attribute field. If you are using a Lotus Domino server but your alias address attribute stores full SMTP email addresses, list the attribute in Alias Address Attributes, not Domino Alias Address Attributes. Example: uid

Domino Replacement Character

Only for Lotus Domino servers. If an address contains a space, Google Apps Directory Sync will substitute this character instead. Example: The most common values are dot (“.”) and underscore (“_”).

Use Defaults Click this button to use the default values for your server type, as follows: • •

Lotus Domino: Email Address Attribute mail, Domino Alias Address Attribute uid. MS Active Directory: Email Address Attribute mail, Alias Address Attribute proxyAddresses.

Release 1.6.10

•

OpenLDAP: Email Address Attribute mail.

•

Other: Email Address Attribute mail.

LDAP Extended Attributes LDAP Extended Attributes are optional LDAP attributes that you can use to import additional information about your Google Apps users.

All attributes are optional. If you do not specify an attribute, the directory sync utility will not import this information. LDAP Extended Attribute Setting

Given Name Attribute

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. Example: givenName

Family Name Attribute

An LDAP attribute that contains each user’s family name. (In the English language, this is usually the last name.) This is synchronized with the user’s name in Google Apps. Example: surname

Mailbox Quota Size Attribute

This field is not implemented.

Configuration

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 password will be synchronized to match your users’ LDAP passwords. The password field must be a string, not a sequence of bytes. The string is the hex encoding of the hashed password. Example: password The default Active Directory field userPassword is a binary, not a string, and will not work with Google Apps Directory Sync. Consider using Single Sign-On instead. For more information, see Single Sign-On in Google Apps Admin Help.

Password Encryption Attribute

Release 1.6.10

The encryption algorithm that the password attribute uses. •

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

•

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

•

Plaintext: Passwords in your LDAP directory server are not encrypted. The directory sync utility will read the password attribute as unencrypted text, then immediately encrypt the password using SHA1 encryption and synchronize with Google Apps. The directory sync utility will never save, log or transmit your passwords unencrypted.

LDAP Extended Attribute Setting

Google Apps Users Deletion/ Suspension Policy

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.

LDAP User Sync This shows a list of rules used when generating the LDAP user list.

By default, all users that match these search rules will be added to the Google Apps user list and all users that do not match these search rules will be removed. You can change this behavior with exclusion filters.

Configuration

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. 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.

Release 1.6.10

Specify the following: LDAP User Sync Setting

Suspend these users in Google Apps

Description

Suspend all users that match this LDAP user sync rule. The directory sync utility suspends users that already exist in Google Apps. User data is retained. The directory sync utility will add new users that do not yet exist in Google Apps. The new users are added as suspended users, and are not active users. Suspended users will not show up in your Global Address List. Use for an LDAP query that returns deleted or suspended users on your LDAP directory server. If you are importing active users with this rule, leave this unchecked.

Scope

This determines where in the LDAP directory this rule applies. 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

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 “LDAP Queries” on page 23. Example 1: To match all objects (this may cause load problems): objectclass=*

Example 2: To match all human users: •

For OpenLDAP: (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

LDAP User Exclusion Rules If you have any users on your LDAP directory server that match your search rules but should not be added to Google Apps, add an LDAP user exclusion rule. Some examples of reasons for LDAP user exclusion rules:

Release 1.6.10

•

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

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 will be an empty list. To add exclusion filters, click the Add Exclusion Filter button at the bottom of the screen. In the list of Exclusion Filters, you can change existing filters as follows: •

Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters.

•

Edit: Click the notepad icon to edit the settings of an exclusion filter.

•

Delete: Click the X icon to delete the exclusion filter.

Example 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. 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

Configuration

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

Add Exclusion Filter Click the Add Exclusion Filter at the bottom of the page to exclude a user or organization in your LDAP server from synchronization.

Release 1.6.10

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, with the domain name added on. Note: In many cases, Substring Match yields better results than Exact Match.

Example: maria (if you are using the domain example.com) would exclude only the user maria@example.com. •

Substring Match: The address or organization name must contain the text of the rule as a substring. Example: “test” would exclude testadmin@example.com and salestest1@example.com.

•

Regular Expression: The address or organization must match the regular expression specified. Example: internal.*@example.com would exclude internalhelpdesk@example.com and internal@example.com.

Exclude Type

What kind of LDAP data to exclude. •

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

•

Alias Address: Directory Sync will exclude aliases that match this rule. The interface displays this choice as ALIAS.

If you want to exclude both primary addresses and alias addresses, create two exclusion rules. 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

Configuration

LDAP Groups Set up synchronization for Google Apps groups in the LDAP Groups page. Groups are similar to LDAP mailing lists, and allow you to set up email for multiple recipients with a single email address. Note: Google Apps groups is a feature of Google Apps that supports mailing lists,

announcement lists, and teams lists for your mail domain. Google Apps Directory Sync is completely distinct from the Google Groups discussion pages. Despite similar names, the two are unrelated.

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.

Release 1.6.10

LDAP Group Search Rules Groups in Google Apps are a special kind of email address that direct mail to many addresses at once. Google Apps Directory Sync can synchronize groups with your LDAP directory server mailing lists.

This page shows the list of LDAP Group Sync rules. In a new configuration, this will be an empty list. To add mail lists, click the Add Rule button at the bottom of the screen. In the list of Mail List rules, you can change existing filters as follows: •

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.

Configuration

Add Group Search Rule Filter (LDAP) Click the Add Rule at the bottom of the page to synchronize one or more addresses as mailing lists.

The first tab you see is the LDAP tab, which contains information on which LDAP objects to synchronize, and which attributes to use for groups information. To view the groups you have in Google Apps, see the Google Apps control panel.

Attribute Fields: Reference vs. Literal For two entries (Member and Owner) you have a choice of two attributes, a Reference attribute or a Literal attribute. Enter only one of them. To determine which to use, use an LDAP browser to look at the contents of the field you want to use: â&#x20AC;˘

If the field contains an email address such as listowner@example.com then use the Literal attribute.

â&#x20AC;˘

If the field contains a distinguished name such as CN=listowner,OU=administrators,OU=example,OU=com then use the

Reference attribute.

Release 1.6.10

Specify the following: LDAP Group Rule Setting

Description

Scope

Where to apply the mail list rule. Choose which option to user: •

•

Object: Only objects directly matched by the search. No recursion of any kind. Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object.

Example: Subtree Rule

The LDAP query for Group Sync to match. This allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see “LDAP Queries” on page 23. Example: (objectclass=dominoGroup)

Base DN

Group Name Attribute

An LDAP attribute that contains the full-text name of the group. This will become the group email address in Google Apps. Example: cn

Configuration

LDAP Group Rule Setting

Group Description Attribute

Description

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

Member Reference Attribute

An attribute that contains the DN of mailing list members in your LDAP directory sync.

(Either this field or Member Literal Attribute is required.)

Google Apps Directory Server looks up the email addresses of these members and adds each member to the group in Google Apps.

Member Literal Attribute

An attribute that contains the full email address of mailing list members in your LDAP directory sync.

(Either this field or Member Reference Attribute is required.)

Google Apps Directory Server adds each member to the group in Google Apps.

Owner Reference Attribute

An attribute that contains the DN of each group’s owner.

Example: memberUID

Example: memberaddress

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

Release 1.6.10

Edit LDAP Group Rule (Prefix-Suffix) If you need the directory sync utility to add a prefix or suffix to group names, user names or owner names in Google Apps, list them here.

LDAP Group Rule Setting

Description

Group Name Prefix

Text to add at the beginning of each group name. Example: groups-

Group Name Suffix

Text to add at the end of each group name. Example: -list

Replace spaces in group names with

If the group name in your LDAP server contains any spaces, they will be replaced with this. If you leave this blank, the directory sync utility will remove spaces and concatenate group names. Example: underscore (_)

User Name Prefix

Text to add at the beginning of each user name for group members.

User Name Suffix

Text to add at the end of each user name for group members.

Owner Name Prefix

Text to add at the beginning of each user name for group owners.

Owner Name Suffix

Text to add at the end of each user name for group owners.

Configuration

LDAP Group Exclusion Rules You can exclude particular addresses from being imported as groups. If you have any entries in your directory server that match a mail list rule, but should not be treated as a mailing list, list them here. This might include: •

Internal mailing lists that do not have outside email addresses

•

Printers, conference rooms, and other non-user resources

•

Mailing lists that should be treated as individual users, with separate mailboxes and settings.

Exclusion rules are based on string values and regular expressions, not LDAP settings.

This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click the Add Rule button at the bottom of the screen. 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 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.

Release 1.6.10

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. •

Match Type: Regular Expression

•

Rule: internal-test[0-9]*@example.com

Configuration

Add Exclusion Filter Click Add Rule at the bottom of the page to prevent an address from being treated as a mailing list.

Specify the following:

Release 1.6.10

Exclusion Rule Setting

Description

Type

Sets the type of exclusion filter to create: User Name, Group Name, or Member Name. •

User Name: Do not sync any user whose primary address matches the rule. The interface displays this choice as ADDRESS.

•

Group Name: Do not sync any group which has a name that matches the rule. The interface displays this choice as NESTED_GROUP_NAME.

•

Member Name: Do not sync any user whose primary address matches this rule from any groups. The interface displays this choice as MEMBER_NAME.

Exclusion Rule Setting

Description

Match Type

The type of rule to use for the filter.

Exclusion Rule

•

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.

LDAP User Profiles Set up synchronization for Google Apps user profiles in the LDAP User Profiles page. User Profiles contain extended information about users, such as phone number and title.

The LDAP User Profiles section configures how Google Apps Directory Sync generates user profile information from your LDAP directory server. You may need to collect information from your LDAP directory server before you can enter details in this section.

Configuration

LDAP User Profiles Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP user profiles.

Release 1.6.10

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.

Department

LDAP attribute that contains a user’s department.

Office location

LDAP attribute that contains a user’s office location.

Employee ids

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

Websites

LDAP attribute that contains a user’s home page or other website.

Work phone numbers

LDAP attribute that contains a user’s work phone number.

Home phone numbers

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

Fax phone numbers

LDAP attribute that contains a user’s fax number.

Mobile phone numbers

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

Work mobile phone numbers

LDAP attribute that contains a user’s work mobile phone number.

Configuration

LDAP User Profiles Sync This shows a list of rules used when determining which user profiles to import. Note: If you store your user profile information in the same place in your directory

server as your users’ mail addresses, you may use the same sync rules for LDAP User Profiles as you did for LDAP User Sync. To use the same settings, add a new search rule and copy the same scope and rule text.

By default, user profile information will be synchronized for all users that match these search rules will be added to the Google Apps user list. You can change this behavior with exclusion filters. 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

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.

Release 1.6.10

Add User Profile Search Rule To add a new search rule, click Add User Profile Search Rule.

Configuration

This dialog box has the following fields LDAP User Profile Search Rule Field

Scope

Description

This determines where in the LDAP directory this rule applies. Choose which option to use: •

•

Object: Only objects directly matched by the search. No recursion of any kind.Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object.

Example: Subtree Rule

The search rule for user profile sync to match. This rule is a standard LDAP query, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see “LDAP Queries” on page 23. Example 1: To match all objects (this may cause load problems): objectclass=*

Example 2: To match all human users: •

For OpenLDAP: (objectClass=inetOrgPerson)

•

For Active Directory: (objectClass=person)

•

for Lotus Domino: (objectClass=dominoPerson)

Release 1.6.10

LDAP User Profile Search Rule Field

Base DN

Description

LDAP User Profiles Exclusion Rules If you have any existing user profile information in Google Apps that you do not want to synchronize, specify it here.

This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click the Add Exclusion Filter button at the bottom of the screen.

Configuration

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 LDAP 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

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: atif@example.com

Second rule: •

Match Type: Exact Match

•

Rule: svetlana@example.com

Sample Regular Expression Match: Test Users

Release 1.6.10

•

Match Type: Regular Expression

•

Rule: internal-test[0-9]*@example.com

Add Exclusion Filter Click the Add Exclusion Filter at the bottom of the page to exclude a user or organization in your LDAP server from synchronization.

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: maria@example.com would exclude only the user maria@example.com.

•

Substring Match: The address or organization name must contain the text of the rule as a substring. Example: “test” would exclude testadmin@example.com and salestest1@example.com.

•

Regular Expression: The address or organization must match the regular expression specified. Example: internal.*@example.com would exclude internalhelpdesk@example.com and internal@example.com.

Configuration

Exclusion Rule Setting

Description

Rule

Exact Match: maria@example.com

•

Substring Match: listinternal

•

Regular Expression: internal.*@example.com

LDAP Shared Contacts Set up synchronization for Google Apps user profiles in the LDAP User Profiles page. Shared Contacts contain information about contacts, such as name, email address, phone number and title.

Shared Contacts in Google Apps are contacts that any user can see and use. Shared Contacts correspond to a Global Address List (GAL) in Microsoft Active Directory and other directory servers.

Release 1.6.10

You can see Shared Contacts in Google Apps by going to your Inbox and clicking the Contacts link.

The LDAP Shared Contacts section configures how Google Apps Directory Sync generates shared contacts information from your LDAP directory server. You may need to collect information from your LDAP directory server before you can enter details in this section.

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

Autocomplete. While a user types a recipient address in Google Apps Mail, autocomplete will suggest possible addresses that match what the user has typed. This list of possible recipients comes from three places: addresses that the user has mailed before, users (but not groups) in the domain, and Shared Contacts. Adding Shared Contacts means that users will see the address in the suggestion list even if they have not mailed that contact before.

•

Chooser. When a user click on the To field while composing a Google Apps Mail message, the Chooser will present a list of possible recipients, similar to an address list. This list of possible recipients comes from three places: addresses that the user has mailed before, users (but not groups) in the domain, and Shared Contacts.

•

Contacts information. Shared Contacts are not visible when a user clicks the Contacts tab. However, if a user sends mail to a contact, or adds a contact, Google Apps will also add information from Shared Contacts.

Configuration

Below are some of the most common reasons to import Shared Contacts: •

Add groups and outside addresses to autocomplete. User addresses in your domain will show up in autocomplete. However, groups and outside addresses are not visible in autocomplete. Create LDAP sync rules to import any groups or outside addresses you want your users to see when using autocomplete.

•

Give pilot users access to all users for autocomplete. If you are adding a small number of users for a pilot program, consider adding other users as Shared Contacts, so that pilot users will see the address of other users in autocomplete.

•

Provide supplemental directory information to users. If your users want to see rich contact information from your directory server for their contacts (such as postal addresses, phone numbers, companies, and titles), synchronize this information using Shared Contacts. Users will see this additional information in the Contacts page after they have added the contact manually, or sent mail to that contact’s address.

Important: Shared Contacts do not show immediately. After you synchronize

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

LDAP Shared Contacts Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP user profiles.

Release 1.6.10

The fields are as follows. LDAP Shared Contact Attribute

Description

Sync key

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

Full name

LDAP attribute that contains a contact’s full name.

Job title

LDAP attribute that contains a contact’s job title.

Company name

LDAP attribute that contains a contact’s company name.

Department

LDAP attribute that contains a contact’s department.

Office location

LDAP attribute that contains a contact’s office location.

Work email address

LDAP attribute that contains a contact’s email address

Employee ids

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

Websites

LDAP attribute that contains a contact’s home page or other website.

Work phone numbers

LDAP attribute that contains a contact’s work phone number.

Home phone numbers

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

Fax phone numbers

LDAP attribute that contains a contact’s fax number.

Mobile phone numbers

LDAP attribute that contains a contact’s personal mobile phone number.

Work mobile phone numbers

LDAP attribute that contains a contact’s work mobile phone number.

Configuration

LDAP Shared Contacts Sync This shows a list of rules used when determining which shared contacts to import.

By default, shared contacts will be synchronized for all contacts that match these search rules will be added to the Google Apps user list, and removed for shared contacts that do not match these rules. You can change this behavior with exclusion filters. 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 Shared Contact Search Rule button at the bottom of the screen. Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP

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.

Release 1.6.10

Add Shared Contact Search Rule To add a new search rule, click Add Shared Contact Search Rule.

Specify the following:

Configuration

LDAP User Profile Search Rule Field

Scope

Description

This determines where in the LDAP directory this rule applies. Choose which option to use: •

•

Object: Only objects directly matched by the search. No recursion of any kind.Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object.

Example: Subtree Rule

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

Example 2: To match all human users: •

For OpenLDAP: (objectClass=inetOrgPerson)

•

For Active Directory: (objectClass=person)

•

for Lotus Domino: (objectClass=dominoPerson)

Release 1.6.10

LDAP User Profile Search Rule Field

Base DN

Description

LDAP Shared Contacts Exclusion Filter If you have any contacts on your LDAP directory server that match your search rules but should not be added to Google Apps, add an LDAP shared contacts exclusion rule. 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.

This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click the Add Exclusion Filter button at the bottom of the screen.

Configuration

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 LDAP 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: atif@example.com

Second rule: •

Match Type: Exact Match

•

Rule: svetlana@example.com

Sample Regular Expression Match: Test Contacts

Release 1.6.10

•

Match Type: Regular Expression

•

Rule: internal-test[0-9]*@example.com

Add Exclusion Filter Click the Add Exclusion Filter at the bottom of the page to exclude a user or organization in your LDAP server from synchronization.

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: maria@example.com would exclude only the user maria@example.com.

•

Substring Match: The address or organization name must contain the text of the rule as a substring. Example: “test” would exclude testadmin@example.com and salestest1@example.com.

•

Regular Expression: The address or organization must match the regular expression specified. Example: internal.*@example.com would exclude internalhelpdesk@example.com and internal@example.com.

Configuration

Exclusion Rule Setting

Description

Rule

Exact Match: maria@example.com

•

Substring Match: listinternal

•

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. Consider adding a notification to send mail to your own address, and possibly the addresses of any concerned parties in your company. Note: Notifications are sent by plain SMTP, not TLS.

Release 1.6.10

Specify the following: Notifications Setting

Description

Send notifications from address

Enter the â&#x20AC;&#x153;From:â&#x20AC;? address for the notification mail. Recipients will see this address as the notification sender. For instance, you might use your own email address. Example: dirsync@example.com

Send notifications to the following addresses

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, the directory sync utility may be unable to send mail to external email addresses. Run a test notification to confirm that mail is sent properly. Example: dirsync-admins@example.com

SMTP Relay Host

The SMTP mail server to use for notifications. The directory sync utility uses this mail server as a relay host. Note: You cannot use Google Apps as your SMTP

Relay Host for Notifications. Example: 127.0.0.1 to run the mail server on the same machine. Example: mail.example.com Username (if needed)

If the SMTP server you specify requires SMTP authentication, enter the user name to use here. Example: admin5

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.

Configuration

Notifications Setting

Description

Do not include in notifications

You can limit the information sent in notifications by checking any of the three checkboxes. All checkboxes are optional.

(Optional)

•

Extra details: Google Apps Directory Sync notifications will not include extra details and potentially extraneous information.

•

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

•

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

Test Notification Click this button to test notifications. Configuration Manager will connect to the SMTP server you specified and send a test notification to the addresses you list.

Delete Limits As a safeguard, you can limit how many users Google Apps Directory Sync can delete during synchronization. This is recommended as a way to prevent accidental mass deletion.

Release 1.6.10

The directory sync utility checks to be sure that synchronization will not delete too many users. If the synchronization would delete more users than the delete limits allow, the entire synchronization fails and no users are added, moved or deleted. This will be noted in the notifications email.

Note: Delete limits apply during synchronization, but not during simulation.

Simulation results will not include delete limits. To set a delete limit, specify one of the following: Delete Limits Setting

Description

Delete no more than

Specify a maximum percentage of users that can be deleted. This is a percentage of the users registered on Google Apps, not a percentage of users on your LDAP server.

% of users (Optional)

If no delete limit is specified, the default is 5%. Example: 5% You can suppress delete limits from the command line. Delete no more than users (Optional)

Specify a maximum number of users that can be deleted. Example: 25

Configuration

Log Files 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.

Release 1.6.10

•

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

Simulate Sync After you enter configuration information, use this section to verify and test your Google Apps Directory Sync settings. Configuration Manager does not check for valid LDAP syntax. To find invalid LDAP queries, use Simulate Sync. Invalid LDAP queries will cause errors. For information on common errors that might occur and how to troubleshoot them, see â&#x20AC;&#x153;Common Issuesâ&#x20AC;? on page 97.

Simulate Sync When you first go to this page, you will see Validation Results. This page will show a checklist of all the Configuration Manager sections. If you are missing required information, you will see error messages showing what needs to be added.

Important: This checklist confirms only the minimum needed for synchronization.

You may need to configure additional filters or rules to be sure the results are what you expect.

Configuration

Once you’ve completed all required fields, you will be able to use the Simulate Sync button to simulate a synchronization.

Once you’re ready, click Simulate Sync. You will see the Simulate Sync page. During simulation, Configuration Manager will: •

Connect to Google Apps and generate a list of users, groups, and shared contacts.

•

Connect to your LDAP directory server and generate a list of users, groups, and shared contacts.

•

Generate a list of differences.

•

Log all events.

•

If connection was successful, show a Proposed Change Report which shows what changes would have been made to your Google Apps user list.

Note: Simulate Sync will never update or change your LDAP server or your users

in Google Apps. The simulation is strictly for configuration and testing. To run an actual synchronization, use the command line. See “Synchronization” on page 93 for more.

Release 1.6.10

Review the Simulation Results to confirm that the simulation occurred correctly without any unexpected results.

If any errors occur, check the error text. Most error text is human readable, but some error text may contain Java stack trace errors. If you need help troubleshooting these errors, see “Troubleshooting” on page 97. If the synchronization was successful, check the Proposed Change Report and review it for unexpected results. Note: The Proposed Change Report doesn’t check your delete limits.

If you see any errors or unexpected results, you can go back and change your configuration to try again. To change your configuration, click on any of the headings on the left navigation bar. You can switch between the Validation Results and Simulation Results pages using the buttons at the bottom of the page. You can also run another simulation from either page by clicking the Simulate Sync button at the bottom. Once you are finished, save your configuration file and run synchronization. See “Synchronization” on page 93.

Configuration

Release 1.6.10

Chapter 6

Synchronization

Chapter 6

About Synchronization Run the synchronization command to push your LDAP directory server user information to Google Apps. The directory sync utility uses the command sync-cmd to run synchronization. This simple command line interface gives you the flexibility to incorporate synchronization into any scheduling or batch script you wish to use. Before you can synchronize Google Apps with your LDAP directory server, you must create rules that detail how to connect to both servers, and what filters and rules to use. These rules are stored in an XML file. To create this XML file, run Configuration Manager. For more information about Configuration Manager, see “Configuration” on page 31. Most administrators run their first synchronization manually to test the process, import an initial set of users, and confirm the changes. After initial synchronization with the command line, you can set up automatic scheduling for future synchronization.

Command Line Synchronization Before you can run synchronization, create a Configuration XML file using the Configuration Manager user interface. For more information, see For more information about Configuration Manager, see “Configuration” on page 31. The command line to use for all platforms is sync-cmd

Run without any arguments, this command gives an error and directs you to run sync-cmd -h for help. To synchronize, use the following command line to read a configuration file, connect to both servers, generate a list of changes, and apply those changes: sync-cmd -a -c [filename]

Synchronization

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 the directory sync utility is installed. Option

Values

-r,--report-out

Write reports to the specified output file, in addition to writing them to the log.

-a,--apply

Apply detected changes. Note: If you do not use this tag, the

synchronization is a test only and will not affect your Google Apps account. For best results, run a test without this flag before running a full synchronization with this flag. -V

Display detailed application version information. Does not synchronize.

-c,--config [filename]

Specify the configuration to load. Synchronization will not occur without a valid XML file for this argument.

-d, --deletelimits

Ignores any configured delete limits.

-f, --flush

For support troubleshooting only (slows sync) WARNING: This option is intended only to resolve specific troubleshooting issues. Improper use can cause performance degradation. Do not use this option unless directed by support.

-g, --groups

Do not analyze groups. Use this option if you want to synchronize users, but not groups.

-h,--help

View this information and exit.

-l,--loglevel [level]

Override the default and/or configured log level with the specified value. Valid values (in increasing order of verbosity) are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. In most cases, the recommended log level is INFO.

Release 1.6.10

Option

Values

-s, --sharedcontacts

Do not analyze shared contacts. Note: Do not use this option. It is intended for other versions of the directory sync utility, and will have no effect.

-u, --users

Do not analyze users. Use this option if you want to synchronize groups, but not users.

-v

Display short application version information.

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

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

Scheduled Tasks is a third-party product and is not supported directly by the Google (or Postini) team. In the event of a Scheduled Tasks issue, contact your Windows administrator. To schedule a task

1. In Control Panel, open Scheduled Tasks. 2. Double-click Add Scheduled Task.

Synchronization

3. Complete the Scheduled Task wizard using the following information. (Steps may vary depending on your version of Microsoft Windows.) •

Choose the program sync-cmd.exe, located where the directory sync utility is installed.

•

The frequency of the task depends on your synchronization needs. For most environments, twice per week is appropriate.

•

Use Advanced Properties to specify an exact command line. The appropriate command line is: [path]\sync-cmd -a -c [filename]

Replace [path] with the path where the directory sync utility was installed. Replace [filename] with the name of the XML file you created in the Configuration Manager. 4. Test the scheduled task by running manually once. In the Scheduled Tasks window, right-click the task you created and select Run from the right-click menu. Check the log file for errors.

Linux and Solaris: cron In Linux and Solaris environments, schedule synchronization using crontab. Note: These steps apply to most common Linux and Solaris configurations. Linux

and Solaris are third-party products and are not supported directly by the Google (or Postini) team. In the event of an issue with cron, contact your administrator. To add a cron job

1. Run crontab -e to update the crontab file. 2. Add a line in the crontab file for the following command: sync-cmd -a -c [filename]

The syntax of this line will depend on your operating system and version of cron. For instance, to schedule the task to run at 3:30 AM twice per week, on Monday and Thursday, add the following entry: 30 3 * * 1,4 [path]/sync-cmd -a -c [filename]

Replace [path] with the path where the directory sync utility was installed.Replace [filename] with the name of the XML file you created in the Configuration Manager. 3. Save the crontab file and exit your text editor.

Release 1.6.10

Chapter 7

Troubleshooting

Chapter 7

About Troubleshooting This chapter covers information about how to troubleshoot problems that may occur with Google Apps Directory Sync. Troubleshooting information includes information about common issues, system tests and researching issues. For information about LDAP queries, see â&#x20AC;&#x153;LDAP Queriesâ&#x20AC;? on page 23.

Common Issues The following describes common issues and questions related to Google Apps Directory Sync.

Configuration Manager When creating an exception rule, the dialog box does not have an OK button.

You may be using a font that is too large for the screen. The dialog box does not work with Extra Large Fonts or Large Fonts. Change your font size, or edit your XML file directly.

User Sync Errors Error Message: You are not authorized to access this API

Confirm that you are using Premier, Partner or Educational Edition of Google Apps. Google Apps Directory Sync is not compatible with Standard Edition or Team Edition.

Troubleshooting

Enable APIs on your Google Apps domain, as described in “Enable APIs” on page 27. How does Google Apps Directory Sync handle suspended users?

Google Apps Directory Sync is unable to detect suspended users, and will not try to delete them. If Google Apps Directory Sync tries to add a suspended user, you will see an error message: EntityAlreadyExists (1300). Error Message: DomainUserLimitExceeded (error code 1200)

You attempted to add more users than you have licensed seats. Contact your sales representative to purchase more user licenses, or change your LDAP queries to synchronize fewer users. Error Message: UserDeletedRecently (error code 1100)

The directory sync utility tried to add a user who was deleted. When you delete a user, you can’t add that user until 5 days pass. Wait 5 days, or contact support for help. Where can I find a list of other error messages and their meanings?

Other error messages are listed in the Error Codes section of the Google Apps Provisioning API Developer’s Guide.

Synchronization Rules A group rule or exclusion rule doesn’t seem to be doing anything.

Check the scope of the rule. You may need to set the scope to SUBTREE. A group rule generates errors.

Check the Group Search Attribute in LDAP Configuration. This is the field that contains the email address of a group. In most cases, this will be mail. How can I exclude a specific LDAP organization?

You cannot create an LDAP rule to exclude users in a specific LDAP organization. Instead, limit the authority of the LDAP Administrator you use, removing access to any OUs you do not want to synchronize.

Release 1.6.10

Connections and Security The proxy environment requires a password challenge for external web access.

The directory sync utility can use a proxy server but cannot respond to password challenges. To run synchronization, you will need to change your network setup to allow the directory sync utility to connect without a password challenge, or without a proxy server. I cannot simulate a synchronization because the notifications server not specified.

To run a simulated synchronization, you will need a server capable of sending mail. If you are running directory sync on a mail server machine, you can use the IP address 127.0.0.1 for your mail server. Otherwise, contact your mail administrator for the correct mail information. How securely are passwords stored?

Google Apps Directory Sync stores passwords using a two-way encryption scheme. This protects your sensitive information from casual snooping or reverse engineering. To convert a configuration file to the new format with encrypted passwords: 1. Open the file in Configuration Manager. 2. Save the file again. You can also upgrade the file with the following command-line executable: upgrade-config -c [filename]

where [filename] is the name of the XML configuration file to upgrade. Note: Configuration files for version 1.3.11 or later are not compatible with earlier

versions.

LDAP Directory Server The Base DN information doesn’t seem to be correct.

Check to be sure your Base DN doesn’t include any spaces. How do I find out information about my LDAP server fields?

You will need to download an LDAP browser. An LDAP browser allows you to browse through an LDAP directory server and identify all fields and values. Many directory servers do not include a complete LDAP browser. For information on LDAP browsers, see “Useful LDAP Tools” on page 16.

Troubleshooting

How can I get password sync to work?

Google Apps Directory Sync supports two encoding formations: SHA-1 and MD-5. Specify the name of the attribute that contains the password. Google Apps does not return the encoded password back, so every time you run a synchronization, the report will show that all users had passwords updated. An LDAP query that includes a wildcard isn’t working with Lotus Domino LDAP

Lotus Domino has a setting for “Minimum characters for wildcard search” that controls how wildcard LDAP searches work. Update your search to include more characters, or change this setting to a lower number.

System Tests If you encounter problems, use the tests in Configuration Manager to find the problem: 1. In Configuration Manager, open the XML file you are using for configuration. 2. Under LDAP Connections, click Test Connection to confirm you can connect to your LDAP server. 3. Under Notifications, click Test Notification to confirm you can send a test notification. 4. Under Simulate Sync, confirm you have filled out all required fields. 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.

100

Release 1.6.10

Escalating Problems If you are unable to run directory sync, and cannot resolve the problem using system tests, collect the following information for troubleshooting: •

The most current sync log file, located in the folder where the directory sync utility is installed.

•

The version number of the directory sync utility you are running. You can find this in the Configuration Manager UI by going to Help->About, or you can run the command sync-cmd -V.

•

The current config file you are using. This is an XML file (default name sync.xml) located in the same folder where the directory sync utility is installed.

•

The brand and version of the LDAP directory server you're using.

•

The operating system on the machine where the directory sync utility is running.

Once you have collected this information, check the help center or contact support for help.

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

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

Troubleshooting

101

102

Release 1.6.10