Google Apps Directory SyncAdministration Guide Release 3.0.6 Google, Inc. 1600 Amphitheatre Parkway Mountain View, CA 94043 www.google.com Part number: GADS_3.0_36 March 21, 2012 © Copyright 2012 Google, Inc. All rights reserved. Google, the Google logo, Google Message Filtering, Google Message Security, Google Message Discovery, Postini, the Postini logo, Postini Perimeter Manager, Postini Threat Identification Network (PTIN), Postini Industry Heuristics, and PREEMPT are trademarks, registered trademarks, or service marks of Google, Inc. All other trademarks are the property of their respective owners. Use of any Google solution is governed by the license agreement included in your original contract. Any intellectual property rights relating to the Google services are and shall remain the exclusive property of Google, Inc. and/or its subsidiaries (“Google”). You may not attempt to decipher, decompile, or develop source code for any Google product or service offering, or knowingly allow others to do so. Google documentation may not be sold, resold, licensed or sublicensed and may not be transferred without the prior written consent of Google. Your right to copy this manual is limited by copyright law. Making copies, adaptations, or compilation works, without prior written authorization of Google. is prohibited by law and constitutes a punishable violation of the law. No part of this manual may be reproduced in whole or in part without the express written consent of Google. Copyright © by Google, Inc. Google, Inc. provides this publication “as is” without warranty of any either express or implied, including but not limited to the implied warranties of merchantability or fitness for a particular purpose. Google, Inc. may revise this publication from time to time without notice. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you. This software uses the JGoodies Forms, JGoodies Validation, and JGoodies Looks. Copyright (c) 2002-2008 JGoodies Karsten Lentzsch. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: o Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. o Neither the name of JGoodies Karsten Lentzsch nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL Release 3.0.6DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This software uses Apache Derby. Apache Derby Copyright 2004-2007 The Apache Software Foundation 2 Release 3.0.6 This product includes software developed by The Apache Software Foundation (http://www.apache.org/). Portions of Derby were originally developed by International Business Machines Corporation and are licensed to the Apache Software Foundation under the “Software Grant and Corporate Contribution License Agreement”, informally known as the “Derby CLA”. The following copyright notice(s) were affixed to portions of the code with which this file is now or was at one time distributed and are placed here unaltered. (C) Copyright 1997,2004 International Business Machines Corporation. All rights reserved. (C) Copyright IBM Corp. 2003. The portion of the functionTests under 'nist' was originally developed by the National Institute of Standards and Technology (NIST), an agency of the United States Department of Commerce, and adapted by International Business Machines Corporation in accordance with the NIST Software Acknowledgment and Redistribution document at http://www.itl.nist.gov/div897/ctg/sql_form.htm 3 6 .0.4 Release 3. Contents About This Guide 9 What This Guide Contains 9 Related Documentation 9 How to Send Comments About This Guide 10 11 Chapter 2: Overview of Google Apps Directory Sync What Is Google Apps Directory Sync? 11 How Directory Sync Works 12 What Is Synchronized 13 Directory Sync and Deployment 15 System Requirements 19 Chapter 3: Getting Started 23 Overview 23 Step One: Install LDAP Browser 24 Step Two: Collect LDAP Inventory 25 Step Three: Decide What to Synchronize 29 Step Four: Prepare Google Apps for Synchronization 41 Step Five: Prepare Your Servers for Synchronization 42 Further Steps 43 Chapter 4: LDAP Queries 45 About LDAP Queries 45 Syntax 45 Common LDAP Queries 46 Chapter 5: Installation 49 About Installation 49 Install Google Apps Directory Sync 49 Upgrade Google Apps Directory Sync 51 Uninstall Google Apps Directory Sync 51 Chapter 6: Configuration About Configuration 53 Configuration Files 54 53 Contents 5 . General Settings 55 Google Apps Configuration 57 Google Apps Connection Settings 58 Google Apps Proxy Settings 61 Google Apps Exclusion Rules 63 LDAP Configuration 69 LDAP Connection Settings 70 LDAP Org Units 71 Org Unit Mappings 72 Org Unit Search Rules 75 Org Unit Exclusion Rules 77 User Accounts 81 User Attributes 82 Additional User Attributes 83 User Search Rules 88 User Exclusion Rules 92 Groups 96 Group Search Rules 96 Group Exclusion Rules 101 User Profiles 104 User Profile Attributes 104 User Profile Search Rules 106 User Profile Exclusion Rules 109 Shared Contacts 112 Shared Contact Attributes 114 Shared Contact Search Rules 116 Shared Contact Exclusion Rules 118 LDAP Calendar Resources 121 Calendar Resource Attributes 122 Calendar Resource Search Rules 124 Calendar Resource Exclusion Rules 126 Notifications 130 Sync Limits 132 Logging Settings 134 Sync 135 Chapter 7: Synchronization 139 About Synchronization 139 Synchronizing from the Configuration Manager Command Line Synchronization 139 Scheduling Synchronization 141 Monitoring 143 Chapter 8: Troubleshooting 145 About Troubleshooting 145 Troubleshooting With Log Files 145 Common Issues 145 System Tests 149 139 6 Release 3.6 .0. Escalating Problems 150 Contents 7 . 8 Release 3.6 .0. including Google Apps. Includes a description of the product. refer to the following documents. Help Center for Google Apps. Google Apps Admin Help 9 . Document Description Directory Sync Admin Help Page Central page for Google Apps Directory Sync. Mail. Related Documentation For additional information about Google Apps and about related products. groups. and Google Apps Directory Sync. Get the latest download here. and shared contacts Troubleshooting Directory Sync This guide is intended for administrators who are already familiar with Google Apps and with LDAP directory servers. This includes documentation and support for the entire Google Apps suite. as well as available downloads.About This Guide What This Guide Contains The Google Apps Directory Sync Administration Guide provides information about: • • • • • Google Apps Directory Sync features Basic steps for installing Directory Sync on your server Configuration for Directory Sync Synchronizing users. Please send comments about this guide to: enterprise-apps-doc-feedback@google. including release schedules. This is kept up to date with the changes in the latest version. 10 Release 3. resolved issues. Google Apps Directory Sync for Email Security How to Send Comments About This Guide Google values your feedback.Document Description Google Apps Directory Sync Release Notes Release Notes for Google Apps Directory Sync.0. Another version of Google Apps Directory Sync.6 .com Please specify in your message the section to which your comment applies. Google Apps Directory Sync for Email Security synchronizes with Message Security and Delivery (powered by Postini) instead of Google Apps. and known behavior changes. new features. users. and deletes your users.Chapter 2 Overview of Google Apps Directory Sync Chapter 2 What Is Google Apps Directory Sync? Google Apps Directory Sync (also called Directory Sync or GADS) is a utility that adds.S. Google Apps changes to match your LDAP directory. shared contacts. Family Educational Rights and Privacy Act of 1974 (FERPA). GADS runs on your server. OUs. which your end user may then choose to publish publicly on the web. Use GADS to synchronize information so that your Google Apps organizations. please keep a few things in mind: If Google Profiles is enabled for your organization. and updates Google Apps to match your LDAP directory. and shared contacts are automatically kept up to date with your LDAP directory server. Directory Sync never updates or changes your LDAP directory information. Important Notice Before you enable GADS for your organization. and the Children’s Online Privacy Protection Act of 1998 (COPPA).please communicate this to your end users if you have enabled Google Profiles for your organization or if you do so in the future. Customer acknowledges and agrees that Customer is solely responsible for complying with all laws and regulations that might be applicable to Customer’s provision of Google Profiles to Customer’s end users. such as the U. groups. Children’s Internet Protection Act (CIPA). Your use of Google Apps Directory Sync may in some cases override the user’s edits to their own profile fields -. and calendar resources in Google Apps to match your LDAP directory server. Overview of Google Apps Directory Sync 11 . When you synchronize. the data synced from your institution’s directory will be auto-populated into the Google Profile. groups. modifies. and shared contacts on your directory. You can set up rules to specify how this list is generated. 2. 12 Release 3. GADS compares these lists.6 . You can use the sync-cmd utility to update Google Apps data. and shared contacts in Google Apps. groups. GADS connects to Google Apps and generates a list of users. 4. After GADS has finished synchronization. Configuration Manager is a GUI-based wizard that walks through the steps of configuring a synchronization.How Directory Sync Works This section discusses how GADS synchronizes your LDAP data into Google Apps. groups. and generates a list of changes. list which attributes contain the information you want to synchronize. you set up what data to synchronize. The utility is designed to be run from a command line so that you can use your server’s task scheduling to run a scheduled synchronization. and note any exclusion rules. 1. specify LDAP query rules. In Configuration Manager. The sync-cmd is a command-line utility that performs the actual synchronization. You can set up rules to specify how this list is generated. specify server connections.0. 3. GADS connects to your LDAP server and generates a list of users. The Configuration Manager utility allows you to test your settings. and stores information in an XML file that is then used by the sync-cmd utility. GADS then updates Google Apps to match your LDAP server settings. it sends a report of results to email addresses that you specify. Data Flow The following steps describe how the data flow of GADS works. Technical Overview GADS includes two connected tools: Configuration Manager and the sync-cmd synchronization command line utility. Overview of Google Apps Directory Sync 13 . These are not altered or synchronized by Google Apps Directory Sync. All LDAP data is synchronized with Google Apps and stored as user information on Google Apps secure servers. It connects to your LDAP server inside your network through Standard LDAP or secure LDAP + SSL. LDAP Org Units (OU) Google Apps Synchronizes Notes Organizations Organizations in Google Apps contain multiple users. . This connection can also run through a proxy host in your network. It connects to a mail server inside your network using standard (non-TLS) SMTP. It caches some Google Apps information locally on your Directory Sync server. or manually by each organization. It does not store LDAP data on the Directory Sync machine. not LDAP Distinguished Name. It connects to Google Apps through the Internet via HTTPS on port 443. location. Mailing Lists Groups User Users In Google Apps. Organizations can be used to structure users by department. and notes on what is and is not synchronized. You can synchronize org structure automatically. but does not store any LDAP data. but defaults to standard LDAP ports. This connection occurs on any port you specify. user-managed Groups.Security GADS has the following security features: • • It runs inside your network. configuration files. • • • • What Is Synchronized The chart below details what gets synchronized by GADS. and event logs on the Directory Sync server. users are organized by email address. Mailing lists in LDAP correspond to public groups in Google Apps. the equivalent terms between LDAP and Google Apps. Groups can also be used to control access to sites and documents. or other categories. on a machine you control. Google Apps users can also create private. Directory Sync stores connection details. can be synchronized from your LDAP directory into Google Apps. like phone numbers and addresses. can be synchronized into Google Apps as rich User Profiles. and these can come from multiple LDAP alias attributes. use a migration tool. If your users wish to import personal contact information. For more information on Passwords. Rooms Contacts Personal Contacts Personal Contacts Extended User Information User Profiles Shared Folders None 14 Release 3. Shared Contacts are visible as autocomplete options when users in Gmail start typing an email address. Alternatively. GADS does not synchronize personal contacts. Personal contacts are not synchronized. or authentication can be handled by SSO (Single Sign-On). An LDAP Contacts list corresponds to Google Apps Shared Contacts. If you need to migrate your legacy messages and calendar data.0. Google Apps does not include an equivalent to shared folders.LDAP User Aliases Google Apps Synchronizes Notes Nicknames Other email addresses also used by a given primary address. they can use client-based migration tools like Google Apps Migration for Microsoft Outlook. Shared Contacts appear in autocomplete about 24 hours after synchronization.) Calendar Resources Shared Contacts Calendar resources. Each user can have multiple nicknames in Google Apps. such as Google Apps Migration for Lotus Notes. GADS can only synchronize passwords that are stored in SHA-1 or MD-5 format with no salted hashes. Passwords Passwords Messages and Calendar Data Messages and calendar data are not migrated with GADS. Extended LDAP information. see “Passwords” on page 34. like rooms and projectors.6 . or Google Apps Migration for Microsoft Exchange (which also migrates data for other IMAP servers. passwords can be managed separately. Users typically share information in Google Apps by sharing Google Docs or through Groups. you may decide to add your Core IT and Early Adopter users at the same time.Directory Sync and Deployment GADS can be used during different stages of the Google Apps deployment cycle. and name changes. Third Phase: Global Go Live: All users are activated in Google Apps. Overview of Google Apps Directory Sync 15 . take time to learn about Google Apps. The following steps are described in more detail below. and updating for changes to your organization such as departing users. Second Phase: Early Adopter: A small number of early adopters are activated with Google Apps and use it for regular business functions. The goal of this model is to accomplish a Google Apps deployment quickly and give users the best possible customer experience. For a tutorial on the three-phase deployment model. First Phase: Core IT: Core IT department users are activated on Google Apps. This section discusses the three-phase deployment model recommended for implementing Google Apps. new hires. and secure resources. The Three-Phase Deployment Model The methodology described in this section is based on field studies and real-world deployment experience with Google Apps. and combine these two phases. Variations for Different Organizations These steps may vary for your environment. Maintenance: After your Global Go Live date. • • • • • Plan: Before you begin with your Core IT phase. ongoing maintenance involves keeping up services. Deployment is typically divided into three phases. monitoring to detect any issues. plan for your deployment. If you are administering an organization with fewer than 500 users. and how Directory Sync fits into this model. see the video Planning Your Google Apps Deployment. plus planning beforehand and maintenance afterward. see “Getting Started” on page 23. Fore more information on these preparations. Before you begin with the Core IT phase.0. decide what tools to use. Directory Sync: During this phase. Clean up your LDAP directory. identify any need for outside consulting or support. learn technical details.6 . • • • • Prepare a provisioning strategy. Core IT 16 Release 3. begin making preparations for Google Apps. In this case. and set a plan for implementing Google Apps. you may move directly to Global Go Live and continue through maintenance.If you have already added users through another method. and begin using GADS afterwards. the goal is to understand the services available. During the Plan step. and you would set up GADS to synchronize your users and maintain Google Apps to match your LDAP data going forward. Secure LDAP resources. Plan Users: No users added yet. Specific preparations you can make at this stage include the following. Prepare your firewall/proxy settings and network ports to ensure that Directory Sync has a connection to your LDAP directory and to Google Apps. there’s a period of preparation and planning. you would not set up a Core IT or Early Adopter phase. continue preparation and testing to be ready for Directory Sync implementation by the Early Adopter phase. GADS is not used to import users for the initial IT pilot. identify any common questions or issues. you can also set up GADS to synchronize data for early adopters. prepare your synchronization rules so that full synchronization will be ready on your Global Go Live date. so that your Early Adopter users can see recipient addresses in Autocomplete when sending mail. since it is easier to add your initial IT department users either manually or by uploading a CSV file into the Google Apps control panel. adding users with the same username in a separate test domain. Early Adopter Users: Early adopter business users. Early adopters can then become familiar with Google Apps. Optionally. Typically. Directory Sync: During the Early Adopter phase. remember to add exclusion rules so those users are not deleted. If you do have manually added users that are not in your LDAP. The goal of the Core IT phase is to learn how to use the applications and utilities. either manual or synchronized. During the Early Adopter phase. and learn to use the product so that they can help others after a broader rollout. or synchronize as full users without sending passwords or routing users’ mail into Google Apps. In the Core IT phase. and to prepare for Early Adopters. 3. 2. to configure services. set up a small number of active users and give them the best possible user experience. If you are running the Early Adopter phase on a separate test domain. If you are using Postini Message Security. you can set up Postini for split delivery. You can use any of these features for Early Adopter synchronization: 1. a small number of IT users activate in Google Apps and begin learning and configuring Google Apps. You can synchronize users as shared contacts.Users: A small number of manually added users. Overview of Google Apps Directory Sync 17 . You can use GADS during your Early Adopters phase to synchronize your entire user list. Directory Sync: During this phase. so that Early Adopters receive mail in Gmail while other users receive mail on your legacy server. GADS can synchronize users to a test domain. data from legacy systems may be migrated into Google Apps. contacts. and day-to-day user activities run in Google Apps. Be prepared for an extended synchronization. In the Global Go Live phase. all users become active and begin using Google Apps for daily business. Maintenance Users: Updated to maintain changes between your LDAP directory and Google Apps. you may decide to split your synchronization into phases to avoid exceeding any search size limits on your directory server. The initial synchronization of a Go Live date can take several cycles of configuration and tests.0. Prepare for your Go Live date. During your rollout. and try to run your synchronization during off-business hours to avoid consuming network and system resources during peak hours. 18 Release 3. groups. and calendar resources so that your Google Apps account is populated with the same data you have on your LDAP directory server. Note also that shared contacts can take up to 24 hours after synchronization to show up in Gmail autocomplete. or may be left on legacy servers and checked when needed. profile information.6 . Directory Sync: You can set up GADS to import organizations. After your Global Go Live date. After you have set up Google Apps and your users are live with the product. aliases. users schedule their activities in Google Calendar. since there may be a great deal of data to synchronize. users.Global Go Live Users: All users active in Google Apps. Mail flow is routed entirely to Gmail. continue to update Google Apps to reflect any changes on your LDAP directory. For steps on how to do this. not domain aliases. or users moved to new organizations. Note: GADS only synchronizes primary domains. You can use GADS to keep your Google Apps directory up to date. System Requirements Before you begin using GADS. Depending on your needs. in order to smoothly handle the user’s documents and mail archives. Google Apps for Government. will be reflected in Google Apps. so that all changes to your LDAP directory server are synchronized with Google Apps. Usually.If you remove any users from your company. during maintenance. • Overview of Google Apps Directory Sync 19 . You can check for new updates by opening Configuration Manager. set up in the Google Apps control panel. • An administrator account on your Google Apps domain. deleted users. or Google Apps for Education. or by running the command checkforupdate. Also. Any changes to your LDAP directory server. You can set up GADS to run scheduled synchronization. update Google Apps to reflect these changes. You can also set up an OAuth key while configuring Google Apps if you have administrator login information. Google Apps for Partners. rather than deleting the user from Google Apps. Directory Sync: Check your notification messages regularly to be sure that GADS is running smoothly. and to detect and address any issues that arise. such as new users. be sure to check regularly for updates to GADS. Google Apps Account • A Google Apps domain running Google Apps for Business. be sure you can meet the following system requirements. this ranges between once an hour and once a day. Be aware that running synchronization too often may use up excess bandwidth or exceed quotas. you may run scheduled synchronizations at different rates. see “Enable APIs” on page 42. Provisioning API enabled on your Google Apps domain.exe. Many companies remove a user by changing the user’s password and access permissions. your familiarity with the LDAP query language. At least 256 MB of free RAM. A mail server able to accept and relay notifications from Directory Sync.Server Requirements • A server to run GADS. Access to SSL Authorities for your network. the initial configuration of GADS includes multiple revisions of synchronization rules. The server should run one of the following operating systems: • • • • • Microsoft Windows (supported on XP. Windows 7. and your familiarity with your own LDAP directory server and data.6 . An LDAP server with user information which is accessible to GADS. directly or through a proxy server.0. further tuning may be needed. updating and refining your LDAP synchronization rules until a simulated sync delivers expected results. For best results. a 32-bit libc (such as libc6-i386) must be installed. If you are running with DEBUG or INFO level of logging. For very large organizations (over 250. • • • • • • • • • Level of Effort and Expertise The level of effort for using GADS will vary based on the scope of your synchronization plans. All versions of the LDAP protocol are supported.000 users.000). you may need more free space than this for additional log data. or 2 GB of free RAM if you have more than 10. Network access to your LDAP server. At least 1 GB of free RAM is recommended if you have less than 10. Windows Server 2003/ 2008) Linux Solaris (version 8+. Read and execute administrative access over the appropriate OU structure of the LDAP server. You do not need to run GADS on your LDAP server. An LDAP browser that can read and browse your LDAP directory server data. 20 Release 3. In many cases. At least 5 GB of disk space for log files and data. a network connection to Google Apps with no proxies or firewalls is recommended. no support for x86) If using 64-bit Linux systems.000 users. This includes ports 80 and 443. Network access to the Google Apps through HTTPS. Overview of Google Apps Directory Sync 21 . Human Resources contact: Familiarity with user base and ability to identify which LDAP entries represent current employees.Depending on your configuration. Familiarity with setting up mail servers for traffic. LDAP administrator: Access to your directory server and familiarity with its contents. Familiarity with LDAP query language. you may need the following levels of expertise for implementing GADS: • • • • • Google Apps administrator: Access to your Google Apps administrator account and familiarity with the Google Apps control panel. Network administrator: Familiarity with your network and security settings for internal and outbound traffic. Mail administrator: Access to a mail server able to relay messages for Directory Sync notifications. 6 .22 Release 3.0. Your GADS configuration will be faster and smoother if you collect information about your network. follow the steps detailed below. Collect LDAP Inventory. For details on system requirements and prerequisites. 2. and synchronization plans before you begin. Collect required information about your LDAP server and your Google Apps domain. and implementing GADS. Getting Started 23 . For more information. including LDAP servers and expert administrators. see “System Requirements” on page 19. see “Step Two: Collect LDAP Inventory” on page 25. Getting Started Steps The following list describes typical steps for preparing. see “Step One: Install LDAP Browser” on page 24. LDAP data. Identify your LDAP resources.Chapter 3 Getting Started Chapter 3 Overview This chapter discusses the steps you’ll take when you get started with Google Apps Directory Sync (GADS). Install LDAP Browser. Note that these steps do not correspond precisely to the three-phase model described in the previous chapter in “Directory Sync and Deployment” on page 15. 1. This chapter also includes necessary steps for setting up your Google Apps account and your internal network before you install GADS. so that you will have synchronization ready during the Early Adopter phase. In most cases. Download an LDAP browser to examine your current LDAP directory server. For a more successful synchronization. LDAP directory server. you will begin these steps during the Planning or the Core IT phases of deployment. planning. For more information. aliases. Check the results. This step is covered in “Command Line Synchronization” on page 139. 11. most LDAP directory servers do not include a way to view or modify your LDAP structure directly. are covered in this chapter below.0. This step is covered in “Scheduling Synchronization” on page 141. run a manual synchronization to update Google Apps. The first steps. Preview Synchronization. which imports all information. 13. Make any needed changes to Google Apps. 8. The first synchronization. Use Configuration Manager to simulate a synchronization and review the results. At the command line. Manual Synchronization. 10. Prepare Google Apps For Synchronization. This step is covered in “Sync” on page 135. and groups you want to synchronize with Google Apps. run a synchronization in preview mode with the configuration file you created. Decide what domains to synchronize. Later steps are covered in future chapters as noted. If needed. This step is covered in “Command Line Synchronization” on page 139. At the command line. 24 Release 3. download and install GADS. to configure synchronization. Decide What To Synchronize. Monitor the results of your ongoing synchronization to detect and address any problems that occur. Prepare Your Server Environment For Synchronization. 12. To collect information about your LDAP structure. Plan which users. This could take several revisions for complex environments. Run Configuration Manager. part of GADS. For more information. see “Step Four: Prepare Google Apps for Synchronization” on page 41. see “Step Three: Decide What to Synchronize” on page 29. and may require a great deal of planning. This can be a very significant step. 5. Configure Directory Sync. Simulate Synchronization.6 .3. This step is covered in “Configuration” on page 53. Scheduled Synchronization. Review the results of the simulated sync. 9. Confirm that you have a notification mail server ready. Step One: Install LDAP Browser By default. revise your configuration in Configuration Manager based on the simulation. Revise Configuration. related to preparation. For more information. For more information. download and install an LDAP browser. This step is covered in “Installation” on page 49. This step is discussed in “Monitoring” on page 143. Monitoring. Install Directory Sync. set up automatic scheduled synchronization. see “Step Five: Prepare Your Servers for Synchronization” on page 42. Using your server’s scheduling tools. 6. is likely to take much longer than later synchronizations. Once you have the needed information. 4. Two such browsers are listed below. 7. Note that these are third-party browsers.com JXplorer To download the JXplorer Java Ldap Browser. Depending on the size and structure of your organization. you may already know all this information. See your directory server documentation for steps on how to do this. and outbound connections. Identify LDAP Resources Contact your LDAP administrators and collect the following information: • • • The hostname or IP address of your LDAP server. or you may need to conduct significant research.org Step Two: Collect LDAP Inventory You can roll out and use GADS more quickly and effectively if you identify your LDAP resources beforehand. you can set up an LDAP administrator with limited permissions on your directory server. The name and password of an account on your LDAP with “read” and “execute” permissions. • Getting Started 25 . go to: http://www. and this document does not include instructions or support on the use of an LDAP browser. Confirmation that your chosen LDAP directory has full access to needed resources. Note that GADS can only synchronize with one LDAP server. proxy servers. If you want to limit what users and OUs you want to synchronize. Your network access.jxplorer. Softerra LDAP Administrator To download Softerra LDAP Administrator.ldapbrowser. go to: http://www. consider the following: • Consolidate. a Global Catalog may help with your synchronization. GADS can only pull data from a single LDAP directory. consider a Base DN that doesn’t include these OUs. If you have multiple Microsoft Active Directory domains. You can use an LDAP browser to collect this information. is a medium-sized manufacturing company that has moved to Google Apps and is starting to synchronize an existing LDAP directory server with Google Apps. acquisitions. The Google Apps administrator confirms with Human Resources that the users on this server are all active users. • Sample Scenario: Identify LDAP Resources MobiStep.” Many customers have multiple LDAP directories. Be sure to collect the following key information: • LDAP Base DN: GADS will use this Base DN as the top level for all LDAP queries. 26 Release 3. Inc. who provides the following information: • • An LDAP administrator account (with appropriate permissions) created specifically for GADS.6 . If you are using multiple directories. The LDAP administrator confirms that GADS will be run within the company’s firewall and that the LDAP server will not need to be open to the outside. Since GADS searches for both users and groups from the Base DN. but only if the catalog is set up with proper replication. The IP address and hostname of the LDAP server. and confirms that this is the only LDAP directory server.0. that you have unexpected or non-standard data in your LDAP directory server. either because of different departments. The Google Apps administrator contacts the LDAP administrator. If your LDAP directory server includes OUs that you do not want to sync.. Research LDAP Structure Use an LDAP browser to collect information about your LDAP server and structure. consolidate your LDAP data into a “single source of truth. or subsidiaries.If you have multiple LDAP directories. You may find. If you want to try using a Global Catalog. It is always better to find and address this before you begin synchronizing. be sure to test the catalog thoroughly before relying upon it. specify a Base DN on a level that includes the users and groups you want to synchronize. Test Global Catalog. while preparing for synchronization. hr. to avoid data cleanup blocking your schedule for synchronization. Each department function is a separate OU under the Base DN. Sample Scenario: Research LDAP Structure MobiStep’s administrator downloads an LDAP browser and look through the directory structure.ou=headquarters.com is: ou=users. Clean Up LDAP Data While you are identifying your LDAP data. • LDAP Structure Information: You need to know which OUs contain users and other resources you want to sync and which LDAP attributes contain important information. and exec. you are ready to start making decisions about your synchronization. You can specify a separate Base DN for each synchronization rule. manufacturing. The administrator finds that the Base DN to use for the domain ad. see “User Search Rules” on page 88. genadmin.dc=com Then. the LDAP attribute that contains a user’s mail address. which will become the username in Google Apps.Note: You can use multiple Base DNs in a configuration. be aware that you may need to clean up your LDAP directory server data to synchronize with Google Apps.mobistep. Department OUs include: sales. In some cases. and finds that the OUs are divided up by department function. contractors. then examine some sample users and other resources to identify the LDAP attributes. In many cases.dc=mobistep. Begin cleaning up your LDAP data early. Confirm the LDAP attribute you want to use for mail addresses.dc=ad. the administrator looks more closely at the structure. Getting Started 27 . Check your LDAP directory server to find out which attributes contain the data you need. this data may include spaces. it. is the mail attribute. Look through your LDAP directory structure with an LDAP browser. Once you have collected this information. For more information. make your transition to Google Apps clear and visible. and possibly bypass any complications with your existing LDAP directory structure.” Use this to mark all users whom you plan to move into Google Apps. see the Google Code site article Developing a naming strategy for your calendar resources. Mark Google Apps Users In LDAP One of the most effective ways to simplify your synchronization is to mark Google Apps users beforehand in your LDAP directory. Mail-Enabled Groups. see “Passwords” on page 34. and populate the attribute with a password setting. or custom attribute. The administrator uses an LDAP browser to identify users and mail-enabled groups. and update any users to fit these naming conventions. Identify any email naming conventions you want to use. • • • • Sample Scenario: Clean Up LDAP Data The MobiStep LDAP Administrator cleans up the MobiStep LDAP database to get ready for synchronization. you can take this opportunity to plan a naming convention in Google Apps. Later. Identify which users you want to synchronize with Google Apps. The existing names already follow a standard naming convention. Generate random passwords and add them to a custom attribute. not security groups. This includes only mail-enabled groups that operate as mailing lists. • Identify users. this will be used to hold randomly generated passwords for new users. For more information on this calendar resource naming. Populate Password Attribute (Optional). If you are planning to synchronize calendar resources. Plan Resource Naming Conventions. Note also that you can set Google Apps to allow users to create and manage their own groups. these are not affected by synchronization. and the administrator decides to keep that naming convention. You may need to consult with your human resources department to confirm that your user list is the correct list of users to synchronize. but some companies use the transition to Google Apps as an opportunity to change naming standards. The LDAP administrator also creates a custom attribute for one-time passwords. Set Naming Conventions (Optional).When conducting LDAP cleanup. Use a descriptive name like “GoogleAppsUsers. This is optional: you do not need to set any particular naming convention for GADS. If you are using a password field in GADS. Identify mail-enabled groups to synchronize with Google Apps.6 . group. 28 Release 3. create a custom attribute in your LDAP for your Google Apps users. When you first clean up your LDAP directory structure. The benefit of marking your Google Apps users in LDAP is that it will simplify your LDAP queries. mark the users you plan to move into Google Apps with an OU. consider the following actions.0. For more information about Passwords. Then, once you begin synchronization, mark active Google Apps users. Create an OU, group, or custom attribute with a name like “GoogleAppsActiveUsers.” You can then configure Directory Sync to synchronize based on this OU, group, or custom attribute, then activate new users in Google Apps by updating your LDAP server. There are three ways to mark your Google Apps users in LDAP: • • • OU: Set up an organizational unit (OU) and move Google Apps users into that unit. Group: Create a new group in LDAP, and add Google Apps users as a member of that group. Custom Attribute: Create a custom attribute for your users, and set that attribute for new users. Use whichever method works best for your LDAP directory environment. The exact steps necessary to set up an OU, group, or custom attribute will vary based on your LDAP directory server. Consult your LDAP directory server documentation and work with your LDAP administrator to configure your LDAP server appropriately. Sample Scenario: Mark Google Apps Users In LDAP The administrator creates two new groups on LDAP, GoogleAppsUsers and GoogleAppsActiveUsers. All users who are identified to be synchronized into Google Apps are added to the GoogleAppsUsers group. When users are added into Google Apps, and have their mail flow switched over, those users are also added to the ActiveGoogleAppsUsers Group. This will make it easier to track which users are in Google Apps, and allows a clean synchronization without removing old accounts that will not be synchronized into Google Apps. Step Three: Decide What to Synchronize Once you have identified your LDAP servers, decide what to synchronize. For specific suggestions on what to synchronize during an early adopter program or other parts of your life cycle, see “Roadmap for Deployment” on page 36, in this chapter. Domains Decide what domains you want to synchronize on your LDAP server and in Google Apps. Google Apps Directory Sync can synchronize with multiple domains on the same account. • Domain: Before you configure synchronization, decide what domain you want to synchronize, and set up your domain in Google Apps. Getting Started 29 Note: GADS does not create a domain for you, so you will need to add the domain before you use Directory Sync. Collect the exact domain name from the Google Apps control panel. Note that you cannot synchronize a domain alias. • Domain Name Replacement: You can also specify another domain. Directory Sync will create or update all users in the new replacement domain. This is most often used for a pilot domain, but can also be used if you are using GADS to move to a new domain. If you specify another domain in Configuration Manager, you can import a full list of users into a different domain. Note that using domain replacement can affect your Google Apps exclusion rules. 30 Release 3.0.6 Note: Domain name substitution does not support Shared Contacts synchronization. Set up the new domain as a primary domain in Google Apps. Then, in Configuration Manager, enter the new domain as your Google Apps domain, and use a Google Apps administrator for that domain. In Google Apps Settings, set Directory Sync to replace domain names in LDAP email addresses with this user name. Google Apps Directory Sync will rename all your users to that new domain during synchronization. After your pilot period is complete, you can change the domain name (and Google Apps administrator) to your actual primary domain, and keep all other configuration options the same. For more information on setting up your domain name, see “LDAP Connection Settings” on page 70. User Data GADS can synchronize a wide variety of user data. This includes users, passwords, alias information, and profiles. Examine your LDAP directory data and your Google Apps configuration to decide what data to synchronize. You may need to purchase additional licenses in Google Apps if you add users above your current number of licenses. Consider the following synchronization options: • Users: Look through your whole set of users with an LDAP browser. For more information about using an LDAP browser, see “Step One: Install LDAP Browser” on page 24. You may have internal-only users, or special users that should not have external email (such as printers). You may also decide to start by synchronizing only a small trial group of users. Construct an LDAP query for the users you want to synchronize. For more information on constructing LDAP queries, see “About LDAP Queries” on page 45. WARNING: Check to be sure that you are importing the correct number of users. If you import more users than you have licenses in Google Apps, you may experience errors during synchronization for exceeding your user limit. • User Profiles: If your LDAP directory server includes further information, such as addresses, phone numbers, or contact information, you can synchronize this information into Google Apps. You can use GADS to import the full names of your users into Google Apps. If you want to do this, find the LDAP attributes that contain this information. User names are often stored in two attributes: one for the first name and one for the last name. If you do not have an LDAP attribute with the appropriate information, you can skip this step.You can synchronize this through LDAP extended attributes. For more information, see “User Profiles” on page 104. If you have full user profiles in your LDAP directory server and you want to synchronize this information into Google Apps, you can import User Profiles. For more information, see “User Profiles” on page 104. • Aliases: You can synchronize one or more attributes for aliases from your LDAP directory into Google Apps nicknames. Use an LDAP browser to Getting Started 31 see “Additional User Attributes” on page 83.com. GADS will not modify or overwrite groups that users create with the Google Groups for Business service. If this is what you want GADS to do. set up a Primary Key attribute beforehand so that user information is not lost when a user changes their name. This is often the member attribute or the mailAddress attribute. which follow a format like terri@mobistep. Different lists and groups can be synchronized into Google Apps in different ways. or may contain unusable data. If you want GADS to handle passwords.confirm the LDAP attribute (or attributes) you want to use. users not found on your LDAP directory will be deleted from Google Apps. For more information on these options. and suspended users will be ignored. and will not change when your users change names. • Mailing Lists: Decide which mailing lists you want to synchronize from your LDAP directory server into Google Apps. Some contain Distinguished Name reference. you can instead set GADS to delete suspended users. Mailing lists on your LDAP directory server will be imported as groups in Google Apps. If your Google Apps account has suspended users that you want to remove. or a user Distinguished Name. Passwords: GADS supports a limited set of password operations. see “Passwords” on page 34. If this attribute is also used for other data.0. You cannot use this setting if you use the option. You may not want to import all mailing lists. Some mailing list attributes contain a literal address. If you do want to synchronize Mailing Lists. For more information. to suspend users instead of deleting them. Be sure that the attribute contains only an email address. This allows for data recovery if users are later recovered. You can set GADS to suspend users instead of deleting them. and not other data such as a phone number. Deleted and Suspended Users: By default. Also. this will require additional preparation and planning. since some lists may be internal lists. find out if the LDAP attribute for mailing list members contains an email address. Be sure to exclude empty lists. described in the paragraph above. see “Groups” on page 96. but your LDAP directory server may be different. For information on synchronizing mailing lists. leave deleted and suspended users settings at the default. • • Groups and Mailing Lists There are several ways to organize your users in Google Apps. find out what attribute contains the members of your mailing lists. and the ability to view and transfer a user’s assets. This should be a field on your LDAP that is unique for each user.6 . or company resources such as rooms or printers. which follow a format like cn=Terri 32 Release 3. Decide how you want to organize your users. and consider the following topics. • Primary Domain Key: If your users are likely to change user names. you may need to use another attribute or to clean up your LDAP directory server. you can use Shared Contacts to synchronize the rest of your user base into your shared contacts list. see “LDAP Org Units” on page 71. To set this up. it may take up to 24 hours for the changes to appear in Google Apps. or if you want all users to have the same settings and rights.Smith. If you’re setting up a pilot with a small group of users. After you synchronize Shared Contacts. but move users between existing Organizations. but you’ll need to know which you’re using beforehand so you can configure GADS properly. These are different from personal contacts. personal contacts are not imported with GADS. This works well if you have a small organization. If you decide to do so.ou=Executive Team. For more information about Shared Contacts. to avoid duplicate Autocomplete addresses. note that you should remove these shared contacts before your full synchronization. see and “User Search Rules” on page 88. select “Do not create or delete Google Organizations. For more information about moving users between existing organizations. If you want to use an org unit hierarchy in Google Apps. GADS synchronizes all users into a single flat structure. If you want to create Google Apps organizations manually. look through your OUs with an LDAP browser beforehand to be sure that you are synchronizing the right OU structure. When users enter email addresses for recipients in Gmail. you can set those organizations up in Google Apps.dc=mobistep. so that pilot users will see addresses in Autocomplete that haven’t been synchronized yet. without changing existing organizations. For more information about synchronizing your OU structure. You may have special OUs that should not have org units in Google Apps. Note that this will only synchronize shared contacts. GADS can synchronize mailing lists using either format. enable Shared Contacts in General Settings. If you do so. For every user search rule. This also works well if you are piloting a small group before a larger rollout. or an LDAP attribute that contains the name of the appropriate Organization. see “Shared Contacts” on page 112. as specified in the User Sync Rules” option on the General Settings page. such as shared contacts and calendar resources. Important: Shared Contacts do not show up immediately. you can synchronize the organization hierarchy from your LDAP directory server. addresses in Shared Contacts will show up in Autocomplete. Shared Contacts will be visible to every user on a contacts list. • Shared Contacts: If you want to import addresses into Google Apps as shared contacts. Shared contacts are contacts that can be viewed by every user in the account. Getting Started 33 . specify the organization that should contain users for that rule.dc=com. then set GADS to move users into those Google Apps organizations. Contacts and Calendar Resources GADS can also synchronize other LDAP resources into Google Apps. however. which are each viewed and edited by an individual user. • Org Structure: By default. such as an OU for printers. see “LDAP Calendar Resources” on page 121. For more information. see the Google Code site article Developing a naming strategy for your calendar resources. 34 Release 3. unsalted MD5. and storing your user passwords in these formats on your mail server may have serious security implications. Base64. If you do want to synchronize calendar resources. Calendar Resources are visible to every user when attempting to schedule calendar events. The rules for calendar resources names are different than other synchronized information. choose a naming format for your calendar resources. For more information on this calendar resource naming. but only in an LDAP attribute that stores passwords in plain text. or unsalted SHA-1 format.• Do you want to synchronize Calendar Resources? If you want to import calendar resources (such as conference rooms) from your LDAP into Google Apps. nor are salted hashes. Note that names containing spaces or special characters (like @) will not be synchronized. Other password encryption hashes are not currently supported.6 .0. configure Calendar Resources synchronization. Most directory servers do not support these formats natively. Passwords Directory Sync can import passwords from LDAP. Google Apps passwords are separate from passwords on your LDAP directory server. and ActiveSync) do not support Single Sign-On and will still require a Google password. POP. With this option. The most secure way to create a default password is to populate a custom attribute with a randomly generated password. Specify a default password for new users. Google Apps passwords are separate from passwords on your LDAP directory server. and to require new users to change passwords. and resource in your LDAP directory server should be synchronized in your Google Apps data. Getting Started 35 . You can use this method to create a temporary password from any LDAP attribute that holds data in plain text format. group. GADS provides the following options: • Implement Single Sign-On for your domain. Use this option if you need to have Google Apps use the same passwords as your LDAP directory server. Important: Be careful of the security considerations of passwords. Use this option if you want users to have separate one-time passwords. Alternately. note that if • you use a plaintext password. but you are unable to set up a SAML server. Note that Single Sign-On supports only web authentication. With this option. Also. be sure to set GADS to synchronize passwords only for new users. Check the Google Marketplace for third-party tools to help with synchronizing passwords. Set up a SAML server for your account to manage Single Sign-On. see the SSO site on Google Code. Users will use the same passwords and authorization for both Google Apps and your LDAP directory server. such as employee ID number. You should have a clear picture of where every user.For password synchronization. and then set Directory Sync to synchronize passwords for new users and force new users to change their passwords. Set a default password for new users. this is not generally recommended as a secure option. Mapping Decide how your LDAP directory server data should map to your Google Apps data. since this could make it easier for other users to sign up using temporary credentials. such as email address or last name. This may require you to set new passwords on your LDAP directory. • Use a plain text LDAP attribute for default password for new users. Every new user will have the same password until that user logs in and changes the password. Use this option if you are planning to set up Single Sign-On for your domain. and you have or can create an appropriate LDAP field to use for temporary passwords. GADS will create random passwords during synchronization in this case. Other forms of authentication (such as IMAP. • Use a third-party utility to convert unsupported passwords to a supported format. you can use a private and unique field. For more information on Single Sign-On. Avoid using a field that could be easily guessed. Because this password may be guessed by other users. Identify any exceptions that you don’t want to synchronize. Find out which users and groups you’d like to exclude. and stage in the life cycle of using GADS. and where those users should be imported. printers. pilot test accounts. This could include new users not listed in your LDAP directory.0. decide whether those users should be imported. • Mapping: For each group of users. defunct mailing lists.6 .For a chart of how your LDAP data maps to Google Apps. you may need to set up manual exception rules to skip specific users. and note these so that you can create exceptions during configuration. suspended users. Exceptions on Google Apps: Are there any exceptions on your Google Apps domain that you don’t want to synchronize? Your Google Apps account may have users or groups that you don’t want to synchronize with LDAP. server. or a pattern of users. In most cases. see “What Is Synchronized” on page 13. • • Roadmap for Deployment The best settings to use for synchronization depend on your situation. and look for any common pattern that may simplify exception rules. test accounts. either on your LDAP server or in Google Apps. Note that you may have some users who should not be synchronized. an automatic one-to-one synchronization. or other data that you do not want to import into Google Apps. you can set your LDAP search rules to ignore these users. You can set up this mapping to a flat hierarchy. or other entries that belong in your Google Apps account but not your LDAP directory. 36 Release 3. Exceptions on LDAP Directory: Are there any exceptions on your LDAP directory that you don’t want to synchronize? Your LDAP directory server may have obsolete users. shared Google Apps accounts. Prepare a list of exceptions so that you know what rules to set up. or a manual set of custom rules. but in some cases. The following roadmap suggests likely settings for different stages of a deployment. The first Synchronization can take time. Domains Optionally. like test.com. Keep Google Apps data synchronized with your LDAP directory. Use your primary domain for synchronization. Set Google Apps up as primary service. Scheduled synchronization will take less time and resources than the first synchronization. In some cases. Getting Started 37 .exmpl. By the end of the Early Adopter phase. see “Directory Sync and Deployment” on page 15. Plan a scheduled synchronization of Google Apps. replacing domain names with a subdomain of your existing organization. Synchronize a few days in advance of your Go Live date so that users will be ready. it may be a good idea to synchronize over a weekend. you can use a “shadow” or test domain. you should have GADS ready for your Global Go Live date. Test connectivity and synchronization. Use your primary domain for synchronization. Core IT Early Adopter Go Live Maintenance Goals in this phase Clean up data and prepare for migration in Early Adopter phase.For more information about deployment phases and the 3-phase deployment model. Switch users over to Google Apps. create a group of custom attribute for active Google Apps users. you can synchronize this with Google Apps. Passwords If you are syncing your users. so that all addresses will be visible in Autocomplete. Create an LDAP OU. Mark which users are activated in your LDAP directory. Then. sync passwords as well. you can synchronize this with Google Apps. Optionally. temporary administrators. group. If your LDAP directory includes rich profile data. or other users that are not part of your LDAP search rules.Core IT Early Adopter Go Live Maintenance Users Set up exceptions for manuallyadded Core IT users. If your LDAP directory includes rich profile data. 38 Release 3. you can synchronize this with Google Apps.6 .0. Set up exceptions for Google Apps users that are not listed in your LDAP directory. you can synchronize all users (but not change their mail flow or send passwords). or custom attribute for users that will be synced into Google Apps. User Profiles Synchronize your early adopters or add them manually. Aliases If your LDAP directory includes rich profile data. Changes to your Organization Structure Mapping rules will move users within Google Apps. configure Directory Sync to synchronize Org Structure. but available if you want to suspend users instead of deleting them. Org Structure Optionally. GADS does not synchronize or overwrite usermanaged mailing lists (groups). Usually not used after go live date. If you have a large organization or complex hierarchy in your LDAP directory server that you want to keep. Most mailing lists will still be maintained on legacy server. start setting up your org structure in advance during Early Adopter phase. Getting Started 39 . but available if you want to suspend users instead of deleting them. Mailing Lists Suspended users can be used for early migration of data.Core IT Early Adopter Go Live Maintenance Suspended Users You can synchronize Google Apps users as suspended users for testing Google Apps functionality. Mailing lists should now be managed in Google Apps as groups. Usually not used after go live date. Primary Key Attribute Set up Primary Key Attribute for easier ongoing maintenance. Calendar resources should now be managed in Google Apps.Core IT Early Adopter Go Live Maintenance Shared Contacts Optionally. Calendar Resources Most calendar resources will be maintained on legacy server. If your company directory has shared contacts. 40 Release 3. and identifies the OUs that should be synchronized. If your company directory has shared contacts. Primary Key attributes help users keep data after a name change.6 . you can synchronize all users as shared contacts so that they will be visible in Autocomplete. you can synchronize these during your Go Live synchronization. Note that personal contacts are not synchronized. Sample Scenario The Google Apps administrator for MobiStep decides that the existing organization hierarchy on the LDAP server should be copied onto Google Apps. you can synchronize these during your Go Live synchronization. Note that these shared contacts may lead to duplicate contacts if not removed before your Go Live date. Note that personal contacts are not synchronized.0. There are two ways to do this. Step Four: Prepare Google Apps for Synchronization Once you know what to synchronize. Because the LDAP user profile information on the LDAP server is not in a standard format across organizations. the Google Apps administrator decides not to synchronize this information. not a literal attribute. This method is recommended because it is more secure. there are a few miscellaneous steps you’ll need to take to prepare for synchronization. The Google Apps identifies that there are some users in the contractors OU that are no longer with the company and should not be synchronized. The Google Apps administrator sets up a mail merge to send out these passwords to users along with information on how to activate their accounts. but will need a Google Apps administrator username and password during this process. rather than their email address.The administrator decides that MobiStep needs to synchronize: • • • • • • OUs Users Aliases Groups (mailing lists) Shared contacts Calendar resources The mailing lists in the LDAP server use the attribute member to store the members of each mailing list. • OAuth Credentials (recommended): GADS can generate an OAuth token during configuration. The administrator looks through these users and notes that all of them match a regular expression (the user addresses all begin with “defunct”) and notes this to create exceptions in Google Apps. Collect the username and password for the administrator account you will use. Google Apps Authentication GADS needs to log into Google Apps to update information. and notes that it is a reference attribute. If you are using this method. • Getting Started 41 . Administrator: Alternately. you can supply a Google Apps username and password that GADS will use when synchronizing. and the member attribute contains the full DN of the mailing list members. and use that token to connect and synchronize. The LDAP administrator creates a custom attribute and populates the attribute with a randomly-generated one-time password. you will generate the token during configuration. The GADS administrator notes this attribute. Collect the following information: • • • • The addresses that should receive notifications. 4. The address the notifications should come from. Before you can synchronize. see the Google Apps Help Center. Note that you cannot use Google Apps as your notifications mail server. The SMTP relay host IP address or domain name. Sample Scenario MobiStep’s Google Apps administrator decides to use OAuth. Step Five: Prepare Your Servers for Synchronization Be sure that your servers and network are prepared for GADS. Because of this. For more information. 3. 42 Release 3. For Provisioning API: Check the box next to Enable provisioning API. Log in to your control panel.6 .0. and collects a Google Apps administrator username and password to configure this. If it’s already checked. leave it checked. you will need a mail server that can relay reports from GADS. Click Save changes. Enable APIs GADS uses the Google Apps Provisioning API to update your Google Apps domain. 2. The username and password for connecting to the SMTP relay host (if needed). Notifications Mail Server GADS is designed to be used for scheduled synchronization without supervision. you must log in to Google Apps and enable the User API. Click Domain settings > User settings. To enable the Provisioning API access for your domain: 1. once synchronization rules are set up. see “Google Apps Connection Settings” on page 58.For more information. 10. 6.notifications@mobistep. 9. Install Directory Sync. This step is covered in “Configuration” on page 53. 12. The MobiStep administrator decides that the notifications should come from the address dirsync. Getting Started 43 . Monitoring. This step is covered in “Sync” on page 135. This step is covered in “Command Line Synchronization” on page 139. Simulate Synchronization.The administrator also contacts MobiStep’s mail administrator to set up notifications. Configure Directory Sync. so the mail administrator sets up an exception so that the machine running Directory Sync can relay mail through that server to send out notifications.com so that notifications can be filtered separately into a label. This step is covered in “Monitoring” on page 143. so no username or password are required. 7. This step is covered in “Installation” on page 49. Further Steps Further steps are discussed in later chapters: 5. This step is covered in “Command Line Synchronization” on page 139. 8. Scheduled Synchronization. The existing MobiStep mail server has a rule to block all relay attempts. 11. Revise Configuration. Preview Synchronization. Manual Synchronization. This step is covered in “Scheduling Synchronization” on page 141. This step is covered in “Configuration” on page 53. The server doesn’t use SMTP authentication. 44 Release 3.0.6 . To develop these queries. The only exception to this are Exception Rules. Before you can synchronize data from your directory server. The LDAP query language is a flexible standard that supports complex and powerful logical queries. LDAP Queries 45 . Google Apps Directory Sync strictly adheres to RFC 2254. you will need to know your LDAP structure. The best way to collect directory server information is an LDAP browser. Note: This document lists many common queries. which defines international standards on LDAP filters. not LDAP fields. 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. which use substring or regular expressions based on the text of email addresses. Google support cannot write LDAP queries for your environment or debug your LDAP queries. and many store information in different fields or formats. see “Step One: Install LDAP Browser” on page 24.Chapter 4 LDAP Queries Chapter 4 About LDAP Queries GADS uses the LDAP query language to collect data from your directory server. Most of the search rules in GADS use LDAP queries for information. For more information. and is discussed in this section. you will need to prepare LDAP queries. To build your LDAP queries. consult standard LDAP documentation and review your LDAP structure with an LDAP browser. but every directory server is different. and are designed to work with most directory server environments. Joins filters together. Separates filters to allow other logical operators to function.Name of Operator Character Use Any Parentheses And Or Not * () & | ! Wildcard to represent that a field can equal anything except NULL. Joins filters together. At least one condition in the series must be true. These queries are the most common queries used.0. All objects (this may cause load problems): objectclass=* All user objects that are designated as a “person” (&(objectclass=user)(objectcategory=person)) Mailing Lists only (objectcategory=group) Public Folders only (objectcategory=publicfolder) All user objects except for ones with primary email addresses that begin with “test” (&(&(objectclass=user)(objectcategory=person))(!(mail=test*))) All user objects except for ones with primary email addresses that end with “test” (&(&(objectclass=user)(objectcategory=person))(!(mail=*test))) 46 Release 3. All conditions in the series must be true. see the common LDAP queries below. Excludes all objects that match the filter.6 . For examples of how these operators are used. Common LDAP Queries The examples below show the most common LDAP queries. OU=Users.DC=com”: (&objectcategory=user)(memberof=CN=GRoup.OU=Users.DC=com )) Active Directory LDAP: All users (objectClass=person) Active Directory LDAP: All email users (alternate) (&(objectclass=user)(objectcategory=person)) OpenLDAP: All users (objectClass=inetOrgPerson) Lotus Domino LDAP: All users (objectClass=dominoPerson) Lotus Domino LDAP: All objects with a mail address defined that are designated as a “person “or “group”: (&(|(objectclass=dominoPerson)(objectclass=dominoGroup)(objectclas s=dominoServerMailInDatabase))(mail=*)) LDAP Queries 47 .DC=Domain.DC=Domain.All user objects except for ones with primary email addresses that contain the word “test” (&(&(objectclass=user)(objectcategory=person))(!(mail=*test*))) All user objects (users and aliases) that are designated as a “person” and all group objects (distribution lists) (|(&(objectclass=user)(objectcategory=person))(objectcategory=grou p)) All user objects that are designated as a “person”. all group objects and all contacts. except those with any value defined for extensionAttribute9: (&(|(|(&(objectclass=user)(objectcategory=person))(objectcategory= group))(objectclass=contact))(!(extensionAttribute9=*))) All users who are members of the group identified by the DN of “CN=GRoup. 48 Release 3.6 .0. Go to the GADS download page at: http://google. Linux or Solaris servers. Installation 49 . Choose the operating system of the server where you plan to run GADS and click Download. and instructions on how to install. The sections below contain system requirements. The installer also uninstalls any existing version of GADS in the same directory. Install Google Apps Directory Sync To install GADS: 1. The installer is an executable program that installs all needed components on the server. including managing libraries.Chapter 5 Installation Chapter 5 About Installation Google Apps Directory Sync (GADS) is designed to run on Windows. and other components. classpath variables.com/apps/directorysync 2. upgrade or uninstall GADS on your server. The installer contains all needed components and can be run offline without any outside connection. 4. 50 Release 3. you must also enable APIs on your Google Apps domain. Complete all the steps of the installer.6 .3. Download and run the installer.0. Note: To run synchronization. See “Enable APIs” on page 42. Upgrade Google Apps Directory Sync GADS automatically checks to see if there are any updates available. If updates are available. 4. click Next to uninstall GADS. Open a command line interface and go to the directory that contains GADS. 2. To remove GADS: 1. Uninstall Google Apps Directory Sync GADS also includes an uninstaller. Installation 51 . Configuration files are backward-compatible. The installer wizard automatically detects and uninstalls previous versions of the software in the same directory. In the uninstaller. you will be prompted to upgrade when you start Configuration Manager. Once uninstallation has completed close the uninstaller. All GADS utility files and all libraries not used by other programs will be removed. Log files and XML configuration files will not be deleted. Future versions of GADS can run configuration files created in earlier versions. Run the following command: uninstall 3. 52 Release 3.0.6 . click Next to go to the next step. Once you have finished each page. Configuration 53 . Configuration Manager does not change the data in your LDAP directory server or Google Apps.Chapter 6 Configuration Chapter 6 About Configuration Configuration Manager is a step-by-step graphical user interface that walks you through creating and testing an XML configuration file for Google Apps Directory Sync (GADS). For more information. Once you have set up your configuration in Configuration Manager. you can: • • • • • • Set up and test a connection to Google Apps. and shared contacts in Google Apps to synchronize. groups. or run config-manager from the command line in the directory where you installed Directory Sync. Configure LDAP search criteria for synchronization. To start the application. see “Getting Started” on page 23. Note: Before you use Configuration Manager. Set up notifications and logging. you can run your actual synchronization from the command line. run the GADS Configuration Manager from the Start menu. Configure which users. It is strictly used to configure and simulate synchronization. collect information about your LDAP directory server and your Google Apps setup. or jump directly to any step using the left side navigation menu. See “Synchronization” on page 139. Set up and test a connection to your LDAP server. Configuration Manager walks you through each step of configuring GADS. You can also go back to previous steps with the Previous button. Run a simulated synchronization to verify your settings.‘ In Configuration Manager. GADS includes several ways to customize search rules and filters. When collecting information from your LDAP server, you can define LDAP queries to extract information. Directory Sync supports RFC 2254, the international standard on LDAP Filters. For the details, see RFC 2254: http://www.ietf.org/rfc/rfc2254.txt GADS also includes some non-LDAP filters. In these, you can use regular expressions to filter for patterns of text. Regular expressions use standard Java regular expression syntax, which is similar to most standard regular expression syntax standards. In Configuration Manager, required fields are marked by blue highlight. Configuration Files In Configuration Manager, you can save or load configuration files to manage multiple configuration files and store settings for later. All configuration files are XML files. To save configuration settings under a new name, select File > Save As from the top menu and specify the directory and filename you wish to use. If you overwrite an existing file, Configuration Manager will save the existing file as a copy with the timestamp in the file name. To save configuration settings under the existing name, select File > Save from the top menu. If you are editing a new configuration file you haven’t saved yet, this option will be greyed out. If you overwrite an existing file, Configuration Manager will save the previous file as a copy with the timestamp of when the file was overwritten. To open a configuration file, select File > Open from the top menu and choose the configuration file. The user interface will then show the settings for that configuration file. To open a recent configuration file, select File > Open Recent and choose the configuration file. To start a new configuration file, select File > New from the top menu. Configuration Manager will load a new file with no configuration rules specified. Multiple Configuration Files If you want to use multiple configuration files, you may need extra planning and preparation. You may wish to use multiple configuration files because of a large deployment that needs to be split into smaller synchronizations, or to reduce performance load, or to vary the rate of synchronization, 54 Release 3.0.6 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, because this will actually slow down performance of Google Apps Directory sync. Instead, consider using a single configuration file with multiple LDAP queries. For instance, instead of looking for all users in an organization with a single query, create two rules, one to search for users with an address that starts with any letter A through M, and another that starts with any letter N through Z (plus any numbers or other supported characters). Splitting up your LDAP query into multiple queries with fewer results is called sharding. Sharding is a common solution to LDAP timeout issues for large deployments. You can also run the same configuration file, and synchronize only groups, or synchronize only users. For more information on how to do this, see “Command Line Synchronization” on page 139. General Settings On the General Settings page, specify which categories of object to synchronize. Notice about Google Apps Directory Sync Before you enable GADS for your organization, please keep a few things in mind: If Google Profiles is enabled for your organization, the data synced from your institution’s directory will be auto-populated into the Google Profile, which your end user may then choose to publish publicly on the web. Your use of Google Apps Directory Sync may in some cases override the user’s edits to their own profile fields -- please communicate this to your end users if you have enabled Google Profiles for your organization or if you do so in the future. Customer acknowledges and agrees that Customer is solely responsible for complying with all laws and regulations that might be applicable to Customer’s provision of Google Profiles to Customer’s end users, such as the U.S. Family Educational Rights and Privacy Act of 1974 (FERPA), Children’s Internet Protection Act (CIPA), and the Children’s Online Privacy Protection Act of 1998 (COPPA). Configuration 55 General Settings The General Settings page also includes a reminder to enable the Provisioning API. For more information about the Provisioning API, see “Enable APIs” on page 42. = On the General Settings page, specify the following: General Setting Description Organizational Units Users Accounts Whether GADS should synchronize organizational units. Unchecked by default. Whether GADS should synchronize users. Checked by default. For more information, see “User Accounts” on page 81. Uncheck if you do not want to synchronize users. Groups Whether GADS should synchronize groups. Checked by default. For more information, see “Groups” on page 96. Uncheck if you do not want to synchronize groups. 56 Release 3.0.6 Unchecked by default. Calendar Resources Whether GADS should synchronize calendar resources. see “Shared Contacts” on page 112. Unchecked by default. see “User Profiles” on page 104. Check if you want to synchronize calendar resources. Shared Contacts Whether GADS should synchronize shared contacts. Check if you want to synchronize user profiles. Unchecked by default. Configuration 57 . For details on what information you’ll need. see “LDAP Calendar Resources” on page 121. For more information. collect information about your Google Apps domain and your LDAP directory server.General Setting Description User Profiles Whether GADS should synchronize user profiles. For more information. For more information. Google Apps Configuration Before you begin setup in Google Apps Configuration. see “Getting Started” on page 23. Check if you want to synchronize shared contacts. Specify the following: Google Apps Setting Description Primary Domain Name Enter the primary domain you wish to synchronize. not a domain alias. If you enter a domain that is different from the domain on your LDAP server. You must use the primary domain in Google Apps.0. Google Apps Directory Sync will rename all users and use the Domain name listed here instead.6 . Example: example.com 58 Release 3.Google Apps Connection Settings Enter your Google Apps login and connection information in this section. This is the recommended setting. If unchecked. Options: • Authorize using OAuth: Connect to Google Apps during synchronization using an OAuth token that you generate in Google Apps.com. if your Domain Name is example. Configuration 59 . If you chose Use your Administrator Credentials. click Authorize Now to create and enter your validation token string. then Directory Sync synchronizes
[email protected]. The domain must match the Domain name. If checked. all LDAP email addresses keep their original domain name. Authorization The method you wish to use for connecting to Google Apps securely.Google Apps Setting Description Replace domain names in LDAP email addresses (of users and groups) with this domain name. • Authorize Now Admin Email Address If you chose Authorize using OAuth.com Admin Password If you chose Use your Administrator Credentials. all LDAP email addresses are changed to match the domain listed in Domain Name. Alias Domains This field is not used. Example: swordfish Passwords are stored in an encrypted format. Use your Administrator Credentials: Connect to Google Apps during synchronization using an Administration Email address and password. the domain name is stripped for exclusion rules. For instance. Example: admin@example. Note: Domain names for shared contacts are not replaced. If this setting is enabled.com. Important: Note that if the domain is replaced. this may affect exclusion rules that search for exact match of a user name. the password for the Google Apps administrator. an administrator email address in the domain you are authorizing. and your LDAP query returns an email address user23@domain. click Authorize Now to set up your Authorization settings and create a verification code. Copy that token. Enter the verification code you created in Google Apps in the Verification Code field. 60 Release 3. Click Validate to confirm that the code is valid. Click Sign In to open a browser window and sign in to Google Apps.0. 5. 1.6 . Google Apps automatically displays a token. sign in to Google Apps using administrator credentials. 4. In the browser page.Authorizing using OAuth If you are using OAuth for authorization. 6. After you enter your credentials. 2. 3. Return to the Google Apps Directory Sync Configuration tool and click Next. If you can connect directly to the internet from this machine.Test Connection After you have configured Google Apps Settings. Google Apps Proxy Settings Provide any necessary network proxy settings in this section. enter the proxy host name here.mixateriacorp. Example: firewall02-http. click Test Connection.com Configuration 61 . Provide the following: Google Apps Setting Description 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. leave this field blank. Configuration Manager connects to Google Apps and attempts to log in to verify the authorization and settings you entered. enter the proxy host port here. or you use the same proxy server for HTML and SSL connections. 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. Otherwise. enter the proxy authentication password here.0.Google Apps Setting Description 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. 8080.6 .mixateriacorp. leave this field blank. The only time Directory Sync sends traffic by unencrypted HTTP is to validate a certificate with the issuing authority. this field defaults to the value of the SSL Proxy Host Name field. 3128 and 1080. Example: swordfish HTTP Proxy Host Name (if needed) If you use a different proxy server for HTML connections than SSL connections. If you do not use a proxy server. and that proxy requires authentication. Otherwise. 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. Directory Sync always connects to Google Apps on SSL. leave this field blank.com 62 Release 3. leave this field blank. leave this field blank. If blank. enter the HTTP proxy host here. Example: firewall02-http. and that proxy requires authentication. Common ports for SSL proxy are 80. enter the proxy authentication user name here. Otherwise. Example: swordfish Google Apps Exclusion Rules Exclusion rules let you omit specific users. enter the proxy authentication user name here. calendar resources. leave this field blank. along with any other Google Apps data you want to preserve: • • Google Apps administrators and other users that are not in your LDAP system Any mailing list addresses you’ve manually added to Google Apps groups that are not in your LDAP server Configuration 63 . Example: proxyuser01 HTTP Proxy Password (if required) If you use a different proxy server for HTML connections than SSL connections. enter the HTTP proxy host port number here. org units. Use exclusion rules to preserve information in Google Apps that isn’t in your LDAP system. Otherwise. this field defaults to the value of the SSL Proxy Host Port field. If you do not use a proxy server.Google Apps Setting Description HTTP Proxy Host Port (if needed) If you use a different proxy server for HTML connections than SSL connections. and your HTML proxy requires authentication. Example: 80 HTTP Proxy User Name (if required) If you use a different proxy server for HTML connections than SSL connections. enter the proxy authentication password here. leave this field blank. and other Google Apps data from the synchronization process. If blank. and your HTML proxy requires authentication. Otherwise. or you use the same proxy server for HTML and SSL connections. groups. You should create exclusion rules for the following. leave this field blank. Exclusion rules are based on string values and regular expressions. In a new configuration. 64 Release 3.6 . this contains no exclusion rules. Delete: Click the X icon to delete the exclusion filter. Users under a particular organization You can set up a rule to exclude an entire Google Apps organization path. not LDAP settings. This page shows the list of exclusion filters. Note that the exact text of these rules will vary based on your needs. click Add Exclusion Rule.0. you can change existing filters as follows: • • • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. In the list of Exclusion Filters. To add new exclusion filters. Example Google Apps Exclusion Rules Listed below are samples of common exclusion rules. Edit: Click the notepad icon to edit the settings of an exclusion filter. You can exclude user profiles or shared contacts by their primary sync key. and they all match a specific text pattern. First rule: • • • Type: User Name Match Type: Exact Match Exclusion Rule: username@example. In this example. all these users have the name “appstrial” in their primary address. add the following two rules. as well as any others under the administrators organization: • • • Type: Organization Complete Path Match Type: Substring Exclusion Rule: administrators Users not in your LDAP Server Directory Sync will delete users from your list of Google Apps users and from all Google Apps groups if they are not listed in your LDAP directory server. if you add all your IT administrators to the organization path “administrators/IT” and your security administrators in the organization path “administrators/security” you could use the following rule to exclude both groups of users. for single users not listed in your LDAP. you can use a substring or regular expression instead of creating a rule for each user. such as
[email protected] instance. Therefore.com Pattern of users If your Google Apps users list includes users that aren’t in your LDAP directory server.com and
[email protected]. First rule: • • • Type: User Name Match Type: Substring Exclusion Rule: appstrial Second rule: • • • Type: Member Name Match Type: Substring Exclusion Rule: appstrial Configuration 65 .com Second rule: • • • Type: Member Name Match Type: Exact Match Exclusion Rule: username@example. Directory Sync will delete them. the Google Apps group also include addresses in two other domains.6 . Therefore. Google Apps Directory Sync will remove these unless you add a Member Name exclusion filter.0.com External Mailing List Members Groups in Google Apps can also include mailing address that are outside your domain.com. 66 Release 3.Custom Google Apps Groups If you have groups listed in Google Apps that don’t match a mailing list in your LDAP directory server. • • • Type: Group Name Match Type: Exact Match Exclusion Rule:
[email protected] Second Rule: • • • Type: Member Name Match Type: Substring Exclusion Rule: @electric-automotive. First Rule: • • • Type: Member Name Match Type: Substring Exclusion Rule: @gmail. In this example.com Add Exclusion Rule Click Add Exclusion Rule to create an exclusion rule.com and electric-automotive. add the following rule. gmail. Calendar Resource Display Name: Do not remove a calendar resource if its display name matches the rule. • User Email Address: Do not delete any user whose primary address matches the rule. Calendar Resource Id: Do not remove a calendar resource if its resource ID matches the rule. The interface displays this choice as GROUP_NAME. Exclusion Rule Setting Description Type Sets the type of exclusion filter to create: User Name. The interface displays this choice as MEMBER_NAME. Group Member Address: Do not remove any user whose primary address matches this rule from any groups. 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 USER_NAME. User Profile Primary Sync Key: Do not delete any user profile if the user’s address matches the rule. specify the following to add an exclusion rule. The interface displays this choice as USER_PROFILE_PRIMARY_KEY. • Organization Complete Path: Do not delete any user who is a member of an organization that matches the complete path rule. The interface displays this choice as ORGUNIT_PATH. Group Name. not your LDAP directory server. The interface displays this choice as USER_ALIAS. Organization paths are treated as strings with the format organization/sub-organization/sub-suborganization.In the Add Exclusion Rule panel. or Member Name. Keep in mind that this is information on your Google Apps account. Alias Email Address: Do not delete any user with an alias address that matches the rule. Calendar Resource Type: Do not remove a calendar resource if its type matches the rule. The interface displays this choice as SHARED_CONTACT_PRIMARY_KEY. Group Email Address: Do not remove any group which has a name that matches the rule. • • • • • • • • Configuration 67 . 0.NJ” and “Local Team .example. • Regular Expression: The address or organization must match the regular expression in the rule. Member Name: the regular expression team[39]@example. Member Name:
[email protected] excludes that Google Apps group from groups synchronization. Group Name: the regular expression Local Team [A-Z][A-Z] excludes the “Local Team .com. 68 Release 3.com and amanda@sales. but not group synchronization.com excludes that single Google Apps user from groups synchronization.com and
[email protected] excludes team3@example. • Exact Match: The address or organization name must match the rule exactly.example. Examples: User Name: sales excludes sales_questions@example. Member Name: sales excludes
[email protected] through
[email protected] from groups synchronization.6 . Group Name:
[email protected] and
[email protected] from groups synchronization.com excludes that single Google Apps user from user list synchronization.Exclusion Rule Setting Description Match Type The type of rule to match for the filter. Group Name: Sales excludes
[email protected] excludes team3@example. Examples: User Name the regular expression team[39]@example.AZ” groups.com through team9@example. Examples: User Name: user1@example. • Substring Match: The address or organization name must contain the text of the rule as a substring.com. Directory Sync will attempt to add the user and fail. See above for examples for these rules. LDAP Configuration The LDAP Configuration section configures how Directory Sync connects to your LDAP directory server and generates your LDAP user list for comparison. You may need to collect information from your LDAP directory server before you can enter details in this section. Users that meet the requirements for an exclusion filter will not be deleted. Configuration 69 . If they are listed on the LDAP server.Exclusion Rule Setting Description Exclusion Rule The text of the match or regular expression to compare. If your LDAP server supports an SSL connection and you wish to use it. Example: Standard Host Name Enter the domain name or IP address of your LDAP directory server.6 .example.1. Make sure to select the correct type for your LDAP server.1.com. LDAP Connection Setting Description Server Type The type of LDAP server you are syncing. The default is 389.22. Port Specify the host port.LDAP Connection Settings Specify your LDAP connection and authentication in this page. GADS interacts with each type of server slightly differently. Example: ad. choose Standard LDAP. Otherwise. choose LDAP + SSL. or 10.0. Example: 389 70 Release 3. Example: MS Active Directory Connection Type Choose whether to use an encrypted connection. Synchronizing org units is optional.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. Configuration Manager will connect to your LDAP server and attempt to log in.dc=ad. to verify the settings you entered. include the domain for the user as well.ou=sales. select Simple. LDAP Org Units The LDAP Org Units section configures how Directory Sync synchronizes your LDAP org hierarchy with your Google Apps org units. but move users between existing Organizations” in General Settings. This user should have read and execute permissions for the whole subtree. Example: swordfishX23 Passwords are stored in an encrypted format. select Anonymous. Do not include spaces between commas. If you don’t know the Base DN. Example: ou=test. consult your LDAP administrator or check an LDAP browser.ou=melbourne. You may need to collect information from your LDAP directory server before you can enter details in this section. If you set “Do not create or delete Google Organizations. Otherwise. dc=com Test Connection Once you have configured LDAP Authentication settings. see “User Search Rules” on page 88. Example: admin1 Password Enter the password for the authorized user. Example: Simple Authorized User Enter the user who will connect to the server.dc=example. org units will not be synchronized from LDAP. For more information. If your LDAP directory server requires a domain for login. Base DN Enter the Base DN for the subtree to synchronize. Configuration 71 . click Test Connection. You can still specify which users go in org units in the LDAP User Sync rules. the first rule takes precedence. Edit: Click the notepad icon to edit the settings of a mapping.. but users can still be added to existing Google Apps organizations as specified in your user search rules. Specify how OUs on your LDAP server correspond to Org Units in Google Apps.0. Add mappings for top-level Org Units. To add a mapping. Delete: Click the X icon to delete a mapping. If you would like one mapping to take priority over another. . On the list of mappings.6 . Mappings are processed in the order listed. this page is an empty list. Google Apps organizations aren’t synced with your LDAP server. 72 Release 3. GADS will add and delete organizations in Google Apps to match your LDAP organization structure according to the mappings you specify. checkbox isn’t checked. and Directory Sync will automatically map sub-organizations on your LDAP directory server to Google Apps Org Units with the same name. If the checkbox is checked. move that mapping up using the up arrow icon on this page. If two rules contradict each other. you can change existing mappings: • • • Reorganize: Click the up arrow or down arrow icon to change the order of mappings.Org Unit Mappings This shows a list of rules used when generating the LDAP org units. Add specific rules to override sub-organization mappings. If the Do not create or delete Google Organizations. In a new configuration. click Add Mapping.. dc=com (Google Apps) Name: Detroit Sample Mapping with Exceptions: Departments In this example.dc=example.dc=com (Google Apps) Name: Melbourne Second Rule: • • (LDAP) DN: ou=detroit.dc=com (Google Apps) Name: Users Second Rule (exception for IT): • • (LDAP) DN: ou=it. Most of the Google Apps org unit hierarchy will match the same hierarchy.dc=example.dc=ad.dc=example. and Executives will synchronize to a separate org unit First Rule (general case for most OUs): • • (LDAP) DN: ou=users.ou=users. an LDAP directory server has an organizational hierarchy split between two office locations: Melbourne and Detroit.ou=users. First Rule: • • (LDAP) DN: ou=melbourne. an LDAP directory server has an organizational hierarchy split based on different departments: Sales. but the IT team will synchronize to the root org unit. Support.dc=ad. IT and Executives.dc=ad. Marketing.Examples of Mapping Listed below are samples of common mappings. Sample Mapping: Multiple Locations In this example. under the Users group.dc=example.dc=example. HR. Note that the exact text of these rules will vary based on your needs.dc=com (Google Apps) Name: Executives Configuration 73 .dc=com (Google Apps) Name: / Third Rule (exception for Executives): • • (LDAP) DN: ou=executives. The Google Apps org unit hierarchy will match the same hierarchy.dc=ad.dc=ad. Example: Melbourne 74 Release 3.Add Mapping To add a new search rule. enter a single forward slash /.6 .dc=ad. Specify the following: Mapping Setting Description (LDAP) DN The Distinguished Name (DN) on your LDAP directory server to map. Example: ou=melbourne.dc=example. click Add Mapping.0. To add users to the default Organization in Google Apps.dc=com (Google Apps) Name The name of the org unit in Google Apps to map. This page shows the list of search rules. Search rules are processed in the order listed. move that search rule up using the up arrow icon on this page.Org Unit Search Rules This shows a list of rules used when generating the LDAP org units. all org units that match these search rules will be added to the Google Apps org unit hierarchy. Configuration 75 . Edit: Click the notepad icon to edit the settings of a search rule. Delete: Click the X icon to delete a search rule. In a new configuration. you can change existing rules: • • • Reorganize: Click the up arrow or down arrow icon to change the order of search rules. By default. and all org units that do not match these search rules will be removed. click Add Search Rule. If you would like one search rule to take priority over another. If two rules contradict each other. the first rule takes precedence. On the list of Search Rules. You can change this behavior with exclusion filters. this will be an empty list. To add a search rule. One-level provides a limited search that will avoid causing extreme load for very large organizations. If left blank. and anything under those objects. • • Example: Subtree 76 Release 3. This field is optional. Object: Only objects directly matched by the search.6 .0. It allows a search only on the specified object. Subtree gives the broadest search.Object is rarely used except with very complex LDAP searches. your Org Units will not contain a description when created. Choose which option to use: • Subtree: All objects matched by the search. click Add Search Rule. but for very large organizations this can be load-intensive and cause system problems. and anything one level underneath them. Does not look further than one level. recursively. No recursion of any kind. One-level: All objects matched by the search. Specify the following: LDAP Org Unit Search Rule Setting Description Org Unit Description Attribute An LDAP attribute that contains the description of each org unit.Add Org Unit Search Rule To add a new search rule. Example: description Scope This determines where in the LDAP directory this rule applies. For more information about LDAP search filters. In most cases. This rule is a standard LDAP query. Example: ou=powerusers.dc=com Base DN Org Unit Exclusion Rules If you have any org units on your LDAP directory server that match your search rules but should not be added to Google Apps.dc=example.dc= ad. add an LDAP org unit exclusion rule.ou=melbourne. you can leave this field blank and use the Base DN specified in the LDAP Connection page. This field is optional. The Base DN (Distinguished Name) to use for this search rule. Configuration 77 . specify an alternate base DN. see “About LDAP Queries” on page 45.ou=test. If you want this rule to use a different Base DN than the default. This will override the default Base DN you specified in LDAP Connection. and allows sophisticated logic and complex rules for searching.LDAP Org Unit Search Rule Setting Description Rule The search rule for org unit sync to match.ou=sales. Some examples of reasons for LDAP org unit exclusion rules: • • • • Internal org units that do not have outside email addresses OUs for printers. click Add Exclusion Rule. In a new configuration. Note that the exact text of these rules will vary based on your needs. add a separate rule for each org unit. Example LDAP Org Unit Exclusion Rules Listed below are samples of common exclusion rules. this will be an empty list. Delete: Click the X icon to delete the exclusion filter. Edit: Click the notepad icon to edit the settings of an exclusion filter.0. and other non-user resources Test OUs on your LDAP directory server OUs that are not participating in a pilot program Note: To exclude individual org units. To add exclusion filters. 78 Release 3. you can change existing filters as follows: • • • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. This page shows the list of exclusion filters. In the list of Exclusion Filters.6 . conference rooms. All the test users follow the same name pattern: ou=internaltextX.dc=example. Add a separate rule for each special LDAP mailing list.dc=example.dc=ad. where X is a number.u=finance.dc=com Second rule: • • Match Type: Exact Match Rule: ou=confidential.dc=ad. but they are only used for internal load testing. The defunct OUs all have “stpaul” in the DN.dc=example. First rule: • • Match Type: Exact Match Rule: ou=earlystatements. • Match Type: Regular Expression Configuration 79 .Sample Substring Match: Defunct OUs Several organizational units are no longer in use because two nearby offices combined together.ou=legal.ou=users. • • Match Type: Substring Match Rule: stpaul Sample Exact Match: Secure OUs Three specific organizational units are top security and should not be synchronized.dc=ad.dc=com.dc=com Sample Regular Expression Match: Internal Testing OUs About thirty extra OUs are listed in the LDAP directory server.ou=users. • Org Unit DN: Base the exclusion rule on the Distinguished Name (DN) of the org unit to exclude. • • Substring Match: The organization unit DN must contain the text of the rule as a substring.6 . Match Type The type of rule to use for the filter. • Exact Match: The org unit DN must match the rule exactly. Note: In many cases.Rule: ou=internal-test[0-9]*. Substring Match yields better results than Exact Match. 80 Release 3.dc=ad. Specify the following: Exclusion Rule Setting Description Exclude Type This Exclude Type is always Org Unit DN.dc=example. with the domain name added on.0.dc=com Add Rule Click Add Exclusion Rule to exclude an org unit in your LDAP server from synchronization. Regular Expression: The org unit DN must match the regular expression specified. Behavior of this field depends on the Match Type you choose. Even if you only use Google Apps Directory Sync to sync groups and not users (See “Synchronization options” on page 140). You may need to collect information from your LDAP directory server before you can enter details in this section. the users must be read in.Exclusion Rule Setting Description Rule The match string or regular expression for the exclusion rule. in order to resolve Reference Attributes for group members or group owners. you can’t add the same user for 5 days.dc=ad. Examples: • Exact Match: ou=test.dc=exam ple. WARNING: After you delete a user. Important: You must add at least one LDAP User Sync rule to run Google Apps Directory Sync. Configuration 81 .dc=com • • Substring Match: ou=test Regular Expression: ou=printer.* User Accounts The User Accounts section configures how Google Apps Directory Sync generates your LDAP user list for comparison.ou=sales. Addresses that contain this string (or match this regular expression) will not be added to Google Apps. and will be deleted if found. This determines which users are synchronized and added in Google Apps.ou=melbourne. 0.User Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP user list. LDAP User Attribute Setting Description Email Address Attribute The LDAP attribute that contains a user’s primary email address. Alias Address Attribute (if needed) One or more attributes used to hold alias addresses. Example: The default is mail. These addresses will be added into Google Apps as nicknames of the primary address listed in the Email Address Attribute field. Example: proxyAddresses 82 Release 3.6 . including passwords. Don’t suspend or delete Google Apps admins not found in LDAP If checked. prevents GADS from suspending or deleting administrator accounts found in Google Apps that don’t exist in your LDAP server. Additional User Attributes LDAP Extended Attributes are optional LDAP attributes that you can use to import additional information about your Google Apps users. Configuration 83 . This is the default setting. Active users in Google Apps will be deleted if they are not in your LDAP.LDAP User Attribute Setting Description Google Apps Users Deletion / Suspension Policy Options for deleting and suspending users. • Suspend Google Apps users not found in LDAP. including suspended users. instead of deleting them. Delete active and suspended users not found in LDAP. Suspended users are left alone. Available options: • Delete only active Google Apps users not found in LDAP (suspended users are retained). All users in Google Apps will be deleted if they are not in your LDAP. but suspended users are left alone. Active users in Google Apps will be suspended if they are not in your LDAP. If you user multiple attributes. If you do not specify an attribute. this is usually the last name.6 .All attributes are optional. (In the English language.0. this is usually the first name. You can also use multiple attributes for the given name. 84 Release 3. LDAP Extended Attribute Setting Description Given Name Attribute An LDAP attribute that contains each user’s given name. place each attribute field name in square brackets.) This is synchronized with the user’s name in Google Apps. Directory Sync will not import this information.[cn]-[ou] Family Name Attribute An LDAP attribute that contains each user’s family name. Examples: givenName. Examples: surname.[cn]-[ou] Mailbox Quota Size Attribute This field is not implemented.) This is synchronized with the user’s name in Google Apps. (In the English language. This option is recommended if you want to manage user passwords on your LDAP server. Example: Only for new users Password Attribute An LDAP attribute that contains each user’s password. Use this option if you want your users to manage their passwords in Google Apps. you must also provide a value for the Password Changed Time Attribute.LDAP Extended Attribute Setting Description Synchronize Passwords Indicates which passwords Directory Sync will synchronize. • For new and existing users: Directory Sync always synchronizes all user passwords. it synchronizes that user’s password. your users’ Google Apps passwords will be synchronized to match their LDAP passwords. Note: If you are using a temporary or one- time password for new users. If you set this attribute. The password field supports string or binary attributes. Existing passwords are not synced. • Only changed passwords: Directory Sync only synchronizes passwords that have changed since your previous sync. use this option. Options are: • Only for new users: When Directory Sync creates a new user. Existing passwords on Google Apps are overwritten. This option is appropriate for managing user passwords on your LDAP server. Example: CustomPassword1 Configuration 85 . Note: If you use this option. but it is less efficient than the Only changed passwords option. 6 . This field supports string attributes. Example: PasswordChangedTime 86 Release 3.0. Your LDAP server updates this attribute whenever a user changes their password.LDAP Extended Attribute Setting Description Password Changed Time Attribute An LDAP attribute that contains a timestamp indicating the last time a user’s password was changed. Use this field only if you select the Only changed passwords option for the Synchronize Passwords field. Simulate sync and full sync logs show the password as a SHA1 password. when you save and reload the configuration resets to the default of SHA1. Consider setting a default password for new users and requiring users to change passwords on first login. MD5: Passwords in your LDAP directory server use MD5 encryption. Active Directory and Lotus Domino directory servers do not store passwords in any of these formats. If you leave the Password Attribute field blank. Check your LDAP directory server with a directory browser to find or change your password encryption. If passwords in your LDAP directory are Base64-encoded or plaintext. Plaintext: Passwords in your LDAP directory server are not encrypted. or transmits passwords unencrypted. Example: SHA1 Configuration 87 . Note that some password encoding formats are not supported.LDAP Extended Attribute Setting Description Password Encryption Method The encryption algorithm that the password attribute uses. then immediately encrypt the password using SHA1 encryption and synchronize with Google Apps. Directory Sync will read the password attribute as unencrypted text. Use this field only if you also specify a Password Attribute. logs. Directory Sync immediately encrypts them with SHA1 encryption and synchronizes them with Google Apps. Note: Directory Sync never saves. • • • • SHA1: Passwords in your LDAP directory server use SHA1 encryption. Base64: Passwords in your LDAP directory server use Base64 encoding. By default. This allows you to set an initial password. be sure to enable “Force new users to change password” so that users will not keep their default password. 88 Release 3. either from an LDAP attribute or by specifying a default password for new users. Example: swordfishX2! User Search Rules This shows a list of rules used when generating the LDAP user list.0. If the user does not have a password in the password attribute. Important: If you enter a default password here. that must be changed the first time the user logs on to their Google Apps account. new users must change passwords the first time they log in to Google Apps. Directory Sync will use the default password. Default password for new users Enter a text string that will serve as the default password for all new users.6 .LDAP Extended Attribute Setting Description Force new users to change password If checked. Use this option if you are using temporary or one-time passwords. you can change existing rules: • • • Reorganize: Click the up arrow or down arrow icon to change the order of search rules. 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. On the list of Search Rules. removing access to any OUs on your LDAP directory server that you do not want to synchronize. You can change this behavior with exclusion filters. To add a search rule. This page shows the list of search rules. In a new configuration. click Add Search Rule. Configuration 89 . move that search rule up using the up arrow icon on this page. Add Search Rule To add a new search rule. If two rules contradict each other.By default. Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP directory. If you would like one search rule to take priority over another. Delete: Click the X icon to delete a search rule. Depending on your General Settings. limit the LDAP administrator authority on your LDAP directory server. Instead. Search rules are processed in the order listed. Edit: Click the notepad icon to edit the settings of a search rule. this will be an empty list. the first rule takes precedence. you may see different versions of the Add LDAP User Sync Rule menu. click Add Search Rule. This option only shows if you have Synchronization of Google Organizations set to “Sync LDAP Org Units” in General Settings.0. Options include: • Org Unit based on Org Units Mappings and DN. Use for an LDAP query that returns deleted or suspended users on your LDAP directory server. Directory Sync will add the users to the root level org unit in Google Apps. Directory Sync will add new users that do not yet exist in Google Apps. Suspended users will not show up in your Global Address List. Add users to the org unit that maps to the user’s DN on your LDAP server. Org Unit Name. Enter the attribute in the text field. The new users are added as suspended users. leave this unchecked. For more information. This is based on your Org Mappings. Add each user to the org unit with the name specified in an attribute on your LDAP directory server. but move users between existing Organizations” in General Settings. Add all users that match this rule to the same Google Apps Org Unit. This will show in the LDAP User Sync list as [derived]. Specify which Google Apps org unit should contain users that match this rule. Directory Sync suspends users that already exist in Google Apps. see “User Accounts” on page 81.Specify the following: LDAP User Sync Setting Description Place users in the following Google Apps Org Unit This option only shows if you have Synchronization of Google Organizations set to “Sync LDAP Org Units” or “Do not create or delete Google Organizations.6 . User data is retained. Example: Users • Org Unit name defined by this LDAP Attribute. If you are importing active users with this rule. and are not active users. If the org unit specified does not exist. 90 Release 3. Example: extensionAttribute11 • Suspend these users in Google Apps Suspend all users that match this LDAP user sync rule. Specify the org unit in the text field. Subtree gives the broadest search.Object is rarely used except with very complex LDAP searches. Choose which option to use: • Subtree: All objects matched by the search. • • Example: Subtree Rule The search rule for user sync to match. see “About LDAP Queries” on page 45. This rule is a standard LDAP query. and anything under those objects.LDAP User Sync Setting Description Scope This determines where in the LDAP directory this rule applies. One-level: All objects matched by the search. Object: Only objects directly matched by the search. recursively. 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) Configuration 91 . For more information about LDAP search filters. One-level provides a limited search that will avoid causing extreme load for very large organizations. No recursion of any kind. Does not look further than one level. and allows sophisticated logic and complex rules for searching. It allows a search only on the specified object. and anything one level underneath them. but for very large organizations this can be load-intensive and cause system problems. Example: ou=powerusers.dc=com User Exclusion Rules If you have any users on your LDAP directory server that match your search rules but should not be added to Google Apps. specify an alternate base DN.0.ou=melbourne. you can leave this field blank and use the Base DN specified in the LDAP Connection page. This field is optional. If you want this rule to use a different Base DN than the default. This will override the default Base DN you specified in LDAP Connection. Some examples of reasons for LDAP user exclusion rules: • • • • Internal users who do not have outside email addresses Printers. and other non-user resources Test users on your LDAP directory server Users who do not want a Google Apps mailbox 92 Release 3.6 .dc=example.ou=sales. In most cases.ou=test. add an LDAP user exclusion rule.LDAP User Sync Setting Description Base DN The Base DN (Distinguished Name) to use for this search rule.dc= ad. conference rooms. click Add Exclusion Rule. However. The rule looks for that substring. not LDAP settings. this is an empty list. Sample Substring Match: Printers In this example. Note: To exclude individual users. Example LDAP User Exclusion Rules Listed below are samples of common exclusion rules. the printers all have the word “printer” in the name. Note that the exact text of these rules will vary based on your needs. Edit: Click the notepad icon to edit the settings of an exclusion filter.Exclusion rules are based on string values and regular expressions. printers are listed as LDAP users and would match the LDAP query given. This page shows the list of exclusion filters. • • • Match Type: Substring Match Exclude Type: Primary Address Rule: printer Configuration 93 . To add exclusion filters. In a new configuration. you can change existing filters as follows: • • • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. In the list of Exclusion Filters. add a separate rule for each user. Delete: Click the X icon to delete the exclusion filter. but they are only used for internal load testing. and all test users are in the same domain.6 .com Add Exclusion Rule Click Add Exclusion Rule to exclude a user or organization in your LDAP server from synchronization. • • Match Type: Regular Expression Rule: internal-test[0-9]*@example.Sample Exact Match: Opt-Out Users Two users have opted out of Google Apps and should not be synchronized. All the test users follow the same name pattern: internaltestX. Add a separate rule for each special user.0. where X is a number. 94 Release 3. 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. com would exclude internalhelpdesk@example. Rule The match string or regular expression for the exclusion rule. Example: maria (if you are using the domain example.com. Note: In many cases. Exclude Type What kind of LDAP data to exclude. Addresses that contain this string (or match this regular expression) will not be added to Google Apps.*@example. and will be deleted if found.com. The interface displays this choice as ADDRESS. Example: internal. create two exclusion rules. Example: “test” would exclude testadmin@example. Examples: • • • Exact Match: maria Substring Match: internal-list Regular Expression: internal.com. The interface displays this choice as ALIAS. with the domain name added on. Substring Match yields better results than Exact Match.com and
[email protected]) would exclude only the user
[email protected] the following: Exclusion Rule Setting Description Match Type The type of rule to use for the filter. Alias Address: Directory Sync will exclude aliases that match this rule. • Exact Match: The address must match the rule exactly.com and salestest1@example. • Primary Address: Directory Sync will exclude primary addresses that match this rule. • Substring Match: The address or organization name must contain the text of the rule as a substring. Behavior of this field depends on the Match Type you choose. • If you want to exclude both primary addresses and alias addresses.*@example.com Configuration 95 . • Regular Expression: The address or organization must match the regular expression specified. 0. click Add Search Rule. You may need to collect information from your LDAP directory server before you can enter details in this section.6 . this is an empty list. Google Apps Directory Sync can synchronize groups with your LDAP directory server mailing lists. Google Groups for Enterprise are similar to LDAP mailing lists. you can let users create their own groups. This page shows the list of LDAP Group Sync rules. Directory Sync will automatically detect groups that users create. Videos and Calendars. To add mail lists. You can also use groups to share content. In a new configuration. User-Defined Groups and Google Apps Directory Sync If you have enabled the Groups (user-managed) service in the Google Apps control panel. including Google Docs. and will not delete or overwrite them. Sites. Group Search Rules Groups in Google Apps are a special kind of email address that direct mail to many addresses at once. These groups are not centrally administered and are controlled by your users. The LDAP Settings section configures how Google Apps Directory Sync generates a list of groups from your LDAP directory server. 96 Release 3. and allow users to send email to multiple recipients with a single email address.Groups Set up synchronization for Google Groups for Enterprise in the LDAP Groups page. Literal For two entries (Member and Owner) you have a choice of two attributes.OU=example. and which attributes to use for groups information. Attribute Fields: Reference vs. Delete: Click the X icon to delete the exclusion filter.com then use the Literal attribute.OU=com then use the Reference attribute. which contains information on which LDAP objects to synchronize. To determine which to use. The first tab you see is the LDAP tab. you can change existing filters as follows: • • • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. If the field contains a distinguished name such as CN=listowner. a Reference attribute or a Literal attribute. use an LDAP browser to look at the contents of the field you want to use: • • If the field contains an email address such as listowner@example. Add Group Search Rule Filter (LDAP) Click Add Search Rule to synchronize one or more addresses as mailing lists.OU=administrators. Edit: Click the notepad icon to edit the settings of an exclusion filter. Enter only one of them. To view the groups you have in Google Apps. see the Google Apps control panel.In the list of Mail List rules. Configuration 97 . No recursion of any kind.dc=com Group Email Address Attribute An LDAP attribute that contains the email address of the group.ou=test.ou=sales. This allows sophisticated logic and complex rules for searching. One-level: All objects matched by the search.dc=example. It allows a search only on the specified object.ou=melbourne. see “About LDAP Queries” on page 45. This will override the default Base DN you specified in LDAP Connection. One-level provides a limited search that will avoid causing load for very large organizations. and anything one level underneath them. This will become the group email address in Google Apps. Subtree gives the broadest search.Specify the following: LDAP Group Rule Setting Description Scope Where to apply the mail list rule. • • Example: Subtree Rule The LDAP query for Group Sync to match. Example: ou=powerusers. recursively. Example: (objectclass=dominoGroup) Base DN The Base DN (Distinguished Name) to use for this search rule. Choose which option to user: • Subtree: All objects matched by the search. and anything under those objects. Object: Only objects directly matched by the search. Does not look further than one level.0. Object is rarely used except with very complex LDAP searches.6 .dc= ad. but for very large organizations this can be load-intensive and cause system problems. This field is optional. Example: mail 98 Release 3. In most cases. you can leave this field blank and use the Base DN specified in the LDAP Connection page. specify an alternate base DN. For more information about LDAP search filters. If you want this rule to use a different Base DN than the default. Google Apps Directory Server adds each member to the group in Google Apps. 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. Example: extendedAttribute6 Group Description Attribute Member Reference Attribute (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.LDAP Group Rule Setting Description Group Display Name Attribute An LDAP attribute that contains the display name of the group.) Owner Reference Attribute An attribute that contains the DN of mailing list members in your LDAP directory server. Example: owner Configuration 99 . Example: memberUID An attribute that contains the full email address of mailing list members in your LDAP directory server. Google Apps Directory Server adds that address as the group owner in Google Apps. An LDAP attribute that contains the full-text description of the group. This will become the group description in Google Apps.) Member Literal Attribute (Either this field or Member Reference Attribute is required. Example: memberaddress An attribute that contains the DN of each group’s owner. This field is optional. This will be used in the display to describe the group. This field is optional. and does not need to be a valid email address. 6 . Text to add at the end of each user name for group members. If you leave this blank. Text to add at the beginning of each user name for group owners. they will be replaced with this. 100 Release 3. list them here. user names or owner names in Google Apps. LDAP Group Rule Setting Description Group Name Prefix Text to add at the beginning of each group name.0. Directory Sync will remove spaces and concatenate group names. Text to add at the end of each user name for group owners. 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. Example: underscore (_) User Name Prefix User Name Suffix Owner Name Prefix Owner Name Suffix Text to add at the beginning of each user name for group members.Edit LDAP Group Rule (Prefix-Suffix) If you need Directory Sync to add a prefix or suffix to group names. Group Exclusion Rules You can exclude particular addresses from being imported as groups. and other non-user resources Mailing lists that should be treated as individual users. Edit: Click the notepad icon to edit the settings of an exclusion filter. To add exclusion filters. This might include: • • • Internal mailing lists that do not have outside email addresses Printers. not LDAP settings. list them here. If you have any entries in your directory server that match a mail list rule. with separate mailboxes and settings. In a new configuration. conference rooms. This page shows the list of exclusion filters. click the Add Rule button at the bottom of the screen. Delete: Click the X icon to delete the exclusion filter. Configuration 101 . 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. but should not be treated as a mailing list. this will be an empty list. Exclusion rules are based on string values and regular expressions. Example Group Exclusion Rules Listed below are samples of common exclusion rules. All the test users follow the same name pattern: internaltestX. 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. Sample Substring Match: Defunct Mailing Lists Several mailing lists are no longer in use because two nearby offices combined together. • • 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. Note that the exact text of these rules will vary based on your needs. • • Match Type: Regular Expression Rule: internal-test[0-9]*@example.com 102 Release 3. Add a separate rule for each special LDAP mailing list. The defunct lists all have “stpaul” in the address.6 . and all test users are in the same domain.0. where X is a number. but they are only used for internal load testing. Member Name: Do not sync any user whose primary address matches this rule from any groups. Regular Expression: The address or organization must match the regular expression specified. • • Match Type The type of rule to use for the filter. The interface displays this choice as ADDRESS. The interface displays this choice as MEMBER_NAME. • • Exact Match: The address or organization name (minus domain name) must match the rule exactly. • Exclusion Rule The text of the match or regular expression to compare. • User Name: Do not sync any user whose primary address matches the rule.Add Group Exclusion Rule Click Add Exclusion Rule to prevent an address from being treated as a mailing list. Group Name: Do not sync any group which has a name that matches the rule. The interface displays this choice as NESTED_GROUP_NAME. Specify the following: Exclusion Rule Setting Description Type Sets the type of exclusion filter to create: User Name. Substring Match: The address or organization name must contain the text of the rule as a substring. Group Name. Addresses that meet the requirements for an exclusion filter will not be added as Google Apps groups. Configuration 103 . or Member Name. User Profiles Set up synchronization for Google Apps user profiles in the User Profiles page. User Profiles contain extended information about users, such as phone number and title. The User Profiles section configures how Google Apps Directory Sync generates user profile information from your LDAP directory server. You may need to collect information from your LDAP directory server before you can enter details in this section. User Profile Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP user profiles. 104 Release 3.0.6 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 Company name Assistant’s DN LDAP attribute that contains a user’s job title. LDAP attribute that contains a user’s company name. LDAP attribute that contains the LDAP Distinguished Name (DN) of the user’s assistant. LDAP attribute that contains the LDAP Distinguished Name (DN) of the user’s direct manager. LDAP attribute that contains a user’s department. LDAP attribute that contains a user’s office location. LDAP attribute that contains a user’s Employee ID number. LDAP attribute that contains a user’s home page or other website. LDAP attribute that contains a user’s work phone number. LDAP attribute that contains a user’s home phone number. LDAP attribute that contains a user’s fax number. LDAP attribute that contains a user’s personal mobile phone number. LDAP attribute that contains a user’s work mobile phone number. LDAP attribute that contains a work phone number for a user’s assistant. LDAP attribute that contains the street address portion of a user’s primary work address. LDAP attribute that contains the P.O. Box of a user’s primary work address. Manager’s DN Department Office location Employee ids Websites Work phone numbers Home phone numbers Fax phone numbers Mobile phone numbers Work mobile phone numbers Assistant’s Number Street Address P.O. Box Configuration 105 LDAP Profile User Attribute Description City State/Province ZIP/Postal Code Country/Region LDAP attribute that contains the city of a user’s primary work address. LDAP attribute that contains the state or province of a user’s primary work address. LDAP attribute that contains the ZIP code or Postal Code of a user’s primary work address. LDAP attribute that contains the country or region of a user’s primary work address. User Profile Search Rules This shows a list of rules used when determining which user profiles to import. Note: If you store your user profile information in the same place in your directory server as your users’ mail addresses, you may use the same sync rules for LDAP User Profiles as you did for LDAP User Sync. To use the same settings, add a new search rule and copy the same scope and rule text. By default, user profile information will be synchronized for all users that match these search rules will be added to the Google Apps user list. You can change this behavior with exclusion filters. 106 Release 3.0.6 Edit: Click the notepad icon to edit the settings of a search rule. this will be an empty list. you can change existing rules: • • • Reorganize: Click the up arrow or down arrow icon to change the order of search rules. Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP directory. Search rules are processed in the order listed.This page shows the list of search rules. To add a search rule. removing access to any OUs on your LDAP directory server that you do not want to synchronize. click the Add Search Rule button at the bottom of the screen. Delete: Click the X icon to delete a search rule. Add User Profile Search Rule To add a new search rule. In a new configuration. click Add User Profile Search Rule. Configuration 107 . Instead. limit the LDAP administrator authority on your LDAP directory server. On the list of Search Rules. No recursion of any kind.Object is rarely used except with very complex LDAP searches. but for very large organizations this can be load-intensive and cause system problems. • • Example: Subtree Rule The search rule for user profile sync to match. see “About LDAP Queries” on page 45. and anything under those objects. recursively. Choose which option to use: • Subtree: All objects matched by the search. This rule is a standard LDAP query. 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) 108 Release 3. For more information about LDAP search filters. Subtree gives the broadest search. Does not look further than one level. One-level: All objects matched by the search.This dialog box has the following fields LDAP User Profile Search Rule Field Description Scope This determines where in the LDAP directory this rule applies.6 . and anything one level underneath them. One-level provides a limited search that will avoid causing extreme load for very large organizations. It allows a search only on the specified object. Object: Only objects directly matched by the search.0. and allows sophisticated logic and complex rules for searching. dc=com User Profile Exclusion Rules If you have any existing user profile information in Google Apps that you do not want to synchronize. Configuration 109 . specify it here.LDAP User Profile Search Rule Field Description Base DN The Base DN (Distinguished Name) to use for this search rule.ou=test. This field is optional.ou=melbou rne.ou=sales. specify an alternate base DN. This will override the default Base DN you specified in LDAP Connection. click Add Exclusion Rule. this will be an empty list. To add exclusion filters. you can leave this field blank and use the Base DN specified in the LDAP Connection page. In a new configuration. In most cases. If you want this rule to use a different Base DN than the default. Example: ou=powerusers. This page shows the list of exclusion filters.dc=ad.dc=example. where X is a number. Note that the exact text of these rules will vary based on your needs. you can change existing filters as follows: • • • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters.com Sample Regular Expression Match: Test Users About five hundred test users are listed in LDAP. Example User Profile Exclusion Rules Listed below are samples of common exclusion rules.In the list of Exclusion Filters. Edit: Click the notepad icon to edit the settings of an exclusion filter. and all test users are in the same domain. First rule: • • Match Type: Exact Match Rule: atif@example. Delete: Click the X icon to delete the exclusion filter. printers are listed as LDAP users and would match the LDAP query given.com Second rule: • • Match Type: Exact Match Rule:
[email protected] 110 Release 3. • • 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. The rule looks for that substring. However. the printers all have the word “printer” in the name. • • Match Type: Regular Expression Rule: internal-test[0-9]*@example. All the test users follow the same name pattern: internaltestX. Add a separate rule for each special user.0. Sample Substring Match: Printers In this example. but they are only used for internal load testing.6 . com. • Substring Match: The address or organization name must contain the text of the rule as a substring. Example: “test” would exclude
[email protected]. • Regular Expression: The address or organization must match the regular expression specified. • Exact Match: The address must match the rule exactly. Example:
[email protected] Exclusion Rule Click Add Exclusion Rule to exclude a user or organization in your LDAP server from synchronization.*@example.com would exclude only the user
[email protected] would exclude
[email protected] and
[email protected] and salestest1@example. Specify the following: Exclusion Rule Setting Description Match Type The type of rule to use for the filter. Example: internal.com. Configuration 111 . Behavior of this field depends on the Match Type you choose.Exclusion Rule Setting Description Rule The match string or regular expression for the exclusion rule.com Substring Match: listinternal Regular Expression: internal. Shared Contacts contain information about contacts. such as name.6 . Examples: • • • Exact Match:
[email protected]. phone number and title. email address.*@example. Shared Contacts correspond to a Global Address List (GAL) in Microsoft Active Directory and other directory servers. Shared Contacts in Google Apps are contacts that any user can see and use. and will be deleted if found.com Shared Contacts Set up synchronization for Google Apps shared contacts in the LDAP Shared Contacts page. Addresses that contain this string (or match this regular expression) will not be added to Google Apps. You may need to collect information from your LDAP directory server before you can enter details in this section. The Shared Contacts section configures how Google Apps Directory Sync generates shared contacts information from your LDAP directory server. You can see Shared Contacts in Google Apps by going to your Inbox and clicking the Contacts link. 112 Release 3. synchronize this information using Shared Contacts. so that pilot users will see the address of other users in autocomplete. autocomplete will suggest possible addresses that match what the user has typed. consider adding other users as Shared Contacts. Your Shared Contacts in Google Apps is a domain-wide repository of contacts. Adding Shared Contacts means that users will see the address in the suggestion list even if they have not mailed that contact before. it may take up to 24 hours for the changes to appear in Google Apps. • • Below are some of the most common reasons to import Shared Contacts: • Add groups and outside addresses to autocomplete. If you are adding a small number of users for a pilot program. This list of possible recipients comes from three places: addresses that the user has mailed before. User addresses in your domain will show up in autocomplete. Chooser. similar to an address list. • • Important: Shared Contacts do not show immediately. However. If your users want to see rich contact information from your directory server for their contacts (such as postal addresses. users (but not groups) in the domain. Users will see this additional information in the Contacts page after they have added the contact manually.How to use Shared Contacts Shared Contacts information is similar to a Global Address List in a directory server. This list of possible recipients comes from three places: addresses that the user has mailed before. if a user sends mail to a contact. While a user types a recipient address in Google Apps Mail. Shared Contacts are visible to a Google Apps user in three places: • Autocomplete. Configuration 113 . available to all users. companies. the Chooser will present a list of possible recipients. users (but not groups) in the domain. After you synchronize Shared Contacts. Google Apps will also add information from Shared Contacts. Provide supplemental directory information to users. groups and outside addresses are not visible in autocomplete. and titles). Shared Contacts are not visible when a user clicks the Contacts tab. When a user click on the To field while composing a Google Apps Mail message. Give pilot users access to all users for autocomplete. or adds a contact. However. and Shared Contacts. Contacts information. and Shared Contacts. Create LDAP sync rules to import any groups or outside addresses you want your users to see when using autocomplete. phone numbers. or sent mail to that contact’s address. LDAP attribute that contains a contact’s company name.Shared Contact Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP shared contacts. LDAP attribute that contains the LDAP Distinguished Name (DN) of the contact’s direct manager. This field becomes the ID of the contact. Choose an attribute present for all your contacts that is not likely to change. Manager’s DN 114 Release 3.6 .0. The fields are as follows. and which is unique for each contact. LDAP attribute that contains a contact’s job title. LDAP attribute that contains the LDAP Distinguished Name (DN) of the contact’s assistant. Examples: dn or contactReferenceNumber Full name Job title Company name Assistant’s DN LDAP attribute that contains a contact’s full name. LDAP Shared Contact Attribute Description Sync key An LDAP attribute that contains a unique identifier for the contact. LDAP attribute that contains the state or province of a contact’s primary work address. Box of a contact’s primary work address. LDAP attribute that contains a contact’s email address LDAP attribute that contains a contact’s employee ID number. LDAP attribute that contains a work phone number for a contact’s assistant.O. Country/Region Configuration 115 . LDAP attribute that contains the city of a contact’s primary work address.O. LDAP attribute that contains a contact’s personal mobile phone number. Box City State/Province ZIP/Postal Code LDAP attribute that contains a contact’s department. LDAP attribute that contains the P. LDAP attribute that contains a contact’s work phone number. LDAP attribute that contains the country or region of a contact’s primary work address.LDAP Shared Contact Attribute Description Department Office location Work email address Employee ids Websites Work phone numbers Home phone numbers Fax phone numbers Mobile phone numbers Work mobile phone numbers Assistant’s Number Street Address P. LDAP attribute that contains a contact’s office location. LDAP attribute that contains the street address portion of a contact’s primary work address. LDAP attribute that contains a contact’s fax number. LDAP attribute that contains a contact’s work mobile phone number. LDAP attribute that contains a contact’s home page or other website. LDAP attribute that contains the ZIP code or Postal Code of a contact’s primary work address. LDAP attribute that contains a contact’s home phone number. To add a search rule. Instead. limit the LDAP administrator authority on your LDAP directory server. shared contacts are synchronized for all contacts that match these search rules will be added to the Google Apps user list.6 . removing access to any OUs on your LDAP directory server that you do not want to synchronize. Delete: Click the X icon to delete a search rule. and removed for shared contacts that do not match these rules. 116 Release 3. this is an empty list. Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP directory. Edit: Click the notepad icon to edit the settings of a search rule. You can change this behavior with exclusion filters.Shared Contact Search Rules This shows a list of rules used when determining which shared contacts to import. This page shows the list of search rules. In a new configuration. On the list of Search Rules. By default.0. you can change existing rules: • • • Reorganize: Click the up arrow or down arrow icon to change the order of search rules. Search rules are processed in the order listed. click Add Search Rule. Does not look further than one level. but for very large organizations this can be load-intensive and cause system problems. click Add Shared Contact Search Rule. Choose which option to use: • Subtree: All objects matched by the search. Specify the following: LDAP Shared Contacts Search Rule Field Description Scope This determines where in the LDAP directory this rule applies. and anything one level underneath them. and anything under those objects. recursively. Object: Only objects directly matched by the search. No recursion of any kind. One-level: All objects matched by the search.Object is rarely used except with very complex LDAP searches. One-level provides a limited search that will avoid causing extreme load for very large organizations.Add Shared Contact Search Rule To add a new search rule. Subtree gives the broadest search. • • Example: Subtree Configuration 117 . It allows a search only on the specified object. see “About LDAP Queries” on page 45. add an LDAP shared contacts exclusion rule. you can leave this field blank and use the Base DN specified in the LDAP Connection page.0. and allows sophisticated logic and complex rules for searching. This rule is a standard LDAP query. If you want this rule to use a different Base DN than the default.ou=test. 118 Release 3. specify an alternate base DN.dc=example.6 . 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) Base DN The Base DN (Distinguished Name) to use for this search rule.dc=ad. This will override the default Base DN you specified in LDAP Connection.ou=sales.dc=com Shared Contact Exclusion Rules If you have any contacts on your LDAP directory server that match your search rules but should not be added to Google Apps. Example: ou=powerusers. This field is optional.LDAP Shared Contacts Search Rule Field Description Rule The search rule for shared contact sync to match. For more information about LDAP search filters.ou=melbou rne. In most cases. Note: To exclude individual contacts. you can change existing filters as follows: • • • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. Note that the exact text of these rules will vary based on your needs. This page shows the list of exclusion filters. In the list of Exclusion Filters.Exclusion rules are based on string values and regular expressions. First rule: • • Match Type: Exact Match Rule: atif@example. Edit: Click the notepad icon to edit the settings of an exclusion filter. Add a separate rule for each special user. To add exclusion filters. Sample Exact Match: Private Contacts Two contacts have opted out of Google Apps and should not be synchronized. Example Shared Contact Exclusion Rules Listed below are samples of common exclusion rules. add a separate rule for each contact. click Add Exclusion Rule. Delete: Click the X icon to delete the exclusion filter. this will be an empty list.com Configuration 119 . not LDAP settings. In a new configuration. Second rule: • • Match Type: Exact Match Rule: svetlana@example. where X is a number. and all test users are in the same domain. All the test users follow the same name pattern: internaltestX. but they are only used for internal load testing.com Sample Regular Expression Match: Test Contacts About five hundred test users are listed in LDAP. Specify the following: 120 Release 3.com Add Exclusion Rule Click Add Exclusion Rule to exclude a shared contact in your LDAP server from synchronization.0.6 . • • Match Type: Regular Expression Rule: internal-test[0-9]*@example. • Regular Expression: The address or organization must match the regular expression specified. You may need to collect information from your LDAP directory server before you can enter details in this section. Example: internal.com. Addresses that contain this string (or match this regular expression) will not be added to Google Apps. Example: maria@example.*@example. • Exact Match: The address must match the rule exactly. Behavior of this field depends on the Match Type you choose. and will be deleted if found.com would exclude
[email protected] and
[email protected]. Rule The match string or regular expression for the exclusion rule.com and salestest1@example. • Substring Match: The address or organization name must contain the text of the rule as a substring. Configuration 121 .com would exclude only the user maria@example. Examples: • • • Exact Match:
[email protected] LDAP Calendar Resources This section configures how Google Apps Directory Sync generates your LDAP calendar resources list for comparison.*@example. Example: “test” would exclude
[email protected] Substring Match: listinternal Regular Expression: internal.Exclusion Rule Setting Description Match Type The type of rule to use for the filter.com. This field must be unique. see the Google Code site article Developing a naming strategy for your calendar resources.Calendar Resource Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP calendar resources list.0. Important: Calendar Resources does not sync an LDAP attribute which contains spaces or characters such as the at sign (@) or colon (:). This is a field managed on your LDAP system. LDAP User Attribute Setting Description Resource Id The LDAP attribute or attributes that contain the ID of the calendar resource.6 . 122 Release 3. which may be a custom attribute. For more information on this calendar resource naming. you might use the following setting for Display Name: [city]-[building]-[floor]-Boardroom-[roomnumber] All LDAP attributes should be inside square brackets. see the Google Code site article Developing a naming strategy for your calendar resources. Example: [city]-[building]-[floor]-Boardroom[roomnumber] Important: Calendar Resources does not sync an LDAP attribute which contains spaces or characters such as the at sign (@) or colon (:). All attributes in the LDAP Calendar Resources Attributes page can include fixed strings and multiple LDAP attributes. All fixed text should be outside the square brackets. Description (optional) The LDAP attribute or attributes that contain a description of the calendar resource. and combine them into a single display name. floor. Configuration 123 . Example: [description] Note: Calendar Resource attributes use a different syntax than other Directory Sync attributes. building. For more information on this calendar resource naming. For instance.LDAP User Attribute Setting Description Display Name (optional) The LDAP attribute or attributes that contain the domain name for the calendar resource. Each LDAP attribute should be marked with square brackets. if you wanted to use the LDAP attributes city. and roomnumber from your LDAP directory. in the format in which it should appear in your Google Apps calendar resources. and all calendar resources that do not match these search rules will be removed. If two rules contradict each other. To add a search rule. On the list of Search Rules.Calendar Resource Search Rules This shows a list of rules used when generating the LDAP calendar resource list. all calendar resources that match these search rules will be added to the Google Apps calendar resources. click Add Search Rule. you can change existing rules: • • • Reorganize: Click the up arrow or down arrow icon to change the order of search rules. By default. In a new configuration. If you would like one search rule to take priority over another. this will be an empty list. You can change this behavior with exclusion filters. Delete: Click the X icon to delete a search rule.6 . the first rule takes precedence. 124 Release 3. move that search rule up using the up arrow icon on this page. Search rules are processed in the order listed. This page shows the list of search rules. Edit: Click the notepad icon to edit the settings of a search rule.0. It allows a search only on the specified object. but for very large organizations this can be load-intensive and cause system problems. One-level: All objects matched by the search. click Add Search Rule. Choose which option to use: • Subtree: All objects matched by the search. Object is rarely used except with very complex LDAP searches. No recursion of any kind. Subtree gives the broadest search. and anything one level underneath them. • • Example: Subtree Configuration 125 . and anything under those objects. Specify the following: LDAP User Sync Setting Description Scope This determines where in the LDAP directory this rule applies. recursively. Object: Only objects directly matched by the search.Add Search Rule To add a new search rule. One-level provides a limited search that will avoid causing extreme load for very large organizations. Does not look further than one level. 0.ou=melbourne. specify an alternate base DN.6 . this may be a helpful field to use. If your calendar resources are sorted in a particular OU. For more information about LDAP search filters.If you have any entities on your LDAP directory server that match your calendar resource search rules but should not be added to Google Apps as calendar resources. computers. and allows sophisticated logic and complex rules for searching. see “About LDAP Queries” on page 45. add an LDAP user exclusion rule.LDAP User Sync Setting Description Rule The search rule for calendar resources sync to match.dc=ad. This rule is a standard LDAP query. If you want this rule to use a different Base DN than the default. and other non-calendar resources Test resources on your LDAP directory server Obsolete calendar resources that are still listed in your LDAP directory 126 Release 3. Example: ou=Rooms. Example 1: To match all objects (this may cause load problems): objectclass=* Example 2: To match all users: • For OpenLDAP: (objectClass=inetOrgPerson) • For Active Directory: (objectClass=person) • for Lotus Domino: (objectClass=dominoPerson) Base DN The Base DN (Distinguished Name) to use for this search rule. This will override the default Base DN you specified in LDAP Connection. This field is optional.dc=com Calendar Resource Exclusion Rules .dc=example. Some examples of reasons for LDAP user exclusion rules: • • • • User accounts that seem to match calendar resource query patterns Printers. In a new configuration. Example Calendar Exclusion Rules Listed below are samples of common exclusion rules. printers are listed as LDAP resources and would match the LDAP query given. • • • Match Type: Substring Match Exclude Type: Calendar Resource Id Rule: printer Configuration 127 . Delete: Click the X icon to delete the exclusion filter. However. you can change existing filters as follows: • • • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. This page shows the list of exclusion filters. The rule looks for that substring. add a separate rule for each user. click Add Exclusion Rule. not LDAP settings. To add exclusion filters. the printers all have the word “printer” in the name. this will be an empty list. Note: To exclude individual calendar resources. Note that the exact text of these rules will vary based on your needs. Edit: Click the notepad icon to edit the settings of an exclusion filter.Exclusion rules are based on string values and regular expressions. Sample Substring Match: Printers In this example. In the list of Exclusion Filters. but they are only used for internal load testing. 128 Release 3.0.Sample Exact Match: Opt-Out Users Two conference rooms have been converted into offices and should not be imported as Google Apps calendar resources. First rule: • • • Match Type: Substring Match or Exact Match Exclude Type: Calendar Resource Display Name Rule: ConferenceRoom-BlueSkyMontana Second rule: • • • Match Type: Substring Match or Exact Match Exclude Type: Calendar Resource Display Name Rule: ConferenceRoom-BigPlains Sample Regular Expression Match: Test Users About five hundred test calendar resources are listed in LDAP.6 . where X is a number. All the test resources follow the same name pattern: internal-testX. • • • Match Type: Regular Expression Exclude Type: Calendar Resource Id Rule: internal-test[0-9]*@example. Add a separate rule for each special user. and all test users are in the same domain.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. com and salestest1@example. Calendar Resource Display Name: Directory Sync will exclude calendar resources where the Calendar Resource Display Name attribute specified in LDAP Calendar Resources Attributes matches this pattern. Example: “test” would exclude testadmin@example. create two exclusion rules. The interface displays this choice as CALENDAR_RESOURCE_DISPLAY_NAME • If you want to exclude both primary addresses and alias addresses. • Regular Expression: The address or organization must match the regular expression specified. The interface displays this choice as CALENDAR_RESOURCE_ID.Specify the following: Exclusion Rule Setting Description Match Type The type of rule to use for the filter.com and internal@example. Example: internal.com would exclude
[email protected]. Configuration 129 . Exclude Type What kind of LDAP data to exclude.*@example. Note: In many cases. • Calendar Resource Id: Directory Sync will exclude calendar resources where the Calendar Resource Id attribute specified in LDAP Calendar Resources Attributes matches this pattern. • Exact Match: The address must match the rule exactly.com) would exclude only the user maria@example. Substring Match yields better results than Exact Match.com. Example: maria (if you are using the domain example. with the domain name added on. • Substring Match: The address or organization name must contain the text of the rule as a substring.com. 0. Note: Notifications are sent by plain SMTP. Consider adding a notification to send mail to your own address. and possibly the addresses of any concerned parties in your company.6 . Calendar Resource Ids or Display Names that contain this string (or match this regular expression) will not be added to Google Apps. 130 Release 3.*@example. Behavior of this field depends on the Match Type you choose. not TLS.Exclusion Rule Setting Description Rule The match string or regular expression for the exclusion rule. Google Apps Directory Sync will send out a notification to one or more users.com Notifications You can set Configuration Manager so that every time synchronization occurs. and will be deleted if found. Examples: • • • Exact Match: NewYork-NYC-23-Conference-2 Substring Match: internal-list Regular Expression: internal. Directory Sync may be unable to send mail to external email addresses. enter the user name to use here. Example: 127.Specify the following: Notifications Setting Description Send notifications from address Enter the “From:” address for the notification mail.0. Depending on your mail server settings. then click the Add button. Enter any valid email address on any domain. Enter each recipient email address individually. Run a test notification to confirm that mail is sent properly. Example: dirsync@example. Example: mail. Directory Sync uses this mail server as a relay host.com Send notifications to the following addresses Notifications will be sent to all addresses on this list.example.com SMTP Relay Host The SMTP mail server to use for notifications. For instance. Recipients will see this address as the notification sender. Example: admin5 If the SMTP server you specify requires SMTP authentication. Example: dirsync-admins@example. you might use your own email address. Configuration 131 .com Username (if needed) Password (if needed) If the SMTP server you specify requires SMTP authentication. Note: You cannot use Google Apps as your SMTP Relay Host for Notifications.0. Example: swordfish Passwords are stored in the configuration file in an encrypted format.1 to run the mail server on the same machine. enter the Password to use here. • Extra details: Google Apps Directory Sync notifications will not include extra details and potentially extraneous information. you can limit how many users. This is recommended as a way to prevent accidental mass deletion or suspension. All checkboxes are optional. Warnings: Google Apps Directory Sync notifications will not include warning messages. groups. Errors: Google Apps Directory Sync notifications will not include error messages. and shared contacts Google Apps Directory Sync can delete or suspend during synchronization. Configuration Manager will connect to the SMTP server you specified and send a test notification to the addresses you list.6 .Notifications Setting Description Do not include in notifications (Optional) You can limit the information sent in notifications by checking any of the three checkboxes.0. 132 Release 3. • • Test Notification Click this button to test notifications. Sync Limits As a safeguard. but not during simulation. and shared contacts that can be deleted. To set sync limits. If the synchronization would delete or suspend more users than the sync limits allow. groups.Directory Sync checks to be sure that synchronization will not delete or suspend too many users. or deleted. Delete no more than users. This is a percentage of the users registered on Google Apps. Note: Sync limits apply during synchronization. This will be noted in the notifications email. If no delete limit is specified. Example: 25 Configuration 133 . specify one of the following: Delete Limits Setting Description Delete no more than % of users. Example: 5% You can suppress delete limits from the command line. Simulation results will not include sync limits. groups and shared contact (Optional) Specify a maximum percentage of users that can be deleted. groups. suspended. the entire synchronization fails and no users. groups and shared contacts (Optional) Specify a maximum number of users. or shared contacts are added. not a percentage of users on your LDAP server. moved. the default is 5%. 0. This is a percentage of the users registered on Google Apps. not a percentage of users on your LDAP server. the default is 5%. Example: 5% Suspend no more than users. groups and shared contacts (Optional) Specify a maximum number of users that can be suspended.Delete Limits Setting Description Suspend no more than % of users. Example: sync. groups and shared contact (Optional) Specify a maximum percentage of users that can be suspended. If no suspend limit is specified. 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: 25 Logging Settings You can specify the file name and level of detail of logging for Google Apps Directory Sync.6 .log 134 Release 3. ERROR includes all ERROR and FATAL messages.Logging Setting Description Log Level The level of detail of the log. At any time. WARN only logs warnings. Invalid LDAP queries will cause errors. DEBUG. • • • • • • FATAL only logs fatal operations. INFO. use Simulate Sync. use this section to verify and test your GADS settings. ERROR. Example: 4 Sync After you enter configuration information. INFO logs summary information. The level of detail is cumulative: each level includes all the details of previous levels. Configuration 135 . errors and fatal operations. DEBUG logs more extensive details. it is saved as a backup file (which overwrites any existing backup file) and a new file is created. and TRACE. To find invalid LDAP queries. see “Common Issues” on page 145. Options are FATAL. For information on common errors that might occur and how to troubleshoot them. ERROR only logs errors and fatal operations. WARN. Maximum Log Size The maximum size of the log file. the total size of these two files (the log file and the backup log file) will not exceed the total maximum size. TRACE logs all possible details. in gigabytes. and so on. Configuration Manager does not check for valid LDAP syntax. When this file reaches half capacity. To flush the remote cache for the next synchronization. click Simulate Sync. Important: This checklist confirms only the minimum needed for synchronization.Validation Results When you first go to this page. you will see Validation Results. You may need to configure additional filters or rules to be sure the results are what you expect. This page will show a checklist of all the Configuration Manager sections. 136 Release 3. you will see error messages showing what needs to be added. you will be able to use the Simulate Sync button to simulate a synchronization.0. When you’re ready. check the Clear Cache checkbox. After you’ve completed all required fields. results from the Google Apps server are cached. After you complete a test synchronization. If you are missing required information.6 . If you need help troubleshooting these errors. If any errors occur. groups. check the error text. Most error text is human readable. groups. Review the log file generated by the test sync to confirm that the simulation occurred correctly without any unexpected results. Log all events. and shared contacts. Note: Simulate Sync will never update or change your LDAP server or your users in Google Apps. Configuration Manager will: • • • • • Connect to Google Apps and generate a list of users. To run an actual synchronization. If connection was successful. see “Troubleshooting” on page 145. You can switch between the Validation Results and Simulation Results pages using the buttons at the bottom of the page.During simulation. Configuration 137 . See “Synchronization” on page 139 for more. you can go back and change your configuration to try again. The simulation is strictly for configuration and testing. use the command line. show a Proposed Change Report which shows what changes would have been made to your Google Apps user list. Generate a list of differences. click on any of the headings on the left navigation bar. You can also run another simulation from either page by clicking the Simulate Sync button at the bottom. save your configuration file and run synchronization. If you see any errors or unexpected results. but some error text may contain Java stack trace errors. See “Synchronization” on page 139. Once you are finished. and shared contacts. Note: The Proposed Change Report doesn’t check your delete limits. Connect to your LDAP directory server and generate a list of users. To change your configuration. 6 .0.138 Release 3. see “Configuration” on page 53. you can set up automatic scheduling for future synchronization. This simple command line interface gives you the flexibility to incorporate synchronization into any scheduling or batch script you wish to use. Most administrators run their first synchronization manually to test the process. import an initial set of users. Use this feature to perform a new sync after setting up or modifying your configuration. and confirm the changes. These rules are stored in an XML file. and what filters and rules to use. To create this XML file. Synchronizing from the Configuration Manager You can perform a manual synchronization from the Sync section of the Configuration Manager by clicking Sync & apply changes. you must create rules that detail how to connect to both servers. After initial synchronization from the Configuration Manager. Before you can synchronize Google Apps with your LDAP directory server. you should automate your sync process by instead using command line synchronization. Command Line Synchronization GADS uses the command sync-cmd to run synchronization. The command line to use for all platforms is sync-cmd Synchronization 139 . run Configuration Manager. For more information about Configuration Manager.Chapter 7 Synchronization Chapter 7 About Synchronization Run the synchronization command to push your LDAP directory server user information to Google Apps. After you’re done making configuration changes. --groups Do not analyze groups. but not groups. You can also see this information by running the following: sync-cmd -h in the directory where GADS is installed. run a test without this flag before running a full synchronization with this flag. Note: If you do not use this tag.6 . -c. --flush -g. Synchronization options The table below describes the possible arguments to the sync-cmd command. connect to both servers. use the following command line to read a configuration file.--oneinstance Values Restrict to one instance per config file. Does not synchronize. Synchronization will not occur without a valid XML file for this argument. For support troubleshooting only (slows sync) WARNING: This option is intended only to resolve specific troubleshooting issues. Do not use this option unless directed by support.--report-out -a.Run without any arguments. --deletelimits -f. Specify the configuration to load.0. 140 Release 3. Use this option if you want to synchronize users. generate a list of changes. Only valid with -a. and apply those changes: sync-cmd -a -o -c [filename] Replace [filename] with the name of the XML file you created in the Configuration Manager. Improper use can cause performance degradation. Write reports to the specified output file.--config [filename] -d. this command gives an error and directs you to run sync-cmd -h for help. Apply detected changes. -V Display detailed application version information. Option -o.--apply synchronization is a test only and will not affect your Google Apps account. check to be sure that a sync is not already running. To synchronize. Ignores any configured delete limits. in addition to writing them to the log. the -r. For best results. Scheduled Tasks is a third-party product and is not supported directly by the Google (or Postini) team. INFO. ERROR. In the event of a Scheduled Tasks issue. DEBUG. --users Do not analyze users. You can also use any other scheduling software that can launch commands from the command line interface.Option -h. and will have no effect. contact your Windows administrator. use cron. Note: Do not use this option. The exact timing will vary based on the number of users you have and how often you need to update them. you can set up automatic synchronization. Note: These steps apply to most common Microsoft Windows configurations.exe command as well. while a small company with few changes may not need to run the utility more than once a week. The exact method to schedule this task depends on the operating system in which Directory Sync is installed. use Scheduled Tasks. In Linux or Solaris. Override the default and/or configured log level with the specified value. Use this option if you want to synchronize groups. Use existing third-party scheduling software to automate synchronization. and TRACE. Display short application version information. In most cases. Steps for how to do this are listed below. the recommended log level is INFO. -s. Synchronization 141 . In most cases. be sure to schedule regular use of the checkforupdate. -v Scheduling Synchronization Once you have successfully run a manual synchronization. --sharedcontacts Do not analyze shared contacts. so that you can regularly check for new versions of Google Apps Directory Sync. WARN. Valid values (in increasing order of verbosity) are FATAL. but not users. In Microsoft Windows. It is intended for other versions of Directory Sync. Important: When scheduling synchronization.--help -l.--loglevel [level] Values View this information and exit. A large company with many users changing frequently may need to run Directory Sync multiple times daily.Microsoft Windows: Scheduled Tasks In Microsoft Windows. scheduled synchronization runs every one to six hours. schedule synchronization using Scheduled Tasks. -u. Test the scheduled task by running manually once. In Control Panel. A large company with many users changing frequently may need to run Directory Sync multiple times daily.exe. In the event of an issue with cron. The frequency of the task depends on your synchronization needs. add the following entry: 30 3 * * 1.6 . to schedule the task to run at 3:30 AM twice per week. 3.4 [path]/sync-cmd -a -c [filename] Replace [path] with the path where Directory Sync was installed. right-click the task you created and select Run from the right-click menu. Linux and Solaris: cron In Linux and Solaris environments. 3. 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. Note: These steps apply to most common Linux and Solaris configurations. while a small company with few changes may not need to run the utility more than once a week. The appropriate command line is: [path]\sync-cmd -a -c [filename] • Replace [path] with the path where Directory Sync was installed.Replace [filename] with the name of the XML file you created in the Configuration Manager. Save the crontab file and exit your text editor. In the Scheduled Tasks window. Check the log file for errors. 2. Complete the Scheduled Task wizard using the following information. To add a cron job 1. Run crontab -e to update the crontab file.To schedule a task 1. located where Directory Sync is installed. Double-click Add Scheduled Task. contact your administrator. open Scheduled Tasks. schedule synchronization using crontab. For instance. Linux and Solaris are third-party products and are not supported directly by the Google (or Postini) team.0. 2. 4. on Monday and Thursday. Replace [filename] with the name of the XML file you created in the Configuration Manager. 142 Release 3.) • • Choose the program sync-cmd. (Steps may vary depending on your version of Microsoft Windows. Use Advanced Properties to specify an exact command line. You can use the command checkforupdate. Notifications will be sent to an address that you specify. If you expect that a particular user will be synchronized and the user isn’t.exe in the same directory as sync-cmd. When looking through notifications logs. make a policy of regularly checking the status of your synchronizations. check for new updates regularly. Check Notification messages on a regular basis for signs of any problems. For more information about Notifications. Also. check the notifications for information.Monitoring After you have set up scheduled synchronization.exe. to check online for new versions of Google Apps Directory Sync. Synchronization 143 . look for messages that indicate that users were synchronized. see “Notifications” on page 130. 144 Release 3.0.6 . Troubleshooting 145 . Troubleshooting With Log Files If you encounter problems with GADS. system tests and researching issues.com/apps/support/tools/ migration_sync/directory-sync). you should double-check your configuration settings and submit the generated logs to the Google Apps Directory Sync Log Analyzer (https://www. Common Issues The following describes common issues and questions related to GADS. For information about LDAP queries.Chapter 8 Troubleshooting Chapter 8 About Troubleshooting This chapter covers information about how to troubleshoot problems that may occur with Google Apps Directory Sync (GADS). The dialog box does not work with Extra Large Fonts or Large Fonts. see “About LDAP Queries” on page 45. Most issues can be identified within a few moments of submission. or edit your XML file directly. Troubleshooting information includes information about common issues. the dialog box does not have an OK button. You may be using a font that is too large for the screen. Change your font size.google. Configuration Manager When creating an exception rule. What port numbers should be used in GADS when connecting to Global Catalog server? By default, GADS connects to an LDAP server with the standard LDAP port 389 to query users from a single domain/LDAP server. If you need to query users over multiple domains/LDAP servers that have trust relationship, configure GADS to connect to a Global Catalog server with the standard Global Catalog server port 3268. User Sync Errors Error Message: You are not authorized to access this API Confirm that you are using Google Apps for Business, Partners, Government, or Education. Enable APIs on your Google Apps domain, as described in “Enable APIs” on page 42. How does GADS handle suspended users? GADS 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. 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. Group Sync Errors Groups with over 1500 members in my Active Directory server members aren’t syncing correctly. Make sure you have selected MS Active Directory in the Server Type field of the LDAP Configuration section. 146 Release 3.0.6 Synchronization Rules Users are getting recreated on every sync This happens when the LDAP attribute configured as the Group Name Attribute does not contain a full email address. To resolve this issue, check your Group Search rules and make sure that GADS uses a full email address for the group names. Use one of the following methods: • • Set the Group Name Attribute to a different LDAP attribute that specifies a full email address for each group, such as mail. Enable “Replace domain named in LDAP email addresses (of users and groups) with this domain name” in Google Apps Settings, so that your Group Name Attribute matches the Google-side group names. Add the domain name to the group name by specifying a Group Name Suffix in your Group Search Rule. • A group rule or exclusion rule doesn’t seem to be doing anything. Check the scope of the rule. You may need to set the scope to SUBTREE. A group rule generates errors. Check the Group Search Attribute in LDAP Configuration. This is the field that contains the email address of a group. In most cases, this will be mail. How can I exclude a specific LDAP organization? You cannot create an LDAP rule to exclude users in a specific LDAP organization. Instead, limit the authority of the LDAP Administrator you use, removing access to any OUs you do not want to synchronize. Connections and Security What specific ports and URLs need to be accessible for Directory Sync to function? Please note that this information can change over time. For the latest information, check for updates. Directory Sync currently accesses the following URLs: Purpose URL https://www.google.com https://appsapis.google.com Port Number Authentication All Feeds 443 443 Troubleshooting 147 Purpose URL http://www.gstatic.com/ GoogleInternetAuthority/ GoogleInternetAuthority.cr l http://crl.verisign.net Port Number Certificate Revocation List Processing Certificate Authority 80 80 For an up-to-date list of Google IP addresses, run a DNS TXT lookup of the subdomain _netblocks.google.com. If GADS is unable to connect to the revocation list providers, you may see the following error in your GADS log file: PKIX path validation failed: java.security.cert.CertPathValidatorException: revocation status check failed: no CRL found The proxy environment requires a password challenge for external web access. GADS can use a proxy server but cannot respond to password challenges. To run synchronization, you will need to change your network setup to allow Directory Sync to connect without a password challenge, or without a proxy server. I cannot simulate a synchronization because the notifications server is not specified. To run a simulated synchronization, you will need a server capable of sending mail. If you are running Directory Sync on a mail server machine, you can use the IP address 127.0.0.1 for your mail server. Otherwise, contact your mail administrator for the correct mail information. How securely are passwords stored? GADS stores passwords using a two-way encryption scheme. This protects your sensitive information from casual snooping or reverse engineering. To convert a configuration file to the new format with encrypted passwords: 1. Open the file in Configuration Manager. 2. Save the file again. You can also upgrade the file with the following command-line executable: upgrade-config -c [filename] where [filename] is the name of the XML configuration file to upgrade. Note: Configuration files for version 1.3.11 or later are not compatible with earlier versions. 148 Release 3.0.6 4. click Simulate Sync to confirm that synchronization is running properly.LDAP Directory Server The Base DN information doesn’t seem to be correct. If you encounter any problems. note which tests failed and confirm that the configuration information is correct for those sections of Configuration Manager. Under LDAP Connections. Many directory servers do not include a complete LDAP browser. click Test Connection to confirm you can connect to your LDAP server. 5. An LDAP browser allows you to browse through an LDAP directory server and identify all fields and values. 2. Update your search to include more characters. or change this setting to a lower number. Under Simulate Sync. Under Notifications. Under Simulate Sync. see “Step One: Install LDAP Browser” on page 24. In Configuration Manager. 3. How do I find out information about my LDAP server fields? You will need to download an LDAP browser. Check to be sure your Base DN doesn’t include any spaces. open the XML file you are using for configuration. click Test Notification to confirm you can send a test notification. 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. use the tests in Configuration Manager to find the problem: 1. For information on LDAP browsers. confirm you have filled out all required fields. System Tests If you encounter problems. Troubleshooting 149 . The current config file you are using.com/apps/directorysync Expediting Support with Your Support PIN To contact support directly for assistance. The brand and version of the LDAP directory server you're using. collect the following information for troubleshooting: • The most current sync log file. Support will often request that you capture log file information with your log level set to TRACE to collect more information. or you can run the command sync-cmd -V. • • • • Once you have collected this information.com/support/a/bin/answer.google. Documentation and Support For documentation.py?answer=60233 150 Release 3. find your Customer PIN and Support PIN. check the help center or contact support for help. and receive expedited support as a Premium Edition customer. see the Directory Sync page in Google Apps Admin Help: http://google. support information and help center articles.xml) located in the same folder where Directory Sync is installed. The operating system on the machine where Directory Sync is running. You can find this in the Configuration Manager UI by going to Help->About.6 . The version number of Directory Sync you are running.Escalating Problems If you are unable to run GADS. This is an XML file (default name sync. located in the folder where Directory Sync is installed. Information on how to collect this information is available in the help center here: http://www.0. and cannot resolve the problem using system tests.