Beruflich Dokumente
Kultur Dokumente
Administration Guide
Release 2.1.5
Release 2.1.5
The Apache Software Foundation (http://www.apache.org/). Portions of Derby were originally developed by International Business Machines Corporation and are licensed to the Apache Software Foundation under the Software Grant and Corporate Contribution License Agreement, informally known as the Derby CLA. The following copyright notice(s) were affixed to portions of the code with which this file is now or was at one time distributed and are placed here unaltered. (C) Copyright 1997,2004 International Business Machines Corporation. All rights reserved. (C) Copyright IBM Corp. 2003. The portion of the functionTests under 'nist' was originally developed by the National Institute of Standards and Technology (NIST), an agency of the United States Department of Commerce, and adapted by International Business Machines Corporation in accordance with the NIST Software Acknowledgment and Redistribution document at
http://www.itl.nist.gov/div897/ctg/sql_form.htm
Release 2.1.5
Contents
About This Guide 7 What This Guide Contains 7 Related Documentation 7 How to Send Comments About This Guide
8 9
Chapter 2: Overview of Google Apps Directory Sync What Is Google Apps Directory Sync? 9 How Directory Sync Works 10 What Is Synchronized 11 Directory Sync and Deployment 13 System Requirements 18 Chapter 3: Getting Started 21 Overview 21 Step One: Install LDAP Browser 22 Step Two: Collect LDAP Inventory 23 Step Three: Decide What to Synchronize 27 Step Four: Prepare Google Apps for Synchronization 39 Step Five: Prepare Your Servers for Synchronization 40 Further Steps 41 Chapter 4: LDAP Queries 43 About LDAP Queries 43 Syntax 43 Common LDAP Queries 44 Chapter 5: Installation 47 About Installation 47 Install Google Apps Directory Sync 47 Upgrade Google Apps Directory Sync 49 Uninstall Google Apps Directory Sync 49 Chapter 6: Configuration About Configuration 51 Configuration Files 52 51
Contents
General Settings 53 Google Apps Configuration 56 Google Apps Settings 57 Exclusion Filters for Google Apps 62 LDAP Settings 68 LDAP Connection 69 LDAP Org Units 71 LDAP Org Unit Search Rules 72 LDAP Org Units Exclusion Rules 74 LDAP Org Unit Mappings 78 LDAP Users 80 LDAP User Attributes 82 LDAP Extended Attributes 84 LDAP User Sync 89 LDAP User Exclusion Rules 93 LDAP Groups 98 LDAP Group Search Rules 99 LDAP Group Exclusion Rules 104 LDAP User Profiles 107 LDAP User Profiles Attributes 108 LDAP User Profiles Sync 110 LDAP User Profiles Exclusion Rules 113 LDAP Shared Contacts 116 LDAP Shared Contacts Attributes 118 LDAP Shared Contacts Sync 120 LDAP Shared Contacts Exclusion Filter 123 LDAP Calendar Resources 126 LDAP Calendar Resource Attributes 127 LDAP Calendar Resource Search Rules 129 LDAP Calendar Resource Exclusion Rules 131 Notifications 135 Sync Limits 137 Log Files 139 Simulate Sync 140 Chapter 7: Synchronization 145 About Synchronization 145 Command Line Synchronization 145 Scheduling Synchronization 147 Monitoring 149 Chapter 8: Troubleshooting 151 About Troubleshooting 151 Troubleshooting With Log Files 151 Common Issues 151 System Tests 155 Escalating Problems 156
Release 2.1.5
This guide is intended for administrators who are already familiar with Google Apps and with LDAP directory servers.
Related Documentation
For additional information about Google Apps and about related products, refer to the following documents.
Document Description
Central page for Google Apps Directory Sync. Includes a description of the product, as well as available downloads. Get the latest download here. Help Center for Google Apps. This includes documentation and support for the entire Google Apps suite, including Google Apps, Mail, and Google Apps Directory Sync.
Document
Description
Release Notes for Google Apps Directory Sync. This is kept up to date with the changes in the latest version, including release schedules, new features, resolved issues, and known behavior changes. Another version of Google Apps Directory Sync. Google Apps Directory Sync for Email Security synchronizes with Message Security and Delivery (powered by Postini) instead of Google Apps.
Please specify in your email message the section to which your comment applies. If you want to receive a response to your comments, ensure that you include your name and contact information.
Release 2.1.5
Chapter 2
Chapter 2
Important Notice
Before you enable Google Apps Directory Sync for your organization, please keep a few things in mind: If Google Profiles is enabled for your organization, the data synced from your institutions 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 users 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 Customers provision of Google Profiles to Customers end users, such as the U.S. Family Educational Rights and Privacy Act of 1974 (FERPA), Childrens Internet Protection Act (CIPA), and the Childrens Online Privacy Protection Act of 1998 (COPPA).
Technical Overview
Google Apps Directory Sync runs on your server and updates Google Apps to match your LDAP server. Directory Sync never updates or changes your LDAP server. Google Apps Directory Sync includes two connected tools: Configuration Manager and the sync-cmd synchronization command line utility. Configuration Manager is a GUI-based wizard that walks through the steps of configuring a synchronization. In Configuration Manager, you set up what data to synchronize, specify LDAP query rules, list which attributes contain the information you want to synchronize, specify server connections, and note any exclusion rules. The Configuration Manager utility allows you to test your settings, and stores information in an XML file that is then used by the sync-cmd utility. The sync-cmd is a command-line utility that performs the actual synchronization. You can use the sync-cmd utility to update Google Apps data. The utility is designed to be run from a command line so that you can use your servers task scheduling to run a scheduled synchronization.
10
Release 2.1.5
Data Flow
The following steps describe how the data flow of Directory Sync works. 1. Directory Sync connects to your LDAP server and generates a list of users, groups, and shared contacts on your directory. You can set up rules to specify how this list is generated. 2. Directory Sync connects to Google Apps and generates a list of users, groups, and shared contacts in Google Apps. You can set up rules to specify how this list is generated. 3. Directory Sync compares these lists, and generates a list of changes. 4. Directory Sync then updates Google Apps to match your LDAP server settings. After Directory Sync has finished synchronization, Directory Sync sends a report of results to any email addresses that you specify.
Security
Google Apps Directory Sync has the following security features: Runs inside your network, on a machine you control. Connects to your LDAP server inside your network through Standard LDAP or secure LDAP + SSL. This connection occurs on any port you specify, but defaults to standard LDAP ports. Connects to Google Apps through the Internet via HTTPS on port 443. This connection can also run through a proxy host in your network. Connects to a mail server inside your network using standard (non-TLS) SMTP. Does not store LDAP data on the Directory Sync machine. Directory Sync stores connection details, configuration files, and event logs on the Directory Sync server, but does not store any LDAP data. All LDAP data is synchronized with Google Apps and stored as user information on Google Apps secure servers. Caches some Google Apps information locally on your Directory Sync server.
What Is Synchronized
The chart below details what gets synchronized by Google Apps Directory Sync, the equivalent terms between LDAP and Google Apps, and notes on what is and is not synchronized.
11
LDAP
Org Units (OU)
Google Apps
Synchronizes
Notes
Organizations
Organizations in Google Apps contain multiple users. Organizations can be used to structure users by department, location, or other categories. Can synchronize org structure automatically, or manually by each organization. Mailing lists in LDAP correspond to public groups in Google Apps. Groups can also be used to control access to sites and documents. Google Apps users can also create private, user-managed Groups. These are not altered or synchronized by Google Apps Directory Sync.
Mailing Lists
Groups
User
Users
In Google Apps, users are organized by email address, not LDAP Distinguished Name. You can manage changes in email address by setting a Primary Key attribute. Other email addresses also used by a given primary address. Each user can have multiple nicknames in Google Apps, and these can come from multiple LDAP alias attributes. Directory Sync can only synchronize passwords that are stored in SHA-1 or MD-5 format with no salted hashes. Alternatively, passwords can be managed separately, or authentication can be handled by SSO (Single Sign-On). For more information on Passwords, see Passwords on page 32.
User Aliases
Nicknames
Passwords
Passwords
Messages and calendar data are not migrated with Directory Sync. If you need to migrate your legacy messages and calendar data, use a migration tool, such as Google Apps Migration for Lotus Notes, or Google Apps Migration for Microsoft Exchange (which also migrates data for other IMAP servers.) Calendar Resources Calendar resources, like rooms and projectors, can be synchronized from your LDAP directory into Google Apps.
Rooms
12
Release 2.1.5
LDAP
Contacts
Google Apps
Synchronizes
Notes
Shared Contacts
An LDAP Contacts list corresponds to Google Apps Shared Contacts. Shared Contacts are visible as autocomplete options when users in Gmail start typing an email address. Personal contacts are not synchronized. Shared Contacts appear in autocomplete about 24 hours after synchronization. Google Apps Directory Sync does not synchronize personal contacts. If your users wish to import personal contact information, they can use client-based migration tools like Google Apps Migration for Microsoft Outlook. Extended LDAP information, like phone numbers and addresses, can be synchronized into Google Apps as rich User Profiles. Google Apps does not include an equivalent to shared folders. Users typically share information in Google Apps by sharing Google Docs or through Groups.
Personal Contacts
Personal Contacts
User Profiles
Shared Folders
None
13
Deployment is typically divided into three phases, plus planning beforehand and maintenance afterward. The following steps are described in more detail below. Plan: Before you begin with your Core IT pilot, take time to learn about Google Apps, plan for your deployment, and secure resources. First Phase: Core IT: Core IT department users are activated on Google Apps. Second Phase: Early Adopter: A small number of early adopters are activated with Google Apps and use it for regular business functions. Third Phase: Global Go Live: All users are activated in Google Apps. Maintenance: After your Global Go Live date, ongoing maintenance involves keeping up services, monitoring to detect any issues, and updating for changes to your organization such as departing users, new hires, and name changes.
Plan
Users: No users added yet. Before you begin with the Core IT pilot phase, theres a period of preparation and planning. During the Plan step, the goal is to understand the services available, learn technical details, decide what tools to use, identify any need for outside consulting or support, and set a plan for implementing Google Apps. Directory Sync: During this phase, begin making preparations for Google Apps.
14
Release 2.1.5
Specific preparations you can make at this stage include the following. Prepare a provisioning strategy. Secure LDAP resources. Clean up your LDAP directory. Prepare your firewall/proxy settings and network ports to ensure that Directory Sync has a connection to your LDAP directory and to Google Apps.
Fore more information on these preparations, see Getting Started on page 21.
Core IT
Users: A small number of manually added users. In the Core IT phase, a small number of IT users activate in Google Apps and begin learning and configuring Google Apps. The goal of the Core IT phase is to learn how to use the applications and utilities, to configure services, and to prepare for Early Adopters. Directory Sync: During this phase, continue preparation and testing to be ready for Directory Sync implementation by the Early Adopter phase. Typically, Directory Sync is not used to import users for the initial IT pilot, since it is easier to add your initial IT department users either manually or by uploading a CSV file into the Google Apps control panel. If you do have manually added users that are not in your LDAP, remember to add exclusion rules so those users are not deleted.
15
Early Adopter
Users: Early adopter business users, either manual or synchronized. During the Early Adopter phase, set up a small number of active users and give them the best possible user experience. Early adopters can then become familiar with Google Apps, identify any common questions or issues, and learn to use the product so that they can help others after a broader rollout. Directory Sync: During the Early Adopter phase, prepare your synchronization rules so that full synchronization will be ready on your Global Go Live date. Optionally, you can also set up Directory Sync to synchronize data for early adopters. You can use any of these features for Early Adopter synchronization: 1. You can use Directory Sync during your Early Adopters phase to synchronize your entire user list, so that your Early Adopter users can see recipient addresses in Autocomplete when sending mail. You can synchronize users as shared contacts, or synchronize as full users without sending passwords or routing users mail into Google Apps. 2. If you are running the Early Adopter phase on a separate test domain, Directory Sync can synchronize users to a test domain, adding users with the same username in a separate test domain. 3. If you are using Postini Message Security, you can set up Postini for split delivery, so that Early Adopters receive mail in Gmail while other users receive mail on your legacy server.
Global Go Live
16
Release 2.1.5
Users: All users active in Google Apps. In the Global Go Live phase, all users become active and begin using Google Apps for daily business. Mail flow is routed entirely to Gmail, users schedule their activities in Google Calendar, and day-to-day user activities run in Google Apps. After your Global Go Live date, data from legacy systems may be migrated into Google Apps, or may be left on legacy servers and checked when needed. Directory Sync: You can set up Google Apps Directory Sync to import organizations, users, aliases, profile information, groups, contacts, and calendar resources so that your Google Apps account is populated with the same data you have on your LDAP directory server. Prepare for your Go Live date. The initial synchronization of a Go Live date can take several cycles of configuration and tests, since there may be a great deal of data to synchronize. Be prepared for an extended synchronization, and try to run your synchronization during off-business hours to avoid consuming network and system resources during peak hours. Note also that shared contacts can take up to 24 hours after synchronization to show up in Gmail autocomplete. During your rollout, you may decide to split your synchronization into phases to avoid exceeding any search size limits on your directory server.
Maintenance
Users: Updated to maintain changes between your LDAP directory and Google Apps. After you have set up Google Apps and your users are live with the product, continue to update Google Apps to reflect any changes on your LDAP directory. If you remove any users from your company, update Google Apps to reflect these changes. Many companies remove a user by changing the users password and access permissions, rather than deleting the user from Google Apps, in order to smoothly handle the users documents and mail archives. Directory Sync: Check your notification messages regularly to be sure that Directory Sync is running smoothly, and to detect and address any issues that arise.
17
You can use Google Apps Directory Sync to keep your Google Apps directory up to date. You can set up Directory Sync to run scheduled synchronization, so that all changes to your LDAP directory server are synchronized with Google Apps. Any changes to your LDAP directory server, such as new users, deleted users, or users moved to new organizations, will be reflected in Google Apps. Also, during maintenance, be sure to check regularly for updates to Google Apps Directory Sync. You can check for new updates by opening Configuration Manage, or by running the command checkforupdate.exe. Depending on your needs, you may run scheduled synchronizations at different rates. Usually, this ranges between once an hour and once a day. Be aware that running synchronization too often may use up excess bandwidth or exceed quotas.
System Requirements
Before you begin using Google Apps Directory Sync, be sure you can meet the following system requirements.
domain aliases. An administrator account on your Google Apps domain, set up in the Google Apps control panel. You can also set up an OAuth key while configuring Google Apps if you have administrator login information. Provisioning API enabled on your Google Apps domain. For steps on how to do this, see Enable APIs on page 40.
18
Release 2.1.5
Server Requirements
A server to run Google Apps Directory Sync. The server should run one of the following operating systems: Microsoft Windows (supported on XP, Windows 7, Windows Server 2003/ 2008) Linux Solaris (version 8+, no support for x86)
If using 64-bit Linux systems, a 32-bit libc (such as libc6-i386) must be installed. At least 5 GB of disk space for log files and data. If you are running with DEBUG or INFO level of logging, you may need more free space than this for additional log data. At least 256 MB of free RAM. At least 1 GB of free RAM is recommended if you have less than 10,000 users, or 2 GB of free RAM if you have more than 10,000 users. For very large organizations (over 250,000), further tuning may be needed. An LDAP server with user information which is accessible to Directory Sync. All versions of the LDAP protocol are supported. Network access to your LDAP server. You do not need to run Directory Sync on your LDAP server. Read and execute administrative access over the appropriate OU structure of the LDAP server. An LDAP browser that can read and browse your LDAP directory server data. Network access to the Google Apps through HTTPS, directly or through a proxy server. This includes ports 80 and 443. For best results, a network connection to Google Apps with no proxies or firewalls is recommended. A mail server able to accept and relay notifications from Directory Sync. Access to SSL Authorities for your network.
19
Depending on your configuration, you may need the following levels of expertise for implementing Directory Sync: Google Apps administrator: Access to your Google Apps administrator account and familiarity with the Google Apps control panel. LDAP administrator: Access to your directory server and familiarity with its contents. Familiarity with LDAP query language. Network administrator: Familiarity with your network and security settings for internal and outbound traffic. Mail administrator: Access to a mail server able to relay messages for Directory Sync notifications. Familiarity with setting up mail servers for traffic. Human Resources contact: Familiarity with user base and ability to identify which LDAP entries represent current employees.
20
Release 2.1.5
Chapter 3
Getting Started
Chapter 3
Overview
This chapter discusses the steps youll take when you get started with Google Apps Directory Sync. Your implementation of Google Apps Directory Sync will be faster and smoother if you collect information about your network, LDAP directory server, LDAP data, and synchronization plans before you start configuring Google Apps Directory Sync. This chapter also includes necessary steps for setting up your Google Apps account and your internal network before you install Google Apps Directory Sync. For a more successful synchronization, follow the steps detailed below.
Getting Started
21
3. Decide What To Synchronize. Decide what domains to synchronize. Plan which users, aliases, and groups you want to synchronize with Google Apps. This can be a very significant step, and may require a great deal of planning. For more information, see Step Three: Decide What to Synchronize on page 27. 4. Prepare Google Apps For Synchronization. Make any needed changes to Google Apps. For more information, see Step Four: Prepare Google Apps for Synchronization on page 39. 5. Prepare Your Server Environment For Synchronization. Confirm that you have a notification mail server ready. For more information, see Step Five: Prepare Your Servers for Synchronization on page 40. 6. Install Directory Sync. Once you have the needed information, download and install Directory Sync. This step is covered in Installation on page 47. 7. Configure Directory Sync. Run Configuration Manager, part of Google Apps Directory Sync, to configure synchronization. This step is covered in Configuration on page 51. 8. Simulate Synchronization. Use Configuration Manager to simulate a synchronization and review the results. This step is covered in Simulate Sync on page 140. 9. Revise Configuration. Review the results of the simulated sync. If needed, revise your configuration in Configuration Manager based on the simulation. This could take several revisions for complex environments. 10. Preview Synchronization. At the command line, run a synchronization in preview mode with the configuration file you created. Check the results. This step is covered in Command Line Synchronization on page 145. 11. Manual Synchronization. At the command line, run a manual synchronization to update Google Apps. The first synchronization, which imports all information, is likely to take much longer than later synchronizations. This step is covered in Command Line Synchronization on page 145. 12. Scheduled Synchronization. Using your servers scheduling tools, set up automatic scheduled synchronization. This step is covered in Scheduling Synchronization on page 147. 13. Monitoring. Monitor the results of your ongoing synchronization to detect and address any problems that occur. This step is discussed in Monitoring on page 149. The first steps, related to preparation, are covered in this chapter below. Later steps are covered in future chapters as noted.
22
Release 2.1.5
Note that these are third-party browsers, and this document does not include instructions or support on the use of an LDAP browser.
JXplorer
To download the JXplorer Java Ldap Browser, go to:
http://www.jxplorer.org
Getting Started
23
If you have multiple LDAP directories, consider the following: Consolidate. If you are using multiple directories, consolidate your LDAP data into a single source of truth. Many customers have multiple LDAP directories, either because of different departments, acquisitions, or subsidiaries. Google Apps Directory Sync can only pull data from a single LDAP directory. Test Global Catalog. If you have multiple Microsoft Active Directory domains, a Global Catalog may help with your synchronization, but only if the catalog is set up with proper replication. If you want to try using a Global Catalog, be sure to test the catalog thoroughly before relying upon it.
The Google Apps administrator confirms with Human Resources that the users on this server are all active users, and confirms that this is the only LDAP directory server. The LDAP administrator confirms that Directory Sync will be run within the companys firewall and that the LDAP server will not need to be open to the outside.
24
Release 2.1.5
Note: You can use multiple Base DNs in a configuration. You can specify a
separate Base DN for each synchronization rule. For more information, see LDAP User Sync on page 89. LDAP Structure Information: You will need to know which OUs contain users and other resources you want to sync and which LDAP attributes contain important information. Look through your LDAP directory structure with an LDAP browser, then examine some sample users and other resources to identify the LDAP attributes. In many cases, the LDAP attribute that contains a users mail address, which will become the username in Google Apps, is the mail attribute. Confirm the LDAP attribute you want to use for mail addresses. Check your LDAP directory server to find out which attributes contain the data you need. In some cases, this data may include spaces. Once you have collected this information, you are ready to start making decisions about your synchronization.
Then, the administrator looks more closely at the structure, and finds that the OUs are divided up by department function. Each department function is a separate OU under the Base DN. Department OUs include: sales, manufacturing, it, genadmin, hr, contractors, and exec.
Getting Started
25
When conducting LDAP cleanup, consider the following actions. Identify users. Identify which users you want to synchronize with Google Apps. You may need to consult with your human resources department to confirm that your user list is the correct list of users to synchronize. Populate Password Attribute (Optional). If you are using a password field in Google Apps Directory Sync, create a custom attribute in your LDAP for your Google Apps users, and populate the attribute with a password setting. Generate random passwords and add them to a custom attribute. For more information about Passwords, see Passwords on page 32. Set Naming Conventions (Optional). Identify any email naming conventions you want to use, and update any users to fit these naming conventions. This is optional: you do not need to set any particular naming convention for Google Apps Directory Sync, but some companies use the transition to Google Apps as an opportunity to change naming standards. Mail-Enabled Groups. Identify mail-enabled groups to synchronize with Google Apps. This includes only mail-enabled groups that operate as mailing lists, not security groups. Note also that you can set Google Apps to allow users to create and manage their own groups; these are not affected by synchronization. Plan Resource Naming Conventions. If you are planning to synchronize calendar resources, you can take this opportunity to plan a naming convention in Google Apps. For more information on this calendar resource naming, see the Google Code site article Developing a naming strategy for your calendar resources.
26
Release 2.1.5
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.
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
27
Note: Directory Sync 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 Directory Sync 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.
28
Release 2.1.5
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 on page 69.
User Data
Directory Sync 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 22. 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 43.
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 Google Apps Directory Sync 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 LDAP User Profiles on page 107. 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 LDAP User Profiles on page 107. Aliases: You can synchronize one or more attributes for aliases from your
Getting Started
29
LDAP directory into Google Apps nicknames. Use an LDAP browser to confirm the LDAP attribute (or attributes) you want to use. Be sure that the attribute contains only an email address, and not other data such as a phone number. Primary Domain Key: If your users are likely to change user names, set up a Primary Key attribute beforehand so that user information is not lost when a user changes their name. This should be a field on your LDAP that is unique for each user, and will not change when your users change names. Passwords: Directory Sync supports a limited set of password operations. If you want Directory Sync to handle passwords, this will require additional preparation and planning. For more information, see Passwords on page 32. Deleted and Suspended Users: By default, users not found on your LDAP directory will be deleted from Google Apps, and suspended users will be ignored. If this is what you want Directory Sync to do, leave deleted and suspended users settings at the default. You can set Directory Sync to suspend users instead of deleting them. This allows for data recovery if users are later recovered, and the ability to view and transfer a users assets. If your Google Apps account has suspended users that you want to remove, you can instead set Directory Sync to delete suspended users. You cannot use this setting if you use the option, described in the paragraph above, to suspend users instead of deleting them. For more information on these options, see LDAP Extended Attributes on page 84.
30
Release 2.1.5
Distinguished Name reference, which follow a format like cn=Terri Smith,ou=Executive Team,dc=mobistep,dc=com. Google Apps Directory Sync can synchronize mailing lists using either format, but youll need to know which youre using beforehand so you can configure Directory Sync properly. Org Structure: By default, Google Apps Directory Sync synchronizes all users into a single flat structure. This works well if you have a small organization, or if you want all users to have the same settings and rights. This also works well if you are piloting a small group before a larger rollout. If you want to use an org unit hierarchy in Google Apps, you can synchronize the organization hierarchy from your LDAP directory server. If you do so, look through your OUs with an LDAP browser beforehand to be sure that you are synchronizing the right OU structure. You may have special OUs that should not have org units in Google Apps, such as an OU for printers. For more information about synchronizing your OU structure, see LDAP Org Units on page 71. If you want to create Google Apps organizations manually, you can set those organizations up in Google Apps, then set Directory Sync to move users into those Google Apps organizations, without changing existing organizations. To set this up, select Do not create or delete Google Organizations, but move users between existing Organizations, as specified in the User Sync Rules option on the General Settings page. For every user search rule, specify the organization that should contain users for that rule, or an LDAP attribute that contains the name of the appropriate Organization. For more information about moving users between existing organizations, see and LDAP User Sync on page 89.
Getting Started
31
synchronize Shared Contacts, it may take up to 24 hours for the changes to appear in Google Apps. Do you want to synchronize Calendar Resources? If you want to import calendar resources (such as conference rooms) from your LDAP into Google Apps, configure Calendar Resources synchronization. Calendar Resources are visible to every user when attempting to schedule calendar events. For more information, see LDAP Calendar Resources on page 126. If you do want to synchronize calendar resources, choose a naming format for your calendar resources. Note that names containing spaces or special characters (like @) will not be synchronized. The rules for calendar resources names are different than other synchronized information. For more information on this calendar resource naming, see the Google Code site article Developing a naming strategy for your calendar resources.
Passwords
Directory Sync can import passwords from LDAP, but only in an LDAP attribute that stores passwords in plain text, Base64, unsalted MD5, or unsalted SHA-1 format. Other password encryption hashes are not currently supported, nor are salted hashes. Most directory servers do not support these formats natively, and storing your user passwords in these formats on your mail server may have serious security implications.
32
Release 2.1.5
For password synchronization, Directory Sync provides the following options: Implement Single Sign-On for your domain. Set up a SAML server for your account to manage Single Sign-On. Users will use the same passwords and authorization for both Google Apps and your LDAP directory server. Google Apps Directory Sync will create random passwords during synchronization in this case. Note that Single Sign-On supports only web authentication. Other forms of authentication (such as IMAP, POP, and ActiveSync) do not support Single Sign-On and will still require a Google password. Use this option if you are planning to set up Single Sign-On for your domain. For more information on Single Sign-On, see the SSO site on Google Code. Use a plain text LDAP attribute for default password for new users. With this option, Google Apps passwords are separate from passwords on your LDAP directory server. You can use this method to create a temporary password from any LDAP attribute that holds data in plain text format. The most secure way to create a default password is to populate a custom attribute with a randomly generated password. Alternately, you can use a private and unique field, such as employee ID number. Avoid using a field that could be easily guessed, such as email address or last name, since this could make it easier for other users to sign up using temporary credentials. Use this option if you want users to have separate one-time passwords, and you have or can create an appropriate LDAP field to use for temporary passwords. Use a third-party utility to convert unsupported passwords to a supported format. Check the Google Marketplace for third-party tools to help with synchronizing passwords. Use this option if you need to have Google Apps use the same passwords as your LDAP directory server, but you are unable to set up a SAML server. This may require you to set new passwords on your LDAP directory. Specify a default password for new users. Every new user will have the same password until that user logs in and changes the password. With this option, Google Apps passwords are separate from passwords on your LDAP directory server. Set a default password for new users, and then set Directory Sync to synchronize passwords for new users and force new users to change their passwords. Because this password may be guessed by other users, this is not generally recommended as a secure option.
Important: Be careful of the security considerations of passwords. Also, note that if
you use a plaintext password, be sure to set Directory Sync to synchronize passwords only for new users, and to require new users to change passwords.
Mapping
Decide how your LDAP directory server data should map to your Google Apps data. You should have a clear picture of where every user, group, and resource in your LDAP directory server should be synchronized in your Google Apps data.
Getting Started
33
For a chart of how your LDAP data maps to Google Apps, see What Is Synchronized on page 11. Note that you may have some users who should not be synchronized, either on your LDAP server or in Google Apps. Prepare a list of exceptions so that you know what rules to set up. Mapping: For each group of users, decide whether those users should be imported, and where those users should be imported. You can set up this mapping to a flat hierarchy, an automatic one-to-one synchronization, or a manual set of custom rules. Exceptions on Google Apps: Are there any exceptions on your Google Apps domain that you dont want to synchronize? Your Google Apps account may have users or groups that you dont want to synchronize with LDAP. This could include new users not listed in your LDAP directory, pilot test accounts, shared Google Apps accounts, or other entries that belong in your Google Apps account but not your LDAP directory. Find out which users and groups youd like to exclude, and look for any common pattern that may simplify exception rules. Exceptions on LDAP Directory: Are there any exceptions on your LDAP directory that you dont want to synchronize? Your LDAP directory server may have obsolete users, suspended users, test accounts, printers, defunct mailing lists, or other data that you do not want to import into Google Apps. In most cases, you can set your LDAP search rules to ignore these users, but in some cases, you may need to set up manual exception rules to skip specific users, or a pattern of users. Identify any exceptions that you dont want to synchronize, and note these so that you can create exceptions during configuration.
34
Release 2.1.5
For more information about deployment phases and the 3-phase deployment model, see Directory Sync and Deployment on page 13.
Core IT Early Adopter Go Live Maintenance
Clean up data and prepare for migration in Early Adopter phase. Test connectivity and synchronization.
By the end of the Early Adopter phase, you should have Google Apps Directory Sync ready for your Global Go Live date.
Switch users over to Google Apps. Set Google Apps up as primary service. The first Synchronization can take time. Synchronize a few days in advance of your Go Live date so that users will be ready. In some cases, it may be a good idea to synchronize over a weekend.
Keep Google Apps data synchronized with your LDAP directory. Plan a scheduled synchronization of Google Apps. Scheduled synchronization will take less time and resources than the first synchronization.
Domains
Optionally, you can use a shadow or test domain, replacing domain names with a subdomain of your existing organization, like test.exmpl.com.
Getting Started
35
Core IT
Early Adopter
Go Live
Maintenance
Users
Set up exceptions for manuallyadded Core IT users, temporary administrators, or other users that are not part of your LDAP search rules. Create an LDAP OU, group, or custom attribute for users that will be synced into Google Apps. Then, create a group of custom attribute for active Google Apps users. User Profiles
Synchronize your early adopters or add them manually. Mark which users are activated in your LDAP directory. Optionally, you can synchronize all users (but not change their mail flow or send passwords), so that all addresses will be visible in Autocomplete.
Set up exceptions for Google Apps users that are not listed in your LDAP directory.
If your LDAP directory includes rich profile data, you can synchronize this with Google Apps. Aliases
If your LDAP directory includes rich profile data, you can synchronize this with Google Apps.
If your LDAP directory includes rich profile data, you can synchronize this with Google Apps.
Passwords
36
Release 2.1.5
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 Suspended users can be used for early migration of data. Usually not used after go live date, but available if you want to suspend users instead of deleting them. Usually not used after go live date, but available if you want to suspend users instead of deleting them.
Mailing lists should now be managed in Google Apps as groups. Google Apps Directory Sync does not synchronize or overwrite usermanaged mailing lists (groups).
Org Structure
Optionally, start setting up your org structure in advance during Early Adopter phase.
If you have a large organization or complex hierarchy in your LDAP directory server that you want to keep, configure Directory Sync to synchronize Org Structure.
Changes to your Organization Structure Mapping rules will move users within Google Apps.
Getting Started
37
Core IT
Early Adopter
Go Live
Maintenance
Shared Contacts Optionally, you can synchronize all users as shared contacts so that they will be visible in Autocomplete. Note that these shared contacts may lead to duplicate contacts if not removed before your Go Live date. Calendar Resources Most calendar resources will be maintained on legacy server. Primary Key Attribute Set up Primary Key Attribute for easier ongoing maintenance. Primary Key attributes help users keep data after a name change. Calendar resources should now be managed in Google Apps. If your company directory has shared contacts, you can synchronize these during your Go Live synchronization. Note that personal contacts are not synchronized. If your company directory has shared contacts, 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, and identifies the OUs that should be synchronized.
38
Release 2.1.5
The administrator decides that MobiStep needs to synchronize: OUs Users Aliases Groups (mailing lists) Shared contacts Calendar resources
The mailing lists in the LDAP server use the attribute member to store the members of each mailing list, and the member attribute contains the full DN of the mailing list members, rather than their email address. The Google Apps Directory Sync administrator notes this attribute, and notes that it is a reference attribute, not a literal attribute. Because the LDAP user profile information on the LDAP server is not in a standard format across organizations, the Google Apps administrator decides not to synchronize this information. The LDAP administrator creates a custom attribute and populates the attribute with a randomly-generated one-time password. The Google Apps administrator sets up a mail merge to send out these passwords to users along with information on how to activate their accounts. The Google Apps identifies that there are some users in the contractors OU that are no longer with the company and should not be synchronized. The administrator looks through these users and notes that all of them match a regular expression (the user addresses all begin with defunct) and notes this to create exceptions in Google Apps.
Getting Started
39
Enable APIs
Google Apps Directory Sync uses the Google Apps Provisioning API to update your Google Apps domain. Before you can synchronize, you must log in to Google Apps and enable the User API. To enable the Provisioning API access for your domain: 1. Log in to your control panel. 2. Click the Domain Settings tab. 3. Click the User settings tab. 4. For Provisioning API: Check the box next to Enable provisioning API. If its already checked, leave it checked. 5. Click Save changes. For more information, see the Google Apps Help Center.
Note that you cannot use Google Apps as your notifications mail server.
40
Release 2.1.5
Sample Scenario
MobiSteps Google Apps administrator decides to use OAuth, and collects a Google Apps administrator username and password to configure this. The administrator also contacts MobiSteps mail administrator to set up notifications. The existing MobiStep mail server has a rule to block all relay attempts, so the mail administrator sets up an exception so that the machine running Directory Sync can relay mail through that server to send out notifications. The server doesnt use SMTP authentication, so no username or password are required. The MobiStep administrator decides that the notifications should come from the address dirsync.notifications@mobistep.com so that notifications can be filtered separately into a label.
Further Steps
Further steps are discussed in later chapters: 6. Install Directory Sync. This step is covered in Installation on page 47. 7. Configure Directory Sync. This step is covered in Configuration on page 51. 8. Simulate Synchronization. This step is covered in Simulate Sync on page 140. 9. Revise Configuration. This step is covered in Configuration on page 51. 10. Preview Synchronization. This step is covered in Command Line Synchronization on page 145. 11. Manual Synchronization. This step is covered in Command Line Synchronization on page 145. 12. Scheduled Synchronization. This step is covered in Scheduling Synchronization on page 147. 13. Monitoring. This step is covered in Monitoring on page 149.
Getting Started
41
42
Release 2.1.5
Chapter 4
LDAP Queries
Chapter 4
different, and many store information in different fields or formats. To develop these queries, consult standard LDAP documentation and review your LDAP structure with an LDAP browser. Google support cannot write LDAP queries for your environment or debug your LDAP queries.
Syntax
The following syntax is used in LDAP filters:
Name of Operator
Character
Use
Equals
LDAP Queries
43
Name of Operator
Character
Use
* () & | !
Wildcard to represent that a field can equal anything except NULL. Separates filters to allow other logical operators to function. Joins filters together. All conditions in the series must be true. Joins filters together. At least one condition in the series must be true. Excludes all objects that match the filter.
For examples of how these operators are used, see the common LDAP queries below.
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)))
44
Release 2.1.5
All user objects except for ones with primary email addresses that contain the word test
(&(&(objectclass=user)(objectcategory=person))(!(mail=*test*)))
All user objects (users and aliases) that are designated as a person and all group objects (distribution lists)
(|(&(objectclass=user)(objectcategory=person))(objectcategory=grou p))
All user objects that are designated as a person, all group objects and all contacts, except those with any value defined for extensionAttribute9:
(&(|(|(&(objectclass=user)(objectcategory=person))(objectcategory= group))(objectclass=contact))(!(extensionAttribute9=*)))
All users who are members of the group identified by the DN of CN=GRoup,OU=Users,DC=Domain,DC=com:
(&objectcategory=user)(memberof=CN=GRoup,OU=Users,DC=Domain,DC=com ))
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
45
46
Release 2.1.5
Chapter 5
Installation
Chapter 5
About Installation
To run Google Apps Directory Sync, install Directory Sync on your server. Directory Sync is designed to run on Windows, Linux or Solaris machines. The installer is an executable program that installs all needed components on the server, including managing libraries, classpath variables, and other components. The installer also uninstalls any existing version of Directory Sync in the same directory. The sections below contain system requirements, and instructions on how to install, upgrade or uninstall Directory Sync on your server.
2. Choose the operating system of the server where you plan to run Directory Sync and click Download.
Installation
47
The installer contains all needed components and can be run offline without any outside connection.
Note: To run synchronization, you must also enable APIs on your Google Apps
48
Release 2.1.5
3. In the uninstaller, click Next to uninstall Directory Sync. 4. Once uninstallation has completed close the uninstaller. All Directory Sync utility files and all libraries not used by other programs will be removed. Log files and XML configuration files will not be deleted.
Installation
49
50
Release 2.1.5
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.
Note: Before you use Configuration Manager, collect information about your LDAP directory server and your Google Apps setup. For more information, see Getting Started on page 21.
In Configuration Manager, you can: Set up and test a connection to Google Apps. Configure which users, groups, and shared contacts in Google Apps to synchronize. Set up and test a connection to your LDAP server. Configure LDAP search criteria for synchronization. Set up notifications and logging. Run a simulated synchronization to verify your settings.
Once you have set up your configuration in Configuration Manager, you can run your actual synchronization from the command line. See Synchronization on page 145. Configuration Manager does not change the data in your LDAP directory server or Google Apps. It is strictly used to configure and simulate synchronization. Configuration Manager walks you through each step of configuring Google Apps Directory Sync. Once you have finished each page, click Next to go to the next step. You can also go back to previous steps with the Previous button, or jump directly to any step using the left side navigation menu. Directory Sync 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:
Configuration
51
http://www.ietf.org/rfc/rfc2254.txt
Directory Sync 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 havent 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.
52
Release 2.1.5
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 145.
General Settings
On the General Settings page, specify which categories of object to synchronize.
Configuration
53
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 40.
54
Release 2.1.5
How Google Apps Directory Sync synchronizes users from LDAP Org Units into Google Organizations. Options: Sync LDAP Org Units, and move users into Google Organizations, as specified in the User Sync Rules. Google Apps Directory Sync will create and delete Organizations and move users into specified organizations. Do not create or delete Google Organizations, but move users between existing Organizations, as specified in the User Sync Rules. Google Apps Directory Sync move users into specified organizations, but will not modify your organizations structure in Google Apps. Ignore and Google Organization information (Any new users are created in the default Google Organization)
The default is Ignore and Google Organization information (Any new users are created in the default Google Organization). Users Whether Google Apps Directory Sync should synchronize users. Checked by default. For more information, see LDAP Users on page 80. Uncheck if you do not want to synchronize users. Groups Whether Google Apps Directory Sync should synchronize groups. Checked by default. For more information, see LDAP Groups on page 98. Uncheck if you do not want to synchronize groups.
Configuration
55
General Setting
Description
Profiles
Whether Google Apps Directory Sync should synchronize user profiles. Unchecked by default. For more information, see LDAP User Profiles on page 107. Check if you want to synchronize user profiles.
Contacts
Whether Google Apps Directory Sync should synchronize shared contacts. Unchecked by default. For more information, see LDAP Shared Contacts on page 116. Check if you want to synchronize shared contacts.
Calendar Resources
Whether Google Apps Directory Sync should synchronize calendar resources. Unchecked by default. For more information, see LDAP Calendar Resources on page 126. Check if you want to synchronize calendar resources.
56
Release 2.1.5
Before you begin setup in Google Apps Configuration, collect information about your Google Apps domain and your LDAP directory server. For details on what information youll need, see Getting Started on page 21.
Configuration
57
Enter the primary domain you wish to synchronize. You must use the primary domain in Google Apps, not a domain alias. If you enter a domain that is different from the domain on your LDAP server, Google Apps Directory Sync will rename all users and use the Domain name listed here instead. Example: example.com
Replace domain names in LDAP email addresses (of users and groups) with this domain name.
If checked, all LDAP email addresses are changed to match the domain listed in Domain Name. For instance, if your Domain Name is example.com, and your LDAP query returns an email address user23@domain.com, then Directory Sync synchronizes user23@example.com. If unchecked, all LDAP email addresses keep their original domain name.
Important: Note that if the domain is replaced, this may affect exclusion rules that search for exact match of a user name. If this setting is enabled, the domain name is stripped for exclusion rules. Note: Domain names for shared contacts are not
replaced. By default, this is checked. Authorization The method you wish to use for connecting to Google Apps securely. Options: Authorize using OAuth: Connect to Google Apps during synchronization using an OAuth token that you generate in Google Apps. This is the recommended setting. Use your Administrator Credentials: Connect to Google Apps during synchronization using an Administration Email address and password.
If you choose to Authorize using OAuth, press Authorize Now to create and enter your validation token string.
58
Release 2.1.5
Description
The email address used to log into Google Apps. This address should be a valid Google Apps administrator in the domain that you are synchronizing. The domain must match the Domain name. Example: admin@example.com
Admin Password (if using your Administrator Credentials) SSL Proxy Host Name (if needed)
Enter the password for the Google Apps administrator. Example: swordfish Passwords are stored in an encrypted format. If your server is running behind a firewall that requires an SSL Proxy to connect to an outside server, enter the proxy host name here. If you can connect directly to the internet from this machine, leave this field blank. Example: firewall02-http.mixateriacorp.com
If your server is running behind a firewall that requires an SSL Proxy to connect to an outside server, enter the proxy host port here. Otherwise, leave this field blank. Common ports for SSL proxy are 80, 8080, 3128 and 1080. Example: 80
If your server is running behind a firewall that requires an SSL Proxy to connect to an outside server, and that proxy requires authentication, enter the proxy authentication user name here. Otherwise, leave this field blank. Example: proxyuser01
If your server is running behind a firewall that requires an SSL Proxy to connect to an outside server, and that proxy requires authentication, enter the proxy authentication password here. Otherwise, leave this field blank. Example: swordfish
Configuration
59
Description
If you use a different proxy server for HTML connections than SSL connections, enter the HTTP proxy host here. Directory Sync always connects to Google Apps on SSL. The only time Directory Sync sends traffic by unencrypted HTTP is to validate a certificate with the issuing authority. If you do not use a proxy server, or you use the same proxy server for HTML and SSL connections, leave this field blank. If blank, this field defaults to the value of the SSL Proxy Host Name field. Example: firewall02-http.mixateriacorp.com
If you use a different proxy server for HTML connections than SSL connections, enter the HTTP proxy host port number here. If you do not use a proxy server, or you use the same proxy server for HTML and SSL connections, leave this field blank. If blank, this field defaults to the value of the SSL Proxy Host Port field. Example: 80
If you use a different proxy server for HTML connections than SSL connections, and your HTML proxy requires authentication, enter the proxy authentication user name here. Otherwise, leave this field blank. Example: proxyuser01
If you use a different proxy server for HTML connections than SSL connections, and your HTML proxy requires authentication, enter the proxy authentication password here. Otherwise, leave this field blank. Example: swordfish
Alias Domains
60
Release 2.1.5
2. In the browser page, sign in to Google Apps using administrator credentials. 3. After you enter your credentials, Google Apps will automatically display a token. Copy that token. 4. Return to the Google Apps Directory Sync Configuration tool and click Next.
5. In the Step 2: Enter the Verification Code window, enter the verification code you created in Google Apps. 6. Click Validate to confirm that the code is valid.
Configuration
61
Test Connection
Once you have configured Google Apps Settings, click Test Connection at the bottom of the page. Configuration Manager will connect to Google Apps and attempt to log in, to verify the authorization and settings you entered.
Exclusion rules are based on string values and regular expressions, not LDAP settings. You can exclude user profiles or shared contacts by their primary sync key.
This page shows the list of exclusion filters. In a new configuration, this contains no exclusion rules. To add new exclusion filters, click the Add Rule button at the bottom of the screen.
62
Release 2.1.5
In the list of Exclusion Filters, you can change existing filters as follows: Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. Edit: Click the notepad icon to edit the settings of an exclusion filter. Delete: Click the X icon to delete the exclusion filter.
You can set up a rule to exclude an entire Google Apps organization path. For instance, if you add all your IT administrators to the organization path administrators/IT and your security administrators in the organization path administrators/security you could use the following rule to exclude both groups of users, as well as any others under the administrators organization: Type: Organization Complete Path Match Type: Substring Exclusion Rule: administrators
Directory Sync will delete users from your list of Google Apps users and from all Google Apps groups if they are not listed in your LDAP directory server. Therefore, for single users not listed in your LDAP, add the following two rules. First rule: Type: User Name Match Type: Exact Match Exclusion Rule: username@example.com
Second rule: Type: Member Name Match Type: Exact Match Exclusion Rule: username@example.com
Configuration
63
Pattern of users
If your Google Apps users list includes users that arent in your LDAP directory server, and they all match a specific text pattern, you can use a substring or regular expression instead of creating a rule for each user. In this example, all these users have the name appstrial in their primary address, such as appstrial-lydia@example.com and appstrial-manesh@example.com. First rule: Type: User Name Match Type: Substring Exclusion Rule: appstrial
Second rule: Type: Member Name Match Type: Substring Exclusion Rule: appstrial
If you have groups listed in Google Apps that dont match a mailing list in your LDAP directory server, Directory Sync will delete them, Therefore, add the following rule. Type: Group Name Match Type: Exact Match Exclusion Rule: FloridaSalesTeam@example.com
Groups in Google Apps can also include mailing address that are outside your domain. Google Apps Directory Sync will remove these unless you add a Member Name exclusion filter. In this example, the Google Apps group also include addresses in two other domains, gmail.com and electric-automotive.com. First Rule: Type: Member Name Match Type: Substring Exclusion Rule: @gmail.com
Second Rule: Type: Member Name Match Type: Substring Exclusion Rule: @electric-automotive.com
64
Release 2.1.5
Add Rule
Click Add Rule at the bottom of the page to create an exclusion rule.
Configuration
65
In the Add Exclusion Rule panel, specify the following to add an exclusion rule. Keep in mind that this is information on your Google Apps account, not your LDAP directory server.
Exclusion Rule Setting Description
Type
Sets the type of exclusion filter to create: User Name, Group Name, or Member Name. Organization Complete Path: Do not delete any user who is a member of an organization that matches the complete path rule. Organization paths are treated as strings with the format
organization/sub-organization/sub-suborganization. The interface displays this choice
as ORGUNIT_PATH. User Email Address: Do not delete any user whose primary address matches the rule. The interface displays this choice as USER_NAME. Alias Email Address: Do not delete any user with an alias address that matches the rule. The interface displays this choice as USER_ALIAS. Group Email Address: Do not remove any group which has a name that matches the rule. The interface displays this choice as GROUP_NAME. Group Member Address: Do not remove any user whose primary address matches this rule from any groups. The interface displays this choice as MEMBER_NAME. User Profile Primary Sync Key: Do not delete any user profile if the users address matches the rule. The interface displays this choice as USER_PROFILE_PRIMARY_KEY. Shared Contact Primary Search Key: Do not remove a shared contact if the contacts primary key (specified in the Sync Key field) matches the rule. The interface displays this choice as SHARED_CONTACT_PRIMARY_KEY.
66
Release 2.1.5
Description
Match Type
The type of rule to match for the filter. Exact Match: The address or organization name must match the rule exactly. Examples: User Name: user1@example.com excludes that single Google Apps user from user list synchronization, but not group synchronization. Group Name: FloridaSalesGroup@example.com excludes that Google Apps group from groups synchronization. Member Name: user1@example.com excludes that single Google Apps user from groups synchronization. Substring Match: The address or organization name must contain the text of the rule as a substring. Examples: User Name: sales excludes
sales_questions@example.com and amanda@sales.example.com.
synchronization. Regular Expression: The address or organization must match the regular expression in the rule. Examples: User Name the regular expression team[39]@example.com excludes team3@example.com through team9@example.com. Group Name: the regular expression Local Team [A-Z][A-Z] excludes the Local Team - NJ and Local Team - AZ groups. Member Name: the regular expression team[39]@example.com excludes team3@example.com through team9@example.com from groups synchronization.
Configuration
67
Description
Exclusion Rule
The text of the match or regular expression to compare. See above for examples for these rules. Users that meet the requirements for an exclusion filter will not be deleted. If they are listed on the LDAP server, Directory Sync will attempt to add the user and fail.
LDAP Settings
The LDAP Settings 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.
68
Release 2.1.5
LDAP Connection
Specify your LDAP connection and authentication in this page.
Description
Connection Type
Choose whether to use an encrypted connection. If your LDAP server supports an SSL connection and you wish to use it, choose LDAP + SSL. Otherwise, choose Standard LDAP. Example: Standard
Host Name
Enter the domain name or IP address of your LDAP directory server. Example: ad.example.com, or 10.22.1.1.
Port
Base DN
Enter the Base DN for the subtree to synchronize. Do not include spaces between commas. If you dont know the Base DN, consult your LDAP administrator or check an LDAP browser. Example:
ou=test,ou=sales,ou=melbourne,dc=ad,dc=example, dc=com
Configuration
69
Description
Authentication Type
The authentication method for your LDAP server If your LDAP server allows anonymous connections and you want to connect anonymously, select Anonymous. Otherwise, select Simple. Example: Simple
Authorized User
Enter the user who will connect to the server. This user should have read and execute permissions for the whole subtree. If your LDAP directory server requires a domain for login, include the domain for the user as well. Example: admin1
Password
Enter the password for the authorized user. Example: swordfishX23 Passwords are stored in an encrypted format.
Test Connection
Once you have configured LDAP Authentication settings, click Test Connection. Configuration Manager will connect to your LDAP server and attempt to log in, to verify the settings you entered.
70
Release 2.1.5
Synchronizing org units is optional. If you set Do not create or delete Google Organizations, but move users between existing Organizations in General Settings, org units will not be synchronized from LDAP. You can still specify which users go in org units in the LDAP User Sync rules. For more information, see LDAP User Sync on page 89.
Configuration
71
By default, all org units that match these search rules will be added to the Google Apps org unit hierarchy, and all org units that do not match these search rules will be removed. You can change this behavior with exclusion filters. This page shows the list of search rules. In a new configuration, this will be an empty list. To add a search rule, click the Add Org Unit Search Rule button at the bottom of the screen. On the list of Search Rules, you can change existing rules: Reorganize: Click the up arrow or down arrow icon to change the order of search rules. Edit: Click the notepad icon to edit the settings of a search rule. Delete: Click the X icon to delete a search rule.
Search rules are processed in the order listed. If you would like one search rule to take priority over another, move that search rule up using the up arrow icon on this page. If two rules contradict each other, the first rule takes precedence.
72
Release 2.1.5
Description
An LDAP attribute that contains the description of each org unit. This field is optional. If left blank, your Org Units will not contain a description when created. Example: description
Scope
This determines where in the LDAP directory this rule applies. Choose which option to use: Subtree: All objects matched by the search, and anything under those objects, recursively. Subtree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. One-level provides a limited search that will avoid causing extreme load for very large organizations. Object: Only objects directly matched by the search. No recursion of any kind.Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object.
Example: Subtree
Configuration
73
Description
Rule
The search rule for org unit sync to match. This rule is a standard LDAP query, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see About LDAP Queries on page 43. The Base DN (Distinguished Name) to use for this search rule. This will override the default Base DN you specified in LDAP Connection. This field is optional. In most cases, you can leave this field blank and use the Base DN specified in the LDAP Connection page. If you want this rule to use a different Base DN than the default, specify an alternate base DN. Example:
ou=powerusers,ou=test,ou=sales,ou=melbourne,dc= ad,dc=example,dc=com
Base DN
74
Release 2.1.5
Some examples of reasons for LDAP org unit exclusion rules: Internal org units that do not have outside email addresses OUs for printers, conference rooms, and other non-user resources Test OUs on your LDAP directory server OUs that are not participating in a pilot program
Note: To exclude individual org units, add a separate rule for each org unit.
This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click the Add Rule button at the bottom of the screen. In the list of Exclusion Filters, you can change existing filters as follows: Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. Edit: Click the notepad icon to edit the settings of an exclusion filter. Delete: Click the X icon to delete the exclusion filter.
Configuration
75
Several organizational units are no longer in use because two nearby offices combined together. The defunct OUs all have stpaul in the DN. Match Type: Substring Match Rule: stpaul
Three specific organizational units are top security and should not be synchronized. Add a separate rule for each special LDAP mailing list. First rule: Match Type: Exact Match Rule: ou=earlystatements,u=finance,ou=users,dc=ad,dc=example,dc=com
About thirty extra OUs are listed in the LDAP directory server, but they are only used for internal load testing. All the test users follow the same name pattern: ou=internaltextX,dc=ad,dc=example,dc=com, where X is a number. Match Type: Regular Expression
76
Release 2.1.5
Rule: ou=internal-test[0-9]*,dc=ad,dc=example,dc=com
Add Rule
Click the Add Rule button at the bottom of the page to exclude an org unit in your LDAP server from synchronization.
Exclude Type
This Exclude Type is always Org Unit DN. Org Unit DN: Base the exclusion rule on the Distinguished Name (DN) of the org unit to exclude.
Match Type
The type of rule to use for the filter. Exact Match: The org unit DN must match the rule exactly, with the domain name added on.
Note: In many cases, Substring Match yields better results than Exact Match.
Substring Match: The organization unit DN must contain the text of the rule as a substring. Regular Expression: The org unit DN must match the regular expression specified.
Configuration
77
Description
Rule
The match string or regular expression for the exclusion rule. Behavior of this field depends on the Match Type you choose. Addresses that contain this string (or match this regular expression) will not be added to Google Apps, and will be deleted if found. Examples: Exact Match:
ou=test,ou=sales,ou=melbourne,dc=ad,dc=exam ple,dc=com
This page shows the list of mappings. In a new configuration, this will be an empty list. To add a search rule, click the Add Org Mapping button at the bottom of the screen.
78
Release 2.1.5
On the list of Search Rules, you can change existing rules: Reorganize: Click the up arrow or down arrow icon to change the order of search rules. Edit: Click the notepad icon to edit the settings of a search rule. Delete: Click the X icon to delete a search rule.
Search rules are processed in the order listed. If you would like one search rule to take priority over another, move that search rule up using the up arrow icon on this page. If two rules contradict each other, the first rule takes precedence.
Examples of Mapping
Listed below are samples of common mappings. Note that the exact text of these rules will vary based on your needs.
Sample Mapping: Multiple Locations
In this example, an LDAP directory server has an organizational hierarchy split between two office locations: Melbourne and Detroit. The Google Apps org unit hierarchy will match the same hierarchy. First Rule: (LDAP) DN: ou=melbourne,dc=ad,dc=example,dc=com (Google Apps) Name: Melbourne
In this example, an LDAP directory server has an organizational hierarchy split based on different departments: Sales, HR, Support, Marketing, IT and Executives. Most of the Google Apps org unit hierarchy will match the same hierarchy, under the Users group, but the IT team will synchronize to the root org unit, and Executives will synchronize to a separate org unit First Rule (general case for most OUs): (LDAP) DN: ou=users,dc=ad,dc=example,dc=com (Google Apps) Name: Users
Second Rule (exception for IT): (LDAP) DN: ou=it,ou=users,dc=ad,dc=example,dc=com (Google Apps) Name: /
Configuration
79
Third Rule (exception for Executives): (LDAP) DN: ou=executives,ou=users,dc=ad,dc=example,dc=com (Google Apps) Name: Executives
Add Mapping
To add a new search rule, click Add Mapping.
(LDAP) DN
The Distinguished Name (DN) on your LDAP directory server to map. Example: ou=melbourne,dc=ad,dc=example,dc=com
The name of the org unit in Google Apps to map. To add users to the default Organization in Google Apps, enter a single forward slash /. Example: Melbourne
LDAP Users
The LDAP Settings section configures how Google Apps Directory Sync generates your LDAP user list for comparison. You may need to collect information from your LDAP directory server before you can enter details in this section.
80
Release 2.1.5
WARNING: After you delete a user, you cant add the same user for 5 days.
Important: You must add at least one LDAP User Sync rule to run Google Apps
Directory Sync. This determines which users are synchronized and added in Google Apps. Even if you only use Google Apps Directory Sync to sync groups and not users (See Synchronization options on page 146), the users must be read in, in order to resolve Reference Attributes for group members or group owners.
Configuration
81
Description
Server Type
The type of LDAP server that you are using with Directory Sync. If you are using a Lotus Domino, Microsoft Active Directory, or Open LDAP directory server, select that server type. Otherwise, select Other. Example: Microsoft Active Directory
The LDAP attribute that contains a users primary email address. Example: The default is mail.
One or more attributes used to hold alias addresses. These addresses will be added into Google Apps as nicknames of the primary address listed in the Email Address Attribute field. Example: proxyAddresses
82
Release 2.1.5
Description
Only for Lotus Domino servers. One or more attributes used to hold internal Domino alias attributes, which are stored as usernames without domain information. These addresses will be formatted as email addresses and placed as aliases to the primary address listed in the Email Address Attribute field. If you are using a Lotus Domino server but your alias address attribute stores full SMTP email addresses, list the attribute in Alias Address Attributes, not Domino Alias Address Attributes. Example: uid
Only for Lotus Domino servers. If an address contains a space, Google Apps Directory Sync will substitute this character instead. Example: The most common values are dot (.) and underscore (_).
Use Defaults
Click this button to use the default values for your server type, as follows: Lotus Domino: Email Address Attribute mail, Domino Alias Address Attribute uid. MS Active Directory: Email Address Attribute mail, Alias Address Attribute proxyAddresses. OpenLDAP: Email Address Attribute mail. Other: Email Address Attribute mail.
Configuration
83
All attributes are optional. If you do not specify an attribute, Directory Sync will not import this information.
LDAP Extended Attribute Setting
Description
An LDAP attribute that contains each users given name. (In the English language, this is usually the first name.) This is synchronized with the users name in Google Apps. You can also use multiple attributes for the given name. If you user multiple attributes, place each attribute field name in square brackets. Examples: givenName,[cn]-[ou]
An LDAP attribute that contains each users family name. (In the English language, this is usually the last name.) This is synchronized with the users name in Google Apps. Examples: surname,[cn]-[ou]
84
Release 2.1.5
Description
This field is not implemented. Indicates which passwords Directory Sync will synchronize. Options are: Only for new users: When Directory Sync creates a new user, it synchronizes that users password. Existing passwords are not synced. Use this option if you want your users to manage their passwords in Google Apps.
Note: If you are using a temporary or one-
time password for new users, use this option. Only changed passwords: Directory Sync only synchronizes passwords that have changed since your previous sync. This option is recommended if you want to manage user passwords on your LDAP server.
Note: If you use this option, you must also
provide a value for the Password Changed Time Attribute. For new and existing users: Directory Sync always synchronizes all user passwords. Existing passwords on Google Apps are overwritten. This option is appropriate for managing user passwords on your LDAP server, but it is less efficient than the Only changed passwords option.
Example: Only for new users Password Attribute An LDAP attribute that contains each users password. If you set this attribute, your users Google Apps passwords will be synchronized to match their LDAP passwords. The password field supports string or binary attributes. Example: CustomPassword1
Configuration
85
Description
An LDAP attribute that contains a timestamp indicating the last time a users password was changed. Your LDAP server updates this attribute whenever a user changes their password. Use this field only if you select the Only changed passwords option for the Synchronize Passwords field. This field supports string attributes. Example: PasswordChangedTime
86
Release 2.1.5
Description
The encryption algorithm that the password attribute uses. SHA1: Passwords in your LDAP directory server use SHA1 encryption. MD5: Passwords in your LDAP directory server use MD5 encryption. Base64: Passwords in your LDAP directory server use Base64 encoding. Plaintext: Passwords in your LDAP directory server are not encrypted. Directory Sync will read the password attribute as unencrypted text, then immediately encrypt the password using SHA1 encryption and synchronize with Google Apps.
Note: Directory Sync never saves, logs, or
transmits passwords unencrypted. If passwords in your LDAP directory are Base64-encoded or plaintext, Directory Sync immediately encrypts them with SHA1 encryption and synchronizes them with Google Apps. Simulate sync and full sync logs show the password as a SHA1 password. Use this field only if you also specify a Password Attribute. If you leave the Password Attribute field blank, when you save and reload the configuration resets to the default of SHA1. Note that some password encoding formats are not supported. Check your LDAP directory server with a directory browser to find or change your password encryption. By default, Active Directory and Lotus Domino directory servers do not store passwords in any of these formats. Consider setting a default password for new users and requiring users to change passwords on first login. Example: SHA1
Configuration
87
Description
When checked, new users must change passwords the first time they log in to Google Apps. This allows you to set an initial password, either from an LDAP attribute or by specifying a default password for new users, that must be changed the first time the user logs on to their Google Apps account. Use this option if you are using temporary or one-time passwords.
Enter a text string that will serve as the default password for all new users. If the user does not have a password in the password attribute, Directory Sync will use the default password.
Important: If you enter a default password
here, be sure to enable Force new users to change password so that users will not keep their default password. Example: swordfishX2! Google Apps Users Deletion/ Suspension Policy Options for deleting and suspending users. Available options: Delete only active Google Apps users not found in LDAP (suspended users are retained). Active users in Google Apps will be deleted if they are not in your LDAP, but suspended users are left alone. This is the default setting. Delete active and suspended users not found in LDAP. All users in Google Apps will be deleted if they are not in your LDAP, including suspended users. Suspend Google Apps users not found in LDAP, instead of deleting them. Active users in Google Apps will be suspended if they are not in your LDAP. Suspended users are left alone.
88
Release 2.1.5
Description
When enabled, Google Apps admin accounts are not suspended or deleted, even if they are not present on your LDAP server. Enable this setting to prevent accidental suspension or deletion of admin accounts.
Note: If this setting is enabled and you want to
suspend an admin account, you must either revoke the accounts admin privileges or suspend/delete the account manually.
By default, all users that match these search rules will be added to the Google Apps user list and all users that do not match these search rules will be removed. You can change this behavior with exclusion filters.
Configuration
89
This page shows the list of search rules. In a new configuration, this will be an empty list. To add a search rule, click the Add Search Rule button at the bottom of the screen.
Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP
directory. Instead, limit the LDAP administrator authority on your LDAP directory server, removing access to any OUs on your LDAP directory server that you do not want to synchronize. On the list of Search Rules, you can change existing rules: Reorganize: Click the up arrow or down arrow icon to change the order of search rules. Edit: Click the notepad icon to edit the settings of a search rule. Delete: Click the X icon to delete a search rule.
Search rules are processed in the order listed. If you would like one search rule to take priority over another, move that search rule up using the up arrow icon on this page. If two rules contradict each other, the first rule takes precedence.
90
Release 2.1.5
Description
This option only shows if you have Synchronization of Google Organizations set to Sync LDAP Org Units or Do not create or delete Google Organizations, but move users between existing Organizations in General Settings. Specify which Google Apps org unit should contain users that match this rule. If the org unit specified does not exist, Directory Sync will add the users to the root level org unit in Google Apps. Options include: Org Unit based on Org Units Mappings and DN. This option only shows if you have Synchronization of Google Organizations set to Sync LDAP Org Units in General Settings. Add users to the org unit that maps to the users DN on your LDAP server. This is based on your Org Mappings. This will show in the LDAP User Sync list as [derived]. For more information, see LDAP Org Unit Mappings on page 78. Org Unit Name. Add all users that match this rule to the same Google Apps Org Unit. Specify the org unit in the text field. Example: Users Org Unit name defined by this LDAP Attribute. Add each user to the org unit with the name specified in an attribute on your LDAP directory server. Enter the attribute in the text field. Example: extensionAttribute11
Suspend all users that match this LDAP user sync rule. Directory Sync suspends users that already exist in Google Apps. User data is retained. Directory Sync will add new users that do not yet exist in Google Apps. The new users are added as suspended users, and are not active users. Suspended users will not show up in your Global Address List. Use for an LDAP query that returns deleted or suspended users on your LDAP directory server. If you are importing active users with this rule, leave this unchecked.
Configuration
91
Description
Scope
This determines where in the LDAP directory this rule applies. Choose which option to use: Subtree: All objects matched by the search, and anything under those objects, recursively. Subtree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. One-level provides a limited search that will avoid causing extreme load for very large organizations. Object: Only objects directly matched by the search. No recursion of any kind.Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object.
Example: Subtree Rule The search rule for user sync to match. This rule is a standard LDAP query, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see About LDAP Queries on page 43. Example 1: To match all objects (this may cause load problems):
objectclass=*
92
Release 2.1.5
Description
Base DN
The Base DN (Distinguished Name) to use for this search rule. This will override the default Base DN you specified in LDAP Connection. This field is optional. In most cases, you can leave this field blank and use the Base DN specified in the LDAP Connection page. If you want this rule to use a different Base DN than the default, specify an alternate base DN. Example:
ou=powerusers,ou=test,ou=sales,ou=melbourne,dc= ad,dc=example,dc=com
Configuration
93
Exclusion rules are based on string values and regular expressions, not LDAP settings.
Note: To exclude individual users, add a separate rule for each user.
This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click the Add Exclusion Filter button at the bottom of the screen. In the list of Exclusion Filters, you can change existing filters as follows: Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. Edit: Click the notepad icon to edit the settings of an exclusion filter. Delete: Click the X icon to delete the exclusion filter.
94
Release 2.1.5
In this example, printers are listed as LDAP users and would match the LDAP query given. However, the printers all have the word printer in the name. The rule looks for that substring. Match Type: Substring Match Exclude Type: Primary Address Rule: printer
Two users have opted out of Google Apps and should not be synchronized. Add a separate rule for each special user. First rule: Match Type: Substring Match or Exact Match Exclude Type: Primary Address Rule: atif
Second rule: Match Type: Substring Match or Exact Match Exclude Type: Primary Address Rule: svetlana
About five hundred test users are listed in LDAP, but they are only used for internal load testing. All the test users follow the same name pattern: internaltestX, where X is a number, and all test users are in the same domain. Match Type: Regular Expression Rule: internal-test[0-9]*@example.com
Configuration
95
Match Type
The type of rule to use for the filter. Exact Match: The address must match the rule exactly, with the domain name added on.
Note: In many cases, Substring Match yields better results than Exact Match.
Example: maria (if you are using the domain example.com) would exclude only the user maria@example.com. Substring Match: The address or organization name must contain the text of the rule as a substring. Example: test would exclude testadmin@example.com and salestest1@example.com. Regular Expression: The address or organization must match the regular expression specified. Example: internal.*@example.com would exclude internalhelpdesk@example.com and internal@example.com.
96
Release 2.1.5
Description
Exclude Type
What kind of LDAP data to exclude. Primary Address: Directory Sync will exclude primary addresses that match this rule. The interface displays this choice as ADDRESS. Alias Address: Directory Sync will exclude aliases that match this rule. The interface displays this choice as ALIAS.
If you want to exclude both primary addresses and alias addresses, create two exclusion rules. Rule The match string or regular expression for the exclusion rule. Behavior of this field depends on the Match Type you choose. Addresses that contain this string (or match this regular expression) will not be added to Google Apps, and will be deleted if found. Examples: Exact Match: maria Substring Match: internal-list Regular Expression: internal.*@example.com
Configuration
97
LDAP Groups
Set up synchronization for Google Groups for Enterprise in the LDAP Groups page. Google Groups for Enterprise are similar to LDAP mailing lists, and allow users to send email to multiple recipients with a single email address. You can also use groups to share content, including Google Docs, Sites, Videos and Calendars.
The LDAP Settings section configures how Google Apps Directory Sync generates a list of groups from your LDAP directory server. You may need to collect information from your LDAP directory server before you can enter details in this section.
98
Release 2.1.5
This page shows the list of LDAP Group Sync rules. In a new configuration, this will be an empty list. To add mail lists, click the Add Rule button at the bottom of the screen. In the list of Mail List rules, you can change existing filters as follows: Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. Edit: Click the notepad icon to edit the settings of an exclusion filter. Delete: Click the X icon to delete the exclusion filter.
Configuration
99
The first tab you see is the LDAP tab, which contains information on which LDAP objects to synchronize, and which attributes to use for groups information. To view the groups you have in Google Apps, see the Google Apps control panel.
Reference attribute.
100
Release 2.1.5
Description
Scope
Where to apply the mail list rule. Choose which option to user: Subtree: All objects matched by the search, and anything under those objects, recursively. Subtree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. One-level provides a limited search that will avoid causing load for very large organizations. Object: Only objects directly matched by the search. No recursion of any kind. Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object.
Example: Subtree Rule The LDAP query for Group Sync to match. This allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see About LDAP Queries on page 43. Example: (objectclass=dominoGroup) Base DN The Base DN (Distinguished Name) to use for this search rule. This will override the default Base DN you specified in LDAP Connection. This field is optional. In most cases, you can leave this field blank and use the Base DN specified in the LDAP Connection page. If you want this rule to use a different Base DN than the default, specify an alternate base DN. Example:
ou=powerusers,ou=test,ou=sales,ou=melbourne,dc= ad,dc=example,dc=com
An LDAP attribute that contains the email address of the group. This will become the group email address in Google Apps. Example: mail
Configuration
101
Description
An LDAP attribute that contains the display name of the group. This will be used in the display to describe the group, and does not need to be a valid email address. An LDAP attribute that contains the full-text description of the group. This will become the group description in Google Apps. This field is optional. Example: extendedAttribute6
Member Reference Attribute (Either this field or Member Literal Attribute is required.) Member Literal Attribute (Either this field or Member Reference Attribute is required.) Owner Reference Attribute
An attribute that contains the DN of mailing list members in your LDAP directory server. Google Apps Directory Server looks up the email addresses of these members and adds each member to the group in Google Apps. Example: memberUID An attribute that contains the full email address of mailing list members in your LDAP directory server. Google Apps Directory Server adds each member to the group in Google Apps. Example: memberaddress An attribute that contains the DN of each groups owner. Google Apps Directory Server looks up the email addresses of each mailing lists owner and adds that address as the group owner in Google Apps. This field is optional. Example: ownerUID
An attribute that contains the full email address of each groups owner. Google Apps Directory Server adds that address as the group owner in Google Apps. This field is optional. Example: owner
102
Release 2.1.5
Description
If the group name in your LDAP server contains any spaces, they will be replaced with this. If you leave this blank, Directory Sync will remove spaces and concatenate group names. 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. Text to add at the end of each user name for group members. Text to add at the beginning of each user name for group owners. Text to add at the end of each user name for group owners.
Configuration
103
Exclusion rules are based on string values and regular expressions, not LDAP settings.
This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click the Add Rule button at the bottom of the screen. In the list of exclusion filters, you can change existing filters as follows: Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. Edit: Click the notepad icon to edit the settings of an exclusion filter. Delete: Click the X icon to delete the exclusion filter.
104
Release 2.1.5
Several mailing lists are no longer in use because two nearby offices combined together. The defunct lists all have stpaul in the address. Match Type: Substring Match Rule: stpaul
Three small-distribution LDAP mailing lists are top security and should not be imported. Add a separate rule for each special LDAP mailing list. First rule: Match Type: Exact Match Rule: finance-early-statements
About five hundred test mailing lists are listed in LDAP, but they are only used for internal load testing. All the test users follow the same name pattern: internaltestX, where X is a number, and all test users are in the same domain. Match Type: Regular Expression Rule: internal-test[0-9]*@example.com
Configuration
105
Type
Sets the type of exclusion filter to create: User Name, Group Name, or Member Name. User Name: Do not sync any user whose primary address matches the rule. The interface displays this choice as ADDRESS. Group Name: Do not sync any group which has a name that matches the rule. The interface displays this choice as NESTED_GROUP_NAME. Member Name: Do not sync any user whose primary address matches this rule from any groups. The interface displays this choice as MEMBER_NAME.
Match Type
The type of rule to use for the filter. Exact Match: The address or organization name (minus domain name) must match the rule exactly. Substring Match: The address or organization name must contain the text of the rule as a substring. Regular Expression: The address or organization must match the regular expression specified.
106
Release 2.1.5
Description
Exclusion Rule
The text of the match or regular expression to compare. Addresses that meet the requirements for an exclusion filter will not be added as Google Apps groups.
The LDAP User Profiles section configures how Google Apps Directory Sync generates user profile information from your LDAP directory server. You may need to collect information from your LDAP directory server before you can enter details in this section.
Configuration
107
108
Release 2.1.5
Primary email
LDAP attribute that contains a users primary mail address. This is usually the same as the primary mail address listed in the previous LDAP Users section. Example: mail
LDAP attribute that contains a users job title. LDAP attribute that contains a users company name. LDAP attribute that contains the LDAP Distinguished Name (DN) of the users assistant. LDAP attribute that contains the LDAP Distinguished Name (DN) of the users direct manager. LDAP attribute that contains a users department. LDAP attribute that contains a users office location. LDAP attribute that contains a users Employee ID number. LDAP attribute that contains a users home page or other website. LDAP attribute that contains a users work phone number. LDAP attribute that contains a users home phone number. LDAP attribute that contains a users fax number. LDAP attribute that contains a users personal mobile phone number. LDAP attribute that contains a users work mobile phone number. LDAP attribute that contains a work phone number for a users assistant. LDAP attribute that contains the street address portion of a users primary work address. LDAP attribute that contains the P.O. Box of a users primary work address.
Managers DN
Department Office location Employee ids Websites Work phone numbers Home phone numbers Fax phone numbers Mobile phone numbers Work mobile phone numbers Assistants Number Street Address P.O. Box
Configuration
109
Description
LDAP attribute that contains the city of a users primary work address. LDAP attribute that contains the state or province of a users primary work address. LDAP attribute that contains the ZIP code or Postal Code of a users primary work address. LDAP attribute that contains the country or region of a users primary work address.
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.
110
Release 2.1.5
This page shows the list of search rules. In a new configuration, this will be an empty list. To add a search rule, click the Add Search Rule button at the bottom of the screen.
Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP
directory. Instead, limit the LDAP administrator authority on your LDAP directory server, removing access to any OUs on your LDAP directory server that you do not want to synchronize. On the list of Search Rules, you can change existing rules: Reorganize: Click the up arrow or down arrow icon to change the order of search rules. Edit: Click the notepad icon to edit the settings of a search rule. Delete: Click the X icon to delete a search rule.
Configuration
111
Description
Scope
This determines where in the LDAP directory this rule applies. Choose which option to use: Subtree: All objects matched by the search, and anything under those objects, recursively. Subtree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. One-level provides a limited search that will avoid causing extreme load for very large organizations. Object: Only objects directly matched by the search. No recursion of any kind.Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object.
Example: Subtree Rule The search rule for user profile sync to match. This rule is a standard LDAP query, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see About LDAP Queries on page 43. Example 1: To match all objects (this may cause load problems):
objectclass=*
112
Release 2.1.5
Description
Base DN
The Base DN (Distinguished Name) to use for this search rule. This will override the default Base DN you specified in LDAP Connection. This field is optional. In most cases, you can leave this field blank and use the Base DN specified in the LDAP Connection page. If you want this rule to use a different Base DN than the default, specify an alternate base DN. Example:
ou=powerusers,ou=test,ou=sales,ou=melbou rne,dc=ad,dc=example,dc=com
This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click the Add Exclusion Filter button at the bottom of the screen.
Configuration
113
In the list of Exclusion Filters, you can change existing filters as follows: Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. Edit: Click the notepad icon to edit the settings of an exclusion filter. Delete: Click the X icon to delete the exclusion filter.
In this example, printers are listed as LDAP users and would match the LDAP query given. However, the printers all have the word printer in the name. The rule looks for that substring. Match Type: Substring Match Rule: printer
Two users have opted out of Google Apps and should not be synchronized. Add a separate rule for each special user. First rule: Match Type: Exact Match Rule: atif@example.com
About five hundred test users are listed in LDAP, but they are only used for internal load testing. All the test users follow the same name pattern: internaltestX, where X is a number, and all test users are in the same domain. Match Type: Regular Expression Rule: internal-test[0-9]*@example.com
114
Release 2.1.5
Match Type
The type of rule to use for the filter. Exact Match: The address must match the rule exactly. Example: maria@example.com would exclude only the user maria@example.com. Substring Match: The address or organization name must contain the text of the rule as a substring. Example: test would exclude testadmin@example.com and salestest1@example.com. Regular Expression: The address or organization must match the regular expression specified. Example: internal.*@example.com would exclude internalhelpdesk@example.com and internal@example.com.
Configuration
115
Description
Rule
The match string or regular expression for the exclusion rule. Behavior of this field depends on the Match Type you choose. Addresses that contain this string (or match this regular expression) will not be added to Google Apps, and will be deleted if found. Examples: Exact Match: maria@example.com Substring Match: listinternal Regular Expression: internal.*@example.com
Shared Contacts in Google Apps are contacts that any user can see and use. Shared Contacts correspond to a Global Address List (GAL) in Microsoft Active Directory and other directory servers.
116
Release 2.1.5
You can see Shared Contacts in Google Apps by going to your Inbox and clicking the Contacts link.
The LDAP Shared Contacts section configures how Google Apps Directory Sync generates shared contacts information from your LDAP directory server. You may need to collect information from your LDAP directory server before you can enter details in this section.
Configuration
117
Below are some of the most common reasons to import Shared Contacts: Add groups and outside addresses to autocomplete. User addresses in your domain will show up in autocomplete. However, groups and outside addresses are not visible in autocomplete. Create LDAP sync rules to import any groups or outside addresses you want your users to see when using autocomplete. Give pilot users access to all users for autocomplete. If you are adding a small number of users for a pilot program, consider adding other users as Shared Contacts, so that pilot users will see the address of other users in autocomplete. Provide supplemental directory information to users. If your users want to see rich contact information from your directory server for their contacts (such as postal addresses, phone numbers, companies, and titles), synchronize this information using Shared Contacts. Users will see this additional information in the Contacts page after they have added the contact manually, or sent mail to that contacts address.
Shared Contacts, it may take up to 24 hours for the changes to appear in Google Apps.
118
Release 2.1.5
Sync key
An LDAP attribute that contains a unique identifier for the contact. Choose an attribute present for all your contacts that is not likely to change, and which is unique for each contact. This field becomes the ID of the contact. Examples: dn or contactReferenceNumber
LDAP attribute that contains a contacts full name. LDAP attribute that contains a contacts job title. LDAP attribute that contains a contacts company name. LDAP attribute that contains the LDAP Distinguished Name (DN) of the contacts assistant. LDAP attribute that contains the LDAP Distinguished Name (DN) of the contacts direct manager. LDAP attribute that contains a contacts department. LDAP attribute that contains a contacts office location. LDAP attribute that contains a contacts email address LDAP attribute that contains a contacts employee ID number. LDAP attribute that contains a contacts home page or other website. LDAP attribute that contains a contacts work phone number. LDAP attribute that contains a contacts home phone number. LDAP attribute that contains a contacts fax number. LDAP attribute that contains a contacts personal mobile phone number. LDAP attribute that contains a contacts work mobile phone number.
Managers DN
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
Configuration
119
Description
Assistants Number Street Address P.O. Box City State/Province ZIP/Postal Code
LDAP attribute that contains a work phone number for a contacts assistant. LDAP attribute that contains the street address portion of a contacts primary work address. LDAP attribute that contains the P.O. Box of a contacts primary work address. LDAP attribute that contains the city of a contacts primary work address. LDAP attribute that contains the state or province of a contacts primary work address. LDAP attribute that contains the ZIP code or Postal Code of a contacts primary work address. LDAP attribute that contains the country or region of a contacts primary work address.
Country/Region
By default, shared contacts will be synchronized for all contacts that match these search rules will be added to the Google Apps user list, and removed for shared contacts that do not match these rules. You can change this behavior with exclusion filters.
120
Release 2.1.5
This page shows the list of search rules. In a new configuration, this will be an empty list. To add a search rule, click the Add Shared Contact Search Rule button at the bottom of the screen.
Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP
directory. Instead, limit the LDAP administrator authority on your LDAP directory server, removing access to any OUs on your LDAP directory server that you do not want to synchronize. On the list of Search Rules, you can change existing rules: Reorganize: Click the up arrow or down arrow icon to change the order of search rules. Edit: Click the notepad icon to edit the settings of a search rule. Delete: Click the X icon to delete a search rule.
Configuration
121
Description
Scope
This determines where in the LDAP directory this rule applies. Choose which option to use: Subtree: All objects matched by the search, and anything under those objects, recursively. Subtree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. One-level provides a limited search that will avoid causing extreme load for very large organizations. Object: Only objects directly matched by the search. No recursion of any kind.Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object.
Example: Subtree Rule The search rule for shared contact sync to match. This rule is a standard LDAP query, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see About LDAP Queries on page 43. Example 1: To match all contacts:
(objectclass=contact)
122
Release 2.1.5
Description
Base DN
The Base DN (Distinguished Name) to use for this search rule. This will override the default Base DN you specified in LDAP Connection. This field is optional. In most cases, you can leave this field blank and use the Base DN specified in the LDAP Connection page. If you want this rule to use a different Base DN than the default, specify an alternate base DN. Example:
ou=powerusers,ou=test,ou=sales,ou=melbou rne,dc=ad,dc=example,dc=com
Configuration
123
This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click the Add Exclusion Filter button at the bottom of the screen. In the list of Exclusion Filters, you can change existing filters as follows: Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. Edit: Click the notepad icon to edit the settings of an exclusion filter. Delete: Click the X icon to delete the exclusion filter.
Two contacts have opted out of Google Apps and should not be synchronized. Add a separate rule for each special user. First rule: Match Type: Exact Match Rule: atif@example.com
About five hundred test users are listed in LDAP, but they are only used for internal load testing. All the test users follow the same name pattern: internaltestX, where X is a number, and all test users are in the same domain. Match Type: Regular Expression Rule: internal-test[0-9]*@example.com
124
Release 2.1.5
Description
Match Type
The type of rule to use for the filter. Exact Match: The address must match the rule exactly. Example: maria@example.com would exclude only the user maria@example.com. Substring Match: The address or organization name must contain the text of the rule as a substring. Example: test would exclude testadmin@example.com and salestest1@example.com. Regular Expression: The address or organization must match the regular expression specified. Example: internal.*@example.com would exclude internalhelpdesk@example.com and internal@example.com.
Configuration
125
Description
Rule
The match string or regular expression for the exclusion rule. Behavior of this field depends on the Match Type you choose. Addresses that contain this string (or match this regular expression) will not be added to Google Apps, and will be deleted if found. Examples: Exact Match: maria@example.com Substring Match: listinternal Regular Expression: internal.*@example.com
126
Release 2.1.5
Description
Resource Id
The LDAP attribute or attributes that contain the ID of the calendar resource. This is a field managed on your LDAP system, which may be a custom attribute. This field must be unique.
Important: Calendar Resources does not sync an
LDAP attribute which contains spaces or characters such as the at sign (@) or colon (:). For more information on this calendar resource naming, see the Google Code site article Developing a naming strategy for your calendar resources.
Configuration
127
Description
The LDAP attribute or attributes that contain the domain name for the calendar resource. Example: [city]-[building]-[floor]-Boardroom[roomnumber] Important: Calendar Resources does not sync an
LDAP attribute which contains spaces or characters such as the at sign (@) or colon (:). For more information on this calendar resource naming, see the Google Code site article Developing a naming strategy for your calendar resources. Description (optional) The LDAP attribute or attributes that contain a description of the calendar resource. Example: [description]
Note: Calendar Resource attributes use a different syntax than other Directory
Sync attributes. All attributes in the LDAP Calendar Resources Attributes page can include fixed strings and multiple LDAP attributes. Each LDAP attribute should be marked with square brackets. For instance, if you wanted to use the LDAP attributes city, building, floor, and roomnumber from your LDAP directory, and combine them into a single display name, you might use the following setting for Display Name:
[city]-[building]-[floor]-Boardroom-[roomnumber]
All LDAP attributes should be inside square brackets. All fixed text should be outside the square brackets, in the format in which it should appear in your Google Apps calendar resources.
128
Release 2.1.5
By default, all calendar resources that match these search rules will be added to the Google Apps calendar resources, and all calendar resources that do not match these search rules will be removed. You can change this behavior with exclusion filters. This page shows the list of search rules. In a new configuration, this will be an empty list. To add a search rule, click the Add Search Rule button at the bottom of the screen. On the list of Search Rules, you can change existing rules: Reorganize: Click the up arrow or down arrow icon to change the order of search rules. Edit: Click the notepad icon to edit the settings of a search rule. Delete: Click the X icon to delete a search rule.
Search rules are processed in the order listed. If you would like one search rule to take priority over another, move that search rule up using the up arrow icon on this page. If two rules contradict each other, the first rule takes precedence.
Configuration
129
Description
Scope
This determines where in the LDAP directory this rule applies. Choose which option to use: Subtree: All objects matched by the search, and anything under those objects, recursively. Subtree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. One-level provides a limited search that will avoid causing extreme load for very large organizations. Object: Only objects directly matched by the search. No recursion of any kind. Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object.
Example: Subtree
130
Release 2.1.5
Description
Rule
The search rule for calendar resources sync to match. This rule is a standard LDAP query, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see About LDAP Queries on page 43. Example 1: To match all objects (this may cause load problems):
objectclass=*
Base DN
The Base DN (Distinguished Name) to use for this search rule. This will override the default Base DN you specified in LDAP Connection. This field is optional. If your calendar resources are sorted in a particular OU, this may be a helpful field to use. If you want this rule to use a different Base DN than the default, specify an alternate base DN. Example:
ou=Rooms,ou=melbourne,dc=ad,dc=example,dc=com
Configuration
131
Exclusion rules are based on string values and regular expressions, not LDAP settings.
Note: To exclude individual calendar resources, add a separate rule for each user.
This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click the Add Exclusion Filter button at the bottom of the screen. In the list of Exclusion Filters, you can change existing filters as follows: Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. Edit: Click the notepad icon to edit the settings of an exclusion filter. Delete: Click the X icon to delete the exclusion filter.
132
Release 2.1.5
In this example, printers are listed as LDAP resources and would match the LDAP query given. However, the printers all have the word printer in the name. The rule looks for that substring. Match Type: Substring Match Exclude Type: Calendar Resource Id Rule: printer
Two conference rooms have been converted into offices and should not be imported as Google Apps calendar resources. Add a separate rule for each special user. First rule: Match Type: Substring Match or Exact Match Exclude Type: Calendar Resource Display Name Rule: ConferenceRoom-BlueSkyMontana
Second rule: Match Type: Substring Match or Exact Match Exclude Type: Calendar Resource Display Name Rule: ConferenceRoom-BigPlains
About five hundred test calendar resources are listed in LDAP, but they are only used for internal load testing. All the test resources follow the same name pattern: internal-testX, where X is a number, and all test users are in the same domain. Match Type: Regular Expression Exclude Type: Calendar Resource Id Rule: internal-test[0-9]*@example.com
Configuration
133
Match Type
The type of rule to use for the filter. Exact Match: The address must match the rule exactly, with the domain name added on.
Note: In many cases, Substring Match yields better results than Exact Match.
Example: maria (if you are using the domain example.com) would exclude only the user maria@example.com. Substring Match: The address or organization name must contain the text of the rule as a substring. Example: test would exclude testadmin@example.com and salestest1@example.com. Regular Expression: The address or organization must match the regular expression specified. Example: internal.*@example.com would exclude internalhelpdesk@example.com and internal@example.com.
134
Release 2.1.5
Description
Exclude Type
What kind of LDAP data to exclude. Calendar Resource Id: Directory Sync will exclude calendar resources where the Calendar Resource Id attribute specified in LDAP Calendar Resources Attributes matches this pattern. The interface displays this choice as CALENDAR_RESOURCE_ID. Calendar Resource Display Name: Directory Sync will exclude calendar resources where the Calendar Resource Display Name attribute specified in LDAP Calendar Resources Attributes matches this pattern. The interface displays this choice as CALENDAR_RESOURCE_DISPLAY_NAME
If you want to exclude both primary addresses and alias addresses, create two exclusion rules. Rule The match string or regular expression for the exclusion rule. Behavior of this field depends on the Match Type you choose. Calendar Resource Ids or Display Names that contain this string (or match this regular expression) will not be added to Google Apps, and will be deleted if found. Examples: Exact Match: NewYork-NYC-23-Conference-2 Substring Match: internal-list Regular Expression: internal.*@example.com
Notifications
You can set Configuration Manager so that every time synchronization occurs, Google Apps Directory Sync will send out a notification to one or more users.
Configuration
135
Consider adding a notification to send mail to your own address, and possibly the addresses of any concerned parties in your company.
Note: Notifications are sent by plain SMTP, not TLS.
Enter the From: address for the notification mail. Recipients will see this address as the notification sender. For instance, you might use your own email address. Example: dirsync@example.com
Notifications will be sent to all addresses on this list. Enter any valid email address on any domain. Enter each recipient email address individually, then click the Add button. Depending on your mail server settings, Directory Sync may be unable to send mail to external email addresses. Run a test notification to confirm that mail is sent properly. Example: dirsync-admins@example.com
136
Release 2.1.5
Notifications Setting
Description
The SMTP mail server to use for notifications. Directory Sync uses this mail server as a relay host.
Note: You cannot use Google Apps as your SMTP
Relay Host for Notifications. Example: 127.0.0.1 to run the mail server on the same machine. Example: mail.example.com Username (if needed) Password (if needed) If the SMTP server you specify requires SMTP authentication, enter the user name to use here. Example: admin5 If the SMTP server you specify requires SMTP authentication, enter the Password to use here. Example: swordfish Passwords are stored in the configuration file in an encrypted format. Do not include in notifications (Optional) You can limit the information sent in notifications by checking any of the three checkboxes. All checkboxes are optional. Extra details: Google Apps Directory Sync notifications will not include extra details and potentially extraneous information. Warnings: Google Apps Directory Sync notifications will not include warning messages. Errors: Google Apps Directory Sync notifications will not include error messages.
Test Notification
Click this button to test notifications. Configuration Manager will connect to the SMTP server you specified and send a test notification to the addresses you list.
Sync Limits
As a safeguard, you can limit how many users, groups, and shared contacts Google Apps Directory Sync can delete or suspend during synchronization. This is recommended as a way to prevent accidental mass deletion or suspension.
Configuration
137
Directory Sync checks to be sure that synchronization will not delete or suspend too many users. If the synchronization would delete or suspend more users than the sync limits allow, the entire synchronization fails and no users, groups, or shared contacts are added, moved, suspended, or deleted. This will be noted in the notifications email.
Note: Sync limits apply during synchronization, but not during simulation.
Simulation results will not include sync limits. To set sync limits, specify one of the following:
Delete Limits Setting Description
Specify a maximum percentage of users that can be deleted. This is a percentage of the users registered on Google Apps, not a percentage of users on your LDAP server. If no delete limit is specified, the default is 5%. Example: 5% You can suppress delete limits from the command line.
Specify a maximum number of users, groups, and shared contacts that can be deleted. Example: 25
138
Release 2.1.5
Description
Specify a maximum percentage of users that can be suspended. This is a percentage of the users registered on Google Apps, not a percentage of users on your LDAP server. If no suspend limit is specified, the default is 5%. Example: 5%
Log Files
You can specify the file name and level of detail of logging for Google Apps Directory Sync.
File name
Enter the directory and file name to use for the log file or click Browse to browse your file system. Example: sync.log
Configuration
139
Logging Setting
Description
Log Level
The level of detail of the log. Options are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. The level of detail is cumulative: each level includes all the details of previous levels. ERROR includes all ERROR and FATAL messages, and so on. FATAL only logs fatal operations. ERROR only logs errors and fatal operations. WARN only logs warnings, errors and fatal operations. INFO logs summary information. DEBUG logs more extensive details. TRACE logs all possible details.
The maximum size of the log file, in gigabytes. When this file reaches half capacity, it is saved as a backup file (which overwrites any existing backup file) and a new file is created. At any time, the total size of these two files (the log file and the backup log file) will not exceed the total maximum size. Example: 4
Simulate Sync
After you enter configuration information, use this section to verify and test your Google Apps Directory Sync settings. Configuration Manager does not check for valid LDAP syntax. To find invalid LDAP queries, use Simulate Sync. Invalid LDAP queries will cause errors. For information on common errors that might occur and how to troubleshoot them, see Common Issues on page 151.
140
Release 2.1.5
Simulate Sync
When you first go to this page, you will see Validation Results. This page will show a checklist of all the Configuration Manager sections. If you are missing required information, you will see error messages showing what needs to be added.
Important: This checklist confirms only the minimum needed for synchronization.
You may need to configure additional filters or rules to be sure the results are what you expect. Once youve completed all required fields, you will be able to use the Simulate Sync button to simulate a synchronization.
Configuration
141
After you complete a test synchronization, results from the Google Apps server are cached. To flush the remote cache for the next synchronization, click the Clear Cache button.
After you complete a test synchronization, results from the Google Apps server are cached. To flush the remote cache for the next synchronization, click the Clear Cache button. Once youre ready, click Simulate Sync. You will see the Simulate Sync page. During simulation, Configuration Manager will: Connect to Google Apps and generate a list of users, groups, and shared contacts. Connect to your LDAP directory server and generate a list of users, groups, and shared contacts. Generate a list of differences. Log all events. If connection was successful, show a Proposed Change Report which shows what changes would have been made to your Google Apps user list.
Note: Simulate Sync will never update or change your LDAP server or your users
in Google Apps. The simulation is strictly for configuration and testing. To run an actual synchronization, use the command line. See Synchronization on page 145 for more.
142
Release 2.1.5
Review the Simulation Results to confirm that the simulation occurred correctly without any unexpected results.
If any errors occur, check the error text. Most error text is human readable, but some error text may contain Java stack trace errors. If you need help troubleshooting these errors, see Troubleshooting on page 151. If the synchronization was successful, check the Proposed Change Report and review it for unexpected results.
Note: The Proposed Change Report doesnt check your delete limits.
If you see any errors or unexpected results, you can go back and change your configuration to try again. To change your configuration, click on any of the headings on the left navigation bar. You can switch between the Validation Results and Simulation Results pages using the buttons at the bottom of the page. You can also run another simulation from either page by clicking the Simulate Sync button at the bottom. Once you are finished, save your configuration file and run synchronization. See Synchronization on page 145.
Configuration
143
144
Release 2.1.5
Chapter 7
Synchronization
Chapter 7
About Synchronization
Run the synchronization command to push your LDAP directory server user information to Google Apps. Directory Sync uses the command sync-cmd to run synchronization. This simple command line interface gives you the flexibility to incorporate synchronization into any scheduling or batch script you wish to use. Before you can synchronize Google Apps with your LDAP directory server, you must create rules that detail how to connect to both servers, and what filters and rules to use. These rules are stored in an XML file. To create this XML file, run Configuration Manager. For more information about Configuration Manager, see Configuration on page 51. Most administrators run their first synchronization manually to test the process, import an initial set of users, and confirm the changes. After initial synchronization with the command line, you can set up automatic scheduling for future synchronization.
Run without any arguments, this command gives an error and directs you to run sync-cmd -h for help. To synchronize, use the following command line to read a configuration file, check to be sure that a sync is not already running, connect to both servers, generate a list of changes, and apply those changes:
sync-cmd -a -o -c [filename]
Synchronization
145
Replace [filename] with the name of the XML file you created in the Configuration Manager.
Synchronization options
The table below describes the possible arguments to the sync-cmd command. You can also see this information by running the following:
sync-cmd -h
Restrict to one instance per config file. Only valid with -a. Write reports to the specified output file, in addition to writing them to the log. Apply detected changes.
Note: If you do not use this tag, the
-r,--report-out
-a,--apply
synchronization is a test only and will not affect your Google Apps account. For best results, run a test without this flag before running a full synchronization with this flag.
-V
Display detailed application version information. Does not synchronize. Specify the configuration to load. Synchronization will not occur without a valid XML file for this argument. Ignores any configured delete limits. For support troubleshooting only (slows sync)
WARNING: This option is intended only to resolve specific troubleshooting issues. Improper use can cause performance degradation. Do not use this option unless directed by support.
-c,--config [filename]
-g, --groups
Do not analyze groups. Use this option if you want to synchronize users, but not groups. View this information and exit.
-h,--help
146
Release 2.1.5
Values
Override the default and/or configured log level with the specified value. Valid values (in increasing order of verbosity) are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. In most cases, the recommended log level is INFO.
-s, --sharedcontacts
-u, --users
Do not analyze users. Use this option if you want to synchronize groups, but not users. Display short application version information.
-v
Scheduling Synchronization
Once you have successfully run a manual synchronization, you can set up automatic synchronization. Use existing third-party scheduling software to automate synchronization. In most cases, scheduled synchronization runs every one to six hours. The exact timing will vary based on the number of users you have and how often you need to update them. A large company with many users changing frequently may need to run Directory Sync multiple times daily, while a small company with few changes may not need to run the utility more than once a week. The exact method to schedule this task depends on the operating system in which Directory Sync is installed. In Microsoft Windows, use Scheduled Tasks. In Linux or Solaris, use cron. Steps for how to do this are listed below. You can also use any other scheduling software that can launch commands from the command line interface.
Important: When scheduling synchronization, be sure to schedule regular use of the checkforupdate.exe command as well, so that you can regularly check for
new versions of Google Apps Directory Sync.Microsoft Windows: Scheduled Tasks In Microsoft Windows, schedule synchronization using Scheduled Tasks.
Note: These steps apply to most common Microsoft Windows configurations.
Scheduled Tasks is a third-party product and is not supported directly by the Google (or Postini) team. In the event of a Scheduled Tasks issue, contact your Windows administrator.
To schedule a task
Synchronization
147
2. Double-click Add Scheduled Task. 3. Complete the Scheduled Task wizard using the following information. (Steps may vary depending on your version of Microsoft Windows.) Choose the program sync-cmd.exe, located where Directory Sync is installed. The frequency of the task depends on your synchronization needs. A large company with many users changing frequently may need to run Directory Sync multiple times daily, while a small company with few changes may not need to run the utility more than once a week. Use Advanced Properties to specify an exact command line. The appropriate command line is:
[path]\sync-cmd -a -c [filename]
Replace [path] with the path where Directory Sync was installed. Replace [filename] with the name of the XML file you created in the Configuration Manager. 4. Test the scheduled task by running manually once. In the Scheduled Tasks window, right-click the task you created and select Run from the right-click menu. Check the log file for errors.
and Solaris are third-party products and are not supported directly by the Google (or Postini) team. In the event of an issue with cron, contact your administrator.
To add a cron job
1. Run crontab -e to update the crontab file. 2. Add a line in the crontab file for the following command:
sync-cmd -a -c [filename]
The syntax of this line will depend on your operating system and version of cron. For instance, to schedule the task to run at 3:30 AM twice per week, on Monday and Thursday, add the following entry:
30 3 * * 1,4 [path]/sync-cmd -a -c [filename]
Replace [path] with the path where Directory Sync was installed.Replace [filename] with the name of the XML file you created in the Configuration Manager. 3. Save the crontab file and exit your text editor.
148
Release 2.1.5
Monitoring
After you have set up scheduled synchronization, make a policy of regularly checking the status of your synchronizations. Check Notification messages on a regular basis for signs of any problems. Notifications will be sent to an address that you specify. For more information about Notifications, see Notifications on page 135. When looking through notifications logs, look for messages that indicate that users were synchronized. If you expect that a particular user will be synchronized and the user isnt, check the notifications for information. Also, check for new updates regularly. You can use the command checkforupdate.exe in the same directory as sync-cmd.exe, to check online for new versions of Google Apps Directory Sync.
Synchronization
149
150
Release 2.1.5
Chapter 8
Troubleshooting
Chapter 8
About Troubleshooting
This chapter covers information about how to troubleshoot problems that may occur with Google Apps Directory Sync. Troubleshooting information includes information about common issues, system tests and researching issues. For information about LDAP queries, see About LDAP Queries on page 43.
Common Issues
The following describes common issues and questions related to Google Apps Directory Sync.
Configuration Manager
When creating an exception rule, the dialog box does not have an OK button.
You may be using a font that is too large for the screen. The dialog box does not work with Extra Large Fonts or Large Fonts. Change your font size, or edit your XML file directly.
Troubleshooting
151
What port numbers should be used in Google Apps Directory Sync when connecting to Global Catalog server?
By default, Google Apps Directory Sync connects to an LDAP server with the standard LDAP port 389 to query users from a single domain/LDAP server. If you need to query users over multiple domains/LDAP servers that have trust relationship, configure Google Apps Directory Sync to connect to a Global Catalog server with the standard Global Catalog server port 3268.
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 40.
How does Google Apps Directory Sync handle suspended users?
Google Apps Directory Sync is unable to detect suspended users, and will not try to delete them. If Google Apps Directory Sync tries to add a suspended user, you will see an error message: EntityAlreadyExists (1300).
Error Message: DomainUserLimitExceeded (error code 1200)
You attempted to add more users than you have licensed seats. Contact your sales representative to purchase more user licenses, or change your LDAP queries to synchronize fewer users.
Error Message: UserDeletedRecently (error code 1100)
Directory Sync tried to add a user who was deleted. When you delete a user, you cant add that user until 5 days pass. Wait 5 days, or contact support for help.
Where can I find a list of other error messages and their meanings?
Other error messages are listed in the Error Codes section of the Google Apps Provisioning API Developers Guide.
152
Release 2.1.5
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 Google Apps Directory Sync 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.
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.
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
443 443
Troubleshooting
153
Purpose
Port Number
80
80
For an up-to-date list of Google IP addresses, run a DNS TXT lookup of the subdomain _netblocks.google.com. If Directory Sync is unable to connect to the revocation list providers, you may see the following error in your Directory Sync 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.
Directory Sync 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?
Google Apps Directory Sync stores passwords using a two-way encryption scheme. This protects your sensitive information from casual snooping or reverse engineering. To convert a configuration file to the new format with encrypted passwords: 1. Open the file in Configuration Manager. 2. Save the file again. You can also upgrade the file with the following command-line executable:
upgrade-config -c [filename]
versions.
154
Release 2.1.5
You will need to download an LDAP browser. An LDAP browser allows you to browse through an LDAP directory server and identify all fields and values. Many directory servers do not include a complete LDAP browser. For information on LDAP browsers, see Step One: Install LDAP Browser on page 22.
An LDAP query that includes a wildcard isnt working with Lotus Domino LDAP
Lotus Domino has a setting for Minimum characters for wildcard search that controls how wildcard LDAP searches work. Update your search to include more characters, or change this setting to a lower number.
System Tests
If you encounter problems, use the tests in Configuration Manager to find the problem: 1. In Configuration Manager, open the XML file you are using for configuration. 2. Under LDAP Connections, click Test Connection to confirm you can connect to your LDAP server. 3. Under Notifications, click Test Notification to confirm you can send a test notification. 4. Under Simulate Sync, confirm you have filled out all required fields. 5. Under Simulate Sync, click Simulate Sync to confirm that synchronization is running properly. If you encounter any problems, note which tests failed and confirm that the configuration information is correct for those sections of Configuration Manager.
Troubleshooting
155
Escalating Problems
If you are unable to run Directory Sync, and cannot resolve the problem using system tests, collect the following information for troubleshooting: The most current sync log file, located in the folder where Directory Sync is installed. Support will often request that you capture log file information with your log level set to TRACE to collect more information. The version number of Directory Sync you are running. You can find this in the Configuration Manager UI by going to Help->About, or you can run the command sync-cmd -V. The current config file you are using. This is an XML file (default name sync.xml) located in the same folder where Directory Sync is installed. The brand and version of the LDAP directory server you're using. The operating system on the machine where Directory Sync is running.
Once you have collected this information, check the help center or contact support for help.
156
Release 2.1.5