Google Apps Directory Sync Administration Guide Release 4.0.
Google, Inc. 1600 Amphitheatre Parkway Mountain View, CA 94043 www.google.com Part number: GADS_4.0.2 November 5, 2014 © Copyright 2014 Google, Inc. All rights reserved. Google, the Google logo, Google Message Filtering, Google Message Security, Google Message Discovery, Postini, the Postini logo, Postini Perimeter Manager, Postini Threat Identification Network (PTIN), Postini Industry Heuristics, and PREEMPT are trademarks, registered trademarks, or service marks of Google, Inc.
This product includes software developed by The Apache Software Foundation (http://www.apache.org/). Portions of Derby were originally developed by International Business Machines Corporation and are licensed to the Apache Software Foundation under the “Software Grant and Corporate Contribution License Agreement”, informally known as the “Derby CLA”.
Release 4.0.
Contents About This Guide 9 What This Guide Contains 9 Related Documentation 9 How to Send Comments About This Guide 10 Chapter 2: Overview of Google Apps Directory Sync What Is Google Apps Directory Sync? 11 How Directory Sync Works 11 What Is Synchronized 13 Directory Sync and Deployment 15 System Requirements 19 11 Chapter 3: Getting Started 23 Overview 23 Step One: Install LDAP Browser 24 Step Two: Collect LDAP Inventory 25 Step Three: Decide What to Synchronize 28 Step Four: Prepare Google Apps fo
Configuration Best Practices 51 General Settings 52 Google Apps Configuration 53 Google Apps Connection Settings 54 Google Apps Proxy Settings 57 Google Apps Exclusion Rules 58 LDAP Configuration 64 LDAP Connection Settings 65 LDAP Org Units 66 Org Unit Mappings 67 Org Unit Search Rules 70 Org Unit Exclusion Rules 72 User Accounts 76 User Attributes 77 Additional User Attributes 79 User Search Rules 84 User Exclusion Rules 87 Groups 91 Group Search Rules 92 Group Exclusion Rules 98 User Profiles 101 User Pr
Escalating Problems 145 Contents 7
Release 4.0.
About This Guide What This Guide Contains The Google Apps Directory Sync Administration Guide provides information about: • Google Apps Directory Sync features • Basic steps for installing Directory Sync on your server • Configuration for Directory Sync • Synchronizing users, groups, and shared contacts • Troubleshooting Directory Sync This guide is intended for administrators who are already familiar with Google Apps and with LDAP directory servers.
Document Description Google Apps Directory Sync Release Notes Release Notes for Google Apps Directory Sync. This is kept up to date with the changes in the latest version, including release schedules, new features, resolved issues, and known behavior changes. Google Apps Directory Sync for Email Security Another version of Google Apps Directory Sync. Google Apps Directory Sync for Email Security synchronizes with Message Security and Delivery (powered by Postini) instead of Google Apps.
Chapter 2 Overview of Google Apps Directory Sync Chapter 2 What Is Google Apps Directory Sync? Google Apps Directory Sync (also called Directory Sync or GADS) is a utility that automatically adds, modifies, and deletes your users, OUs, groups, shared contacts, and calendar resources in Google Apps to match your LDAP directory server. When you synchronize, Google Apps changes to match your LDAP directory. GADS runs on your LDAP server and updates Google Apps to match your LDAP directory.
Technical Overview GADS includes two connected tools: Configuration Manager and the sync-cmd synchronization command line utility. Configuration Manager is a GUI-based wizard that walks you through the steps of configuring a synchronization. In Configuration Manager, you set up what data to synchronize, specify LDAP query rules, list which attributes contain the information you want to synchronize, specify server connections, and note any exclusion rules.
Security GADS has the following security features: • It runs inside your network, on a machine you control. • It connects to your LDAP server inside your network through Standard LDAP or secure LDAP + SSL. This connection occurs on any port you specify, but defaults to standard LDAP ports. • It connects to Google Apps through the Internet via HTTPS on port 443. This connection can also run through a proxy host in your network. • It connects to any mail server using standard SMTP or SMTP over TLS.
LDAP Google Apps Synchronizes Notes User Aliases Nicknames Other email addresses also used by a given primary address. Each user can have multiple nicknames in Google Apps, and these can come from multiple LDAP alias attributes. Passwords Passwords GADS can only synchronize passwords that are stored in SHA-1 or MD-5 format with no salted hashes. Alternatively, passwords can be managed separately, or authentication can be handled by SSO (Single Sign-On).
Directory Sync and Deployment GADS can be used during different stages of the Google Apps deployment cycle. This section discusses the three-phase deployment model recommended for implementing Google Apps, and how Directory Sync fits into this model. For a tutorial on the three-phase deployment model, see the video Planning Your Google Apps Deployment. The Three-Phase Deployment Model The methodology described in this section is based on field studies and real-world deployment experience with Google Apps.
If you have already added users through another method, and begin using GADS afterwards, you may move directly to Global Go Live and continue through maintenance. In this case, you would not set up a Core IT or Early Adopter phase, and you would set up GADS to synchronize your users and maintain Google Apps to match your LDAP data going forward. Plan Users: No users added yet. Before you begin with the Core IT phase, there’s a period of preparation and planning.
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.
Global Go Live Users: All users active in Google Apps. In the Global Go Live phase, all users become active and begin using Google Apps for daily business. Mail flow is routed entirely to Gmail, users schedule their activities in Google Calendar, and day-to-day user activities run in Google Apps. After your Global Go Live date, data from legacy systems may be migrated into Google Apps, or may be left on legacy servers and checked when needed.
If you remove any users from your company, update Google Apps to reflect these changes. Many companies remove a user by changing the user’s password and access permissions, rather than deleting the user from Google Apps, in order to smoothly handle the user’s documents and mail archives. Directory Sync: Check your notification messages regularly to be sure that GADS is running smoothly, and to detect and address any issues that arise. You can use GADS to keep your Google Apps directory up to date.
Server Requirements • A server to run GADS. The server should run one of the following operating systems: • Microsoft Windows (supported on XP, Windows 7, Windows 8, Windows Server 2003/2008/2012) • Linux • If you’re using a 32-bit version of GADS on a 64-bit Linux system, a 32-bit libc (such as libc6-i386) must be installed. • At least 5 GB of disk space for log files and data. If you are running with DEBUG or INFO level of logging, you may need more free space than this for additional log data.
Depending on your configuration, you may need the following levels of expertise for implementing GADS: • Google Apps administrator: Access to your Google Apps administrator account and familiarity with the Google Apps control panel. • LDAP administrator: Access to your directory server and familiarity with its contents. Familiarity with LDAP query language. • Network administrator: Familiarity with your network and security settings for internal and outbound traffic.
Release 4.0.
Chapter 3 Getting Started Chapter 3 Overview This chapter discusses the steps you’ll take when you get started with Google Apps Directory Sync (GADS). Your GADS configuration will be faster and smoother if you collect information about your network, LDAP directory server, LDAP data, and synchronization plans before you begin. This chapter also includes necessary steps for setting up your Google Apps account and your internal network before you install GADS.
5. Prepare your server environment for synchronization. Confirm that you have a notification mail server ready. For more information, see “Step Five: Prepare Your Servers for Synchronization” on page 39. 6. Install GADS. Once you have the needed information, download and install GADS. This step is covered in “Installation” on page 45. 7. Configure GADS. Run Configuration Manager, part of GADS, to configure synchronization. This step is covered in “Configuration” on page 49. 8. Simulate synchronization.
JXplorer To download the JXplorer Java Ldap Browser, go to: http://www.jxplorer.org Step Two: Collect LDAP Inventory You can deploy GADS more quickly if you identify your LDAP resources beforehand. Depending on the size and structure of your organization, you may already know all this information, or you may need to do some research. Identify LDAP Resources Contact your LDAP administrators and collect the following information: • The hostname or IP address of your LDAP server.
Research LDAP Structure Use an LDAP browser to collect information about your LDAP server and structure. You may find, while preparing for synchronization, that you have unexpected or non-standard data in your LDAP directory server. It is always better to find and address this before you begin synchronizing. Be sure to collect the following key information: • LDAP Base DN: GADS will use this Base DN as the top level for all LDAP queries. You can use an LDAP browser to collect this information.
When conducting LDAP cleanup, consider the following actions. • Identify users. Identify which users you want to synchronize with Google Apps. You may need to consult with your human resources department to confirm that your user list is the correct list of users to synchronize. • Populate Password Attribute (Optional). If you are using a password field in GADS, create a custom attribute in your LDAP for your Google Apps users, and populate the attribute with a password setting.
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.
Note: GADS does not create a domain for you, so you will need to add the domain before you use Directory Sync. Collect the exact domain name from the Google Apps control panel. Note that you cannot synchronize a domain alias. • Domain Name Replacement: You can also specify another domain. Directory Sync will create or update all users in the new replacement domain. This is most often used for a pilot domain, but can also be used if you are using GADS to move to a new domain.
queries, see “About LDAP Queries” on page 41. WARNING: Check to be sure that you are importing the correct number of users. If you import more users than you have licenses in Google Apps, you may experience errors during synchronization for exceeding your user limit. • User Profiles: If your LDAP directory server includes further information, such as addresses, phone numbers, or contact information, you can synchronize this information into Google Apps.
• Mailing Lists: Decide which mailing lists you want to synchronize from your LDAP directory server into Google Apps. Mailing lists on your LDAP directory server will be imported as groups in Google Apps. You may not want to import all mailing lists, since some lists may be internal lists, or company resources such as rooms or printers, or may contain unusable data. GADS will not modify or overwrite groups that users create with the Google Groups for Work service.
Autocomplete addresses. Important: Shared Contacts do not show up immediately. After you synchronize Shared Contacts, it may take up to 24 hours for the changes to appear in Google Apps. • Do you want to synchronize Calendar Resources? If you want to import calendar resources (such as conference rooms) from your LDAP into Google Apps, configure Calendar Resources synchronization. Calendar Resources are visible to every user when attempting to schedule calendar events.
passwords. Because this password may be guessed by other users, this is not generally recommended as a secure option. Important: Be careful of the security considerations of passwords. Also, note that if you use a plaintext password, be sure to set GADS to synchronize passwords only for new users, and to require new users to change passwords. Mapping Decide how your LDAP directory server data should map to your Google Apps data.
For more information about deployment phases and the 3-phase deployment model, see “Directory Sync and Deployment” on page 15. Goals in this phase Core IT Early Adopter Go Live Maintenance Clean up data and prepare for migration in Early Adopter phase. Test connectivity and synchronization. By the end of the Early Adopter phase, you should have GADS ready for your Global Go Live date. Switch users over to Google Apps. Set Google Apps up as primary service.
Core IT Early Adopter Go Live Set up exceptions for manuallyadded Core IT users, temporary administrators, or other users that are not part of your LDAP search rules. Synchronize your early adopters or add them manually. Mark which users are activated in your LDAP directory. Set up exceptions for Google Apps users that are not listed in your LDAP directory. Maintenance Users Create an LDAP OU, group, or custom attribute for users that will be synced into Google Apps.
Core IT Early Adopter Go Live Maintenance You can synchronize Google Apps users as suspended users for testing Google Apps functionality. Suspended users can be used for early migration of data. Usually not used after go live date, but available if you want to suspend users instead of deleting them. Usually not used after go live date, but available if you want to suspend users instead of deleting them. Most mailing lists will still be maintained on legacy server.
Core IT Early Adopter Go Live Maintenance Optionally, you can synchronize all users as shared contacts so that they will be visible in Autocomplete. If your company directory has shared contacts, you can synchronize these during your Go Live synchronization. If your company directory has shared contacts, you can synchronize these during your Go Live synchronization. Note that personal contacts are not synchronized. Note that personal contacts are not synchronized.
The administrator decides that MobiStep needs to synchronize: • OUs • Users • Aliases • Groups (mailing lists) • Shared contacts • Calendar resources The mailing lists in the LDAP server use the attribute member to store the members of each mailing list, and the member attribute contains the full DN of the mailing list members, rather than their email address. The GADS administrator notes this attribute, and notes that it is a reference attribute, not a literal attribute.
Step Five: Prepare Your Servers for Synchronization Be sure that your servers and network are prepared for GADS. Notifications Mail Server GADS is designed to be used for scheduled synchronization without supervision, once synchronization rules are set up. Because of this, you will need a mail server that can relay reports from GADS. Collect the following information: • The addresses that should receive notifications. • The address the notifications should come from.
Release 4.0.
Chapter 4 LDAP Queries Chapter 4 About LDAP Queries GADS uses the LDAP query language to collect data from your directory server. Before you can synchronize data from your directory server, you will need to prepare LDAP queries. The LDAP query language is a flexible standard that supports complex and powerful logical queries, and is discussed in this section. Google Apps Directory Sync strictly adheres to RFC 2254, which defines international standards on LDAP filters.
Name of Operator Character Use Any * Wildcard to represent that a field can equal anything except NULL. Parentheses () Separates filters to allow other logical operators to function. And & Joins filters together. All conditions in the series must be true. Or | Joins filters together. At least one condition in the series must be true. Not ! Excludes all objects that match the filter. For examples of how these operators are used, see the common LDAP queries below.
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=
Release 4.0.
Chapter 5 Installation Chapter 5 About Installation Google Apps Directory Sync (GADS) is designed to run on Windows or Linux servers. The installer is an executable program that installs all needed components on the server, including managing libraries, classpath variables, and other components. The installer also uninstalls any existing version of GADS in the same directory. The sections below contain system requirements, and instructions on how to install, upgrade or uninstall GADS on your server.
3. Download and run the installer. 4. Complete all the steps of the installer. The installer contains all needed components and can be run offline without any outside connection. Note: To run synchronization, you must also enable APIs on your Google Apps domain. See “Enable APIs” on page 38. Upgrade Google Apps Directory Sync GADS automatically checks to see if there are any updates available. If updates are available, you will be prompted to upgrade when you start Configuration Manager.
If you upgrade GADS and then open a configuration file that you created in a previous version, you need to save that configuration file with the current version before you can continue using it to sync. Before saving, make sure your configuration was imported into the current version correctly. Uninstall Google Apps Directory Sync GADS also includes an uninstaller. To remove GADS: 1. Open a command line interface and go to the directory that contains GADS. 2. Run the following command: uninstall 3.
Release 4.0.
Chapter 6 Configuration Chapter 6 About Configuration Configuration Manager is a step-by-step graphical user interface that walks you through creating and testing an XML configuration file for Google Apps Directory Sync (GADS). To start the application, run the GADS Configuration Manager from the Start menu, or run config-manager from the command line in the directory where you installed Directory Sync.
GADS includes several ways to customize search rules and filters. When collecting information from your LDAP server, you can define LDAP queries to extract information. Directory Sync supports RFC 2254, the international standard on LDAP Filters. For the details, see RFC 2254: http://www.ietf.org/rfc/rfc2254.txt GADS also includes some non-LDAP filters. In these, you can use regular expressions to filter for patterns of text.
An LDAP query that would return too many results may time out. If this happens, do not create multiple configuration files to reduce load, because this will actually slow down performance of Google Apps Directory Sync. Instead, consider using a single configuration file with multiple LDAP queries.
General Settings You specify which categories of object to synchronize from your LDAP server on the General Settings page. Specify the following: General Setting Description Organizational Units Whether GADS should synchronize organizational units. Unchecked by default. Users Accounts Whether GADS should synchronize users. Checked by default. For more information, see “User Accounts” on page 76. Uncheck if you do not want to synchronize users. 52 Release 4.0.
General Setting Description Groups Whether GADS should synchronize groups. Checked by default. For more information, see “Groups” on page 91. Uncheck if you do not want to synchronize groups. User Profiles Whether GADS should synchronize user profiles. Unchecked by default. For more information, see “User Profiles” on page 101. Check if you want to synchronize user profiles. Shared Contacts Whether GADS should synchronize shared contacts. Unchecked by default.
Google Apps Connection Settings Enter your Google Apps connection information in this section. Specify the following: Google Apps Setting Description Primary Domain Name The primary domain you want to synchronize. You must use your primary domain in Google Apps, not a domain alias.
Google Apps Setting Description Replace domain names in LDAP email addresses (of users and groups) with this domain name. If checked, all LDAP email addresses are changed to match the domain listed in Domain Name. For instance, if your Domain Name is example.com, and your LDAP query returns an email address user23@domain.com, then Directory Sync synchronizes user23@example.com. If unchecked, all LDAP email addresses keep their original domain name.
Authorizing using OAuth Click Authorize Now to set up your Authorization settings and create a verification code. Note: Customer who already use OAuth will need to authorize again with existing (or new) credentials. This is because GADS now uses the Directory API instead of the deprecated Provisioning and Profiles Data APIs, which means the scope for which the tokens were generated has also changed. 1. Click Sign In to open a browser window and sign in to Google Apps. 2.
Google Apps Proxy Settings Provide any necessary network proxy settings here. If your server does not require a proxy to connect to the internet, skip this page. Provide the following: Google Apps Setting Description SSL Proxy Host Name If your server is running behind a firewall that requires an SSL proxy to connect to an outside server, enter the proxy host name here. (if needed) If you can connect directly to the internet from this machine, leave this field blank. Example: firewall02-http.
Google Apps Setting Description SSL Proxy Password Your SSL proxy password (if any). Example: swordfish (if required) HTTP Proxy Host Name (if needed) Enter the HTTP proxy host you use for HTML connections, even if it is the same as the proxy server you use for SSL connections. Example: firewall02-http.mixateriacorp.com Note: Directory Sync always connects to Google Apps on SSL. The only time Directory Sync sends traffic by unencrypted HTTP is to validate a certificate with the issuing authority.
Exclusion rules are based on string values and regular expressions, not LDAP settings. You can exclude user profiles or shared contacts by their primary sync key. This page shows the list of exclusion filters. In a new configuration, this contains no exclusion rules. To add new exclusion filters, click Add Exclusion Rule. In the list of Exclusion Filters, you can change existing filters as follows: • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters.
For instance, if you add all your IT administrators to the organization path “administrators/IT” and your security administrators in the organization path “administrators/security” you could use the following rule to exclude both groups of users, as well as any others under the administrators organization: • Type: Organization Complete Path • Match Type: Substring • Exclusion Rule: administrators Users not in your LDAP Server Directory Sync will delete users from your list of Google Apps users and fr
Custom Google Apps Groups If you have groups listed in Google Apps that don’t match a mailing list in your LDAP directory server, Directory Sync will delete them, Therefore, add the following rule. • Type: Group Name • Match Type: Exact Match • Exclusion Rule: FloridaSalesTeam@example.com External Mailing List Members Groups in Google Apps can also include mailing address that are outside your domain. Google Apps Directory Sync will remove these unless you add a Member Name exclusion filter.
In 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.
Exclusion Rule Setting Description Match Type The type of rule to match for the filter. • Exact Match: The address or organization name must match the rule exactly. Examples: User Name: user1@example.com excludes that single Google Apps user from user list synchronization, but not group synchronization. Group Name: FloridaSalesGroup@example.com excludes that Google Apps group from groups synchronization. Member Name: user1@example.com excludes that single Google Apps user from groups synchronization.
Exclusion Rule Setting Description Exclusion Rule The text of the match or regular expression to compare. See above for examples for these rules. Users that meet the requirements for an exclusion filter will not be deleted. If they are listed on the LDAP server, Directory Sync will attempt to add the user and fail. LDAP Configuration The LDAP Configuration section configures how Directory Sync connects to your LDAP directory server and generates your LDAP user list for comparison.
LDAP Connection Settings Specify your LDAP connection and authentication in this page. LDAP Connection Setting Description Server Type The type of LDAP server you are syncing. Make sure to select the correct type for your LDAP server; GADS interacts with each type of server slightly differently. Example: MS Active Directory Connection Type Choose whether to use an encrypted connection. If your LDAP server supports an SSL connection and you wish to use it, choose LDAP + SSL.
LDAP Connection Setting Description Authentication Type The authentication method for your LDAP server If your LDAP server allows anonymous connections and you want to connect anonymously, select Anonymous. Otherwise, select Simple. Example: Simple Authorized User Enter the user who will connect to the server. This user should have read and execute permissions for the whole subtree. If your LDAP directory server requires a domain for login, include the domain for the user as well.
Org Unit Mappings This shows a list of rules used when generating the LDAP org units. Specify how OUs on your LDAP server correspond to Org Units in Google Apps. Add mappings for top-level Org Units, and Directory Sync will automatically map sub-organizations on your LDAP directory server to Google Apps Org Units with the same name. Add specific rules to override sub-organization mappings. . If the Do not create or delete Google Organizations...
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.
Add Mapping To add a new search rule, click Add Mapping. Specify the following: Mapping Setting Description (LDAP) DN The Distinguished Name (DN) on your LDAP directory server to map. Example: ou=melbourne,dc=ad,dc=example,dc=com (Google Apps) Name The name of the org unit in Google Apps to map. To add users to the default Organization in Google Apps, enter a single forward slash /.
Org Unit Search Rules This shows a list of rules used when generating the LDAP org units. By default, all org units that match these search rules will be added to the Google Apps org unit hierarchy, and all org units that do not match these search rules will be removed. You can change this behavior with exclusion filters. This page shows the list of search rules. In a new configuration, this will be an empty list. To add a search rule, click Add Search Rule.
Add Org Unit Search Rule To add a new search rule, click Add Search Rule and specify the fields in the dialog box. After specifying the fields, click Apply to submit your changes, or Test LDAP Query to test the search rule. LDAP Org Unit Search Rule Setting Description Org Unit Description Attribute An LDAP attribute that contains the description of each org unit. This field is optional. If left blank, your Org Units will not contain a description when created.
LDAP Org Unit Search Rule Setting Base DN Description The Base DN (Distinguished Name) to use for this search rule. This will override the default Base DN you specified in LDAP Connection. This field is optional. In most cases, you can leave this field blank and use the Base DN specified in the LDAP Connection page. If you want this rule to use a different Base DN than the default, specify an alternate base DN.
Some examples of reasons for LDAP org unit exclusion rules: • OUs for printers, conference rooms, and other non-user resources • Test OUs on your LDAP directory server • OUs that are not participating in a pilot program Note: To exclude individual org units, add a separate rule for each org unit. This page shows the list of exclusion rules. In a new configuration, this will be an empty list. To add an exclusion rule, click Add Exclusion Rule.
Sample Substring Match: Defunct OUs Several organizational units are no longer in use because two nearby offices combined together. The defunct OUs all have “stpaul” in the DN. • Match Type: Substring Match • Rule: stpaul Sample Exact Match: Secure OUs Three specific organizational units are top security and should not be synchronized. Add a separate rule for each special LDAP mailing list.
Rule: ou=internal-test[0-9]*,dc=ad,dc=example,dc=com Add Rule Click Add Exclusion Rule to exclude an org unit in your LDAP server from synchronization. Specify the following: Exclusion Rule Setting Description Exclude Type This Exclude Type is always Org Unit DN. • Match Type Org Unit DN: Base the exclusion rule on the Distinguished Name (DN) of the org unit to exclude. The type of rule to use for the filter. • Exact Match: The org unit DN must match the rule exactly, with the domain name added on.
Exclusion Rule Setting Description Exclusion Rule The match string or regular expression for the exclusion rule. Behavior of this field depends on the Match Type you choose. Addresses that contain this string (or match this regular expression) will not be added to Google Apps, and will be deleted if found. Examples: • Exact Match: ou=test,ou=sales,ou=melbourne,dc=ad,dc=exam ple,dc=com • Substring Match: ou=test • Regular Expression: ou=printer.
User Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP user list. LDAP User Attribute Setting Description Email Address Attribute The LDAP attribute that contains a user’s primary email address. Example: The default is mail. Unique Identifier Attribute An LDAP attribute that contains a unique identifier for every user entity on your LDAP server.
LDAP User Attribute Setting Google Apps Users Deletion / Suspension Policy Don’t suspend or delete Google Apps admins not found in LDAP 78 Release 4.0.2 Description Options for deleting and suspending users. Available options: • Delete only active Google Apps users not found in LDAP (suspended users are retained). Active users in Google Apps will be deleted if they are not in your LDAP, but suspended users are left alone. This is the default setting.
Additional User Attributes LDAP Extended Attributes are optional LDAP attributes that you can use to import additional information about your Google Apps users, including passwords. All attributes are optional. If you do not specify an attribute, Directory Sync will not import this information. LDAP Extended Attribute Setting Given Name Attribute(s) Description An LDAP attribute that contains each user’s given name. (In the English language, this is usually the first name.
LDAP Extended Attribute Setting Family Name Attribute(s) Description An LDAP attribute that contains each user’s family name. (In the English language, this is usually the last name.) This is synchronized with the user’s name in Google Apps. Examples: surname,[cn]-[ou] Synchronize Passwords Indicates which passwords Directory Sync will synchronize. Options are: • Only for new users: When Directory Sync creates a new user, it synchronizes that user’s password. Existing passwords are not synced.
LDAP Extended Attribute Setting Password Attribute Description An LDAP attribute that contains each user’s password. If you set this attribute, your users’ Google Apps passwords will be synchronized to match their LDAP passwords. The password field supports string or binary attributes. Example: CustomPassword1 Password Timestamp Attribute An LDAP attribute that contains a timestamp indicating the last time a user’s password was changed.
LDAP Extended Attribute Setting Password Encryption Method Description The encryption algorithm that the password attribute uses. • SHA1: Passwords in your LDAP directory server hashed using SHA1. • MD5: Passwords in your LDAP directory server hashed using MD5. • Base64: Passwords in your LDAP directory server use Base64 encoding. • Plaintext: Passwords in your LDAP directory server are not encrypted.
LDAP Extended Attribute Setting Description Force new users to change password If checked, new users must change passwords the first time they log in to Google Apps. This allows you to set an initial password, either from an LDAP attribute or by specifying a default password for new users, that must be changed the first time the user logs on to their Google Apps account. Use this option if you are using temporary or one-time passwords.
User Search Rules This shows a list of rules used when generating the LDAP user list. By default, all users that match these search rules will be added to the Google Apps user list and all users that do not match these search rules will be removed. You can change this behavior with exclusion filters. This page shows the list of search rules. In a new configuration, this will be an empty list. To add a search rule, click Add Search Rule.
Add Search Rule To add a new search rule, click Add Search Rule and specify the fields in the dialog box. After specifying the fields, click Apply to submit your changes, or Test LDAP Query to test the search rule.
LDAP User Sync Setting Suspend these users in Google Apps Description Suspend all users that match this LDAP user sync rule. Directory Sync suspends users that already exist in Google Apps. User data is retained. Directory Sync will add new users that do not yet exist in Google Apps. The new users are added as suspended users, and are not active users. Suspended users will not show up in your Global Address List. Use for an LDAP query that returns deleted or suspended users on your LDAP directory server.
LDAP User Sync Setting Rule Description The search rule for user sync to match. This rule is a standard LDAP query, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see “About LDAP Queries” on page 41.
Exclusion rules are based on string values and regular expressions, not LDAP settings. Note: To exclude individual users, add a separate rule for each user. This page shows the list of exclusion filters. In a new configuration, this is an empty list. To add exclusion filters, click Add Exclusion Rule. In the list of Exclusion Filters, you can change existing filters as follows: • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters.
Sample Substring Match: Printers In this example, printers are listed as LDAP users and would match the LDAP query given. However, the printers all have the word “printer” in the name. The rule looks for that substring. • Match Type: Substring Match • Exclude Type: Primary Address • Rule: printer Sample Exact Match: Opt-Out Users Two users have opted out of Google Apps and should not be synchronized. Add a separate rule for each special user.
Add Exclusion Rule Click Add Exclusion Rule to exclude a user or organization in your LDAP server from synchronization, and specify the fields in the dialog box. After specifying the fields, click Apply to submit your changes, or Test LDAP Query to test the search rule. The fields are as follows: Exclusion Rule Setting Description Exclude Type What kind of LDAP data to exclude. • Primary Address: Directory Sync will exclude primary addresses that match this rule.
Exclusion Rule Setting Description Exclusion Rule The match string or regular expression for the exclusion rule. Behavior of this field depends on the Match Type you choose. Addresses that contain this string (or match this regular expression) will not be added to Google Apps, and will be deleted if found. Examples: • Exact Match: maria • Substring Match: internal-list • Regular Expression: internal.*@example.com Groups Set up synchronization for Google Groups for Work in the LDAP Groups page.
Group Search Rules Google Apps Directory Sync can synchronize Google Groups with your LDAP server’s mailing lists. This page shows the list of LDAP Group Sync rules. In a new configuration, this is an empty list. To add mail lists, click Add Search Rule. In the list of Mail List rules, you can change existing filters as follows: 92 Release 4.0.2 • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters.
Add Group Search Rule (LDAP) To synchronize one or more mailing lists as Google Groups, click Add Search Rule and specify the fields in the dialog box. After specifying the fields, click Apply to submit your changes, or Test LDAP Query to test the search rule. The first tab you see is the LDAP tab, which contains information on which LDAP objects to synchronize, and which attributes to use for groups information. To view the groups you have in Google Apps, see the Google Apps control panel.
Specify the following: LDAP Group Rule Setting Description Scope Where to apply the mail list rule. Choose which option to user: • Sub-tree: All objects matched by the search, and anything under those objects, recursively. Subtree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. • One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level.
LDAP Group Rule Setting Description Group Display Name Attribute An LDAP attribute that contains the display name of the group. This will be used in the display to describe the group, and does not need to be a valid email address. Group Description Attribute An LDAP attribute that contains the full-text description of the group. This will become the group description in Google Apps. This field is optional.
LDAP Group Rule Setting Description Member Literal Attribute An attribute that contains the full email address of mailing list members in your LDAP directory server. (Either this field or Member Reference Attribute is required.) Google Apps Directory Server adds each member to the group in Google Apps.
Add Group Search Rule (Prefix-Suffix) You may need Directory Sync to add a prefix or suffix to the value your LDAP server provides for a mailing list’s email address or its members’ email addresses. Specify any prefixes or suffixes here. LDAP Group Rule Setting Description Group Email Address Prefix Text to add at the beginning of a mailing list’s email address when creating the corresponding group email address.
LDAP Group Rule Setting Description Member Name Prefix Text to add at the beginning of each mailing list member’s email address when creating the corresponding group member email address. Member Name Suffix Text to add at the end of each mailing list member’s email address when creating the corresponding group member email address. Owner Name Prefix Text to add at the beginning of each mailing list owner’s email address when creating the corresponding group owner email address.
Exclusion rules are based on string values and regular expressions, not LDAP settings. This page shows the list of exclusion rules. In a new configuration, this will be an empty list. To add exclusion rules, click the Add Exclusion Rule button at the bottom of the screen. In the list of exclusion rules, you can change existing filters as follows: • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters.
Sample Substring Match: Defunct Mailing Lists Several mailing lists are no longer in use because two nearby offices combined together. The defunct lists all have “stpaul” in the address. • Match Type: Substring Match • Rule: stpaul Sample Exact Match: Secure Mailing Lists Three small-distribution LDAP mailing lists are top security and should not be imported. Add a separate rule for each special LDAP mailing list.
Add Group Exclusion Rule Click Add Exclusion Rule to prevent an address from being treated as a mailing list, and specify the following: Exclusion Rule Setting Description Exclude Type Sets the type of exclusion filter to create: Match Type Exclusion Rule • Group Name: Do not sync any group that has a name that matches the rule. • Group Address: Do not sync any group that has an email address that matches the rule.
User Profile Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP user profiles. 102 Release 4.0.
The fields are as follows. LDAP Profile User Attribute Description Primary email LDAP attribute that contains a user’s primary mail address. This is usually the same as the primary mail address listed in the previous LDAP Users section. Example: mail Job title LDAP attribute that contains a user’s job title. Company name LDAP attribute that contains a user’s company name. Assistant’s DN LDAP attribute that contains the LDAP Distinguished Name (DN) of the user’s assistant.
LDAP Profile User Attribute Description State/Province LDAP attribute that contains the state or province of a user’s primary work address. ZIP/Postal Code LDAP attribute that contains the ZIP code or Postal Code of a user’s primary work address. Country/Region LDAP attribute that contains the country or region of a user’s primary work address. User Profile Search Rules This shows a list of rules used when determining which user profiles to import.
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.
LDAP User Profile Search Rule Field Rule Description The search rule for user profile sync to match. This rule is a standard LDAP query, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see “About LDAP Queries” on page 41.
User Profile Exclusion Rules If you have any existing user profile information in Google Apps that you do not want to synchronize, specify it here. This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click Add Exclusion Rule. In the list of Exclusion Filters, you can change existing filters as follows: • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters.
Sample Exact Match: Opt-Out Users Two users have opted out of Google Apps and should not be synchronized. Add a separate rule for each special user. First rule: • Match Type: Exact Match • Rule: atif@example.com Second rule: • Match Type: Exact Match • Rule: svetlana@example.com Sample Regular Expression Match: Test Users About five hundred test users are listed in LDAP, but they are only used for internal load testing.
Specify the following: Exclusion Rule Setting Description Match Type The type of rule to use for the filter. • Exact Match: The address must match the rule exactly. Example: maria@example.com would exclude only the user maria@example.com. • Substring Match: The address or organization name must contain the text of the rule as a substring. Example: “test” would exclude testadmin@example.com and salestest1@example.com.
You can see Shared Contacts in Google Apps by going to your Inbox and clicking the Contacts link. The Shared Contacts section configures how Google Apps Directory Sync generates shared contacts information from your LDAP directory server. You may need to collect information from your LDAP directory server before you can enter details in this section. How to use Shared Contacts Shared Contacts information is similar to a Global Address List in a directory server.
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.
The fields are as follows. LDAP Shared Contact Attribute Description Sync key An LDAP attribute that contains a unique identifier for the contact. Choose an attribute present for all your contacts that is not likely to change, and which is unique for each contact. This field becomes the ID of the contact. Examples: dn or contactReferenceNumber Full name The LDAP attribute or attributes that contain the contact’s full name. Example: [prefix] - [givenName] [sn] [suffix] 112 Release 4.0.
LDAP Shared Contact Attribute Description Mobile phone numbers LDAP attribute that contains a contact’s personal mobile phone number. Work mobile phone numbers LDAP attribute that contains a contact’s work mobile phone number. Assistant’s Number LDAP attribute that contains a work phone number for a contact’s assistant. Street Address LDAP attribute that contains the street address portion of a contact’s primary work address. P.O. Box LDAP attribute that contains the P.O.
By default, shared contacts are synchronized for all contacts that match these search rules will be added to the Google Apps user list, and removed for shared contacts that do not match these rules. You can change this behavior with exclusion filters. This page shows the list of search rules. In a new configuration, this is an empty list. To add a search rule, click Add Search Rule. Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP directory.
LDAP Shared Contacts Search Rule Field Scope Description This determines where in the LDAP directory this rule applies. Choose which option to use: • Sub-tree: All objects matched by the search, and anything under those objects, recursively. Sub-tree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. • One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level.
LDAP Shared Contacts Search Rule Field Base DN Description The Base DN (Distinguished Name) to use for this search rule. This will override the default Base DN you specified in LDAP Connection. This field is optional. In most cases, you can leave this field blank and use the Base DN specified in the LDAP Connection page. If you want this rule to use a different Base DN than the default, specify an alternate base DN.
This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click Add Exclusion Rule. In the list of Exclusion Filters, you can change existing filters as follows: • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters. • Edit: Click the notepad icon to edit the settings of an exclusion filter. • Delete: Click the X icon to delete the exclusion filter.
Add Exclusion Rule Click Add Exclusion Rule to exclude a shared contact in your LDAP server from synchronization. Specify the following: Exclusion Rule Setting Description Match Type The type of rule to use for the filter. • Exact Match: The address must match the rule exactly. Example: 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.
Exclusion Rule Setting Description Rule The match string or regular expression for the exclusion rule. Behavior of this field depends on the Match Type you choose. Addresses that contain this string (or match this regular expression) will not be added to Google Apps, and will be deleted if found. Examples: • Exact Match: maria@example.com • Substring Match: listinternal • Regular Expression: internal.*@example.
Calendar Resource Attributes Specify the attributes you want Google Apps Directory Sync to use when generating the LDAP calendar resources list. LDAP User Attribute Setting Resource Id Description The LDAP attribute or attributes that contain the ID of the calendar resource. This is a field managed on your LDAP system, which may be a custom attribute. This field must be unique.
LDAP User Attribute Setting Export Calendar resource mapping (optional) Description Generates a CSV file listing LDAP calendar resources and their Google Apps equivalents. Use the CSV file with Google Apps Migration for Microsoft Exchange to migrate the contents of your Microsoft Exchange calendar resources to the appropriate Google Apps calendar resources. Note: Calendar resource attributes use a different syntax than other Directory Sync attributes.
By default, all calendar resources that match these search rules will be added to the Google Apps calendar resources, and all calendar resources that do not match these search rules will be removed. You can change this behavior with exclusion filters. This page shows the list of search rules. In a new configuration, this will be an empty list. To add a search rule, click Add Search Rule.
LDAP User Sync Setting Rule Description The search rule for calendar resources sync to match. This rule is a standard LDAP query, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see “About LDAP Queries” on page 41.
Exclusion rules are based on string values and regular expressions, not LDAP settings. Note: To exclude individual calendar resources, add a separate rule for each user. This page shows the list of exclusion filters. In a new configuration, this will be an empty list. To add exclusion filters, click Add Exclusion Rule. In the list of Exclusion Filters, you can change existing filters as follows: • Reorganize: Click the up arrow or down arrow icon to change the order of exclusion filters.
Sample Substring Match: Printers In this example, printers are listed as LDAP resources and would match the LDAP query given. However, the printers all have the word “printer” in the name. The rule looks for that substring. • Match Type: Substring Match • Exclude Type: Calendar Resource Id • Rule: printer Sample Exact Match: Opt-Out Users Two conference rooms have been converted into offices and should not be imported as Google Apps calendar resources. Add a separate rule for each special user.
Add Exclusion Rule Click the Add Exclusion Rule at the bottom of the page to exclude a user or organization in your LDAP server from synchronization. Specify the following: Exclusion Rule Setting Description Exclude Type What kind of LDAP data to exclude. • Calendar Resource Id: Directory Sync will exclude calendar resources where the Calendar Resource Id attribute specified in LDAP Calendar Resources Attributes matches this pattern. The interface displays this choice as CALENDAR_RESOURCE_ID.
Exclusion Rule Setting Description Match Type The type of rule to use for the filter. • Exact Match: The address must match the rule exactly, with the domain name added on. Note: In many cases, Substring Match yields better results than Exact Match. Example: maria (if you are using the domain example.com) would exclude only the user maria@example.com. • Substring Match: The address or organization name must contain the text of the rule as a substring. Example: “test” would exclude testadmin@example.
Consider adding a notification to send mail to your own address, and possibly the addresses of any concerned parties in your company. Specify the following: Notifications Setting Description SMTP Relay Host The SMTP mail server to use for notifications. Directory Sync uses this mail server as a relay host. Example: 127.0.0.1 to run the mail server on the same machine. Example: smtp.gmail.com Use SMTP with TLS Check this box to use SMTP with TLS.
Notifications Setting Description From address Enter the “From:” address for the notification mail. Recipients will see this address as the notification sender. For instance, you might use your own email address. Example: admin@solarmora.com To addresses (recipients) Notifications will be sent to all addresses on this list. Enter any valid email address on any domain. Enter each recipient email address individually, then click the Add button.
Logging Settings You can specify the file name and level of detail of logging for Google Apps Directory Sync. Specify the following: Logging Setting Description File name Enter the directory and file name to use for the log file or click Browse to browse your file system. Example: sync.log Log Level The level of detail of the log. Options are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. The level of detail is cumulative: each level includes all the details of previous levels.
Logging Setting Description Maximum Log Size The maximum size of the log file, in gigabytes. When this file reaches half capacity, it is saved as a backup file (which overwrites any existing backup file) and a new file is created. At any time, the total size of these two files (the log file and the backup log file) will not exceed the total maximum size. Example: 4 Sync After you enter configuration information, use this section to verify and test your GADS settings.
Validation Results When you first go to this page, you will see Validation Results. This page will show a checklist of all the Configuration Manager sections. If you are missing required information, you will see error messages showing what needs to be added. Important: This checklist confirms only the minimum needed for synchronization. You may need to configure additional filters or rules to be sure the results are what you expect.
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.
Release 4.0.
Chapter 7 Synchronization Chapter 7 About Synchronization Run the synchronization command to push your LDAP directory server user information to Google Apps. Before you can synchronize Google Apps with your LDAP directory server, you must create rules that detail how to connect to both servers, and what filters and rules to use. These rules are stored in an XML file. To create this XML file, run Configuration Manager. For more information about Configuration Manager, see “Configuration” on page 49.
sync-cmd Run without any arguments, this command gives an error and directs you to run sync-cmd -h for help. To synchronize, use the following command line to read a configuration file, check to be sure that a sync is not already running, connect to both servers, generate a list of changes, and apply those changes: sync-cmd -a -o -c [filename] Replace [filename] with the name of the XML file you created in the Configuration Manager.
Option Values -g, --groups Do not analyze groups. Use this option if you want to synchronize users, but not groups. -h,--help View this information and exit. -l,--loglevel [level] Override the default and/or configured log level with the specified value. Valid values (in increasing order of verbosity) are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. In most cases, the recommended log level is INFO. -s, --sharedcontacts Do not analyze shared contacts. Note: Do not use this option.
To schedule a task 1. In Control Panel, open Scheduled Tasks. 2. Double-click Add Scheduled Task. 3. Complete the Scheduled Task wizard using the following information. (Steps may vary depending on your version of Microsoft Windows.) • Choose the program sync-cmd.exe, located where Directory Sync is installed. • The frequency of the task depends on your synchronization needs.
Monitoring After you have set up scheduled synchronization, make a policy of regularly checking the status of your synchronizations. Check Notification messages on a regular basis for signs of any problems. Notifications will be sent to an address that you specify. For more information about Notifications, see “Notifications” on page 127. When looking through notifications logs, look for messages that indicate that users were synchronized.
Release 4.0.
Chapter 8 Release 4.0.2 Troubleshooting Chapter 8 About Troubleshooting This chapter covers information about how to troubleshoot problems that may occur with Google Apps Directory Sync (GADS). Troubleshooting information includes information about common issues, system tests and researching issues. For information about LDAP queries, see “About LDAP Queries” on page 41.
What port numbers should be used in GADS when connecting to Global Catalog server? By default, GADS connects to an LDAP server with the standard LDAP port 389 to query users from a single domain/LDAP server. If you need to query users over multiple domains/LDAP servers that have trust relationship, configure GADS to connect to a Global Catalog server with the standard Global Catalog server port 3268.
A group rule or exclusion rule doesn’t seem to be doing anything. Check the scope of the rule. You may need to set the scope to SUBTREE. A group rule generates errors. Check the Group Search Attribute in LDAP Configuration. This is the field that contains the email address of a group. In most cases, this will be mail. How can I exclude a specific LDAP organization? You cannot create an LDAP rule to exclude users in a specific LDAP organization.
The proxy environment requires a password challenge for external web access. GADS can use a proxy server but cannot respond to password challenges. To run synchronization, you will need to change your network setup to allow Directory Sync to connect without a password challenge, or without a proxy server. I cannot simulate a synchronization because the notifications server is not specified. To run a simulated synchronization, you will need a server capable of sending mail.
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.
Release 4.0.
