Google Apps Directory Sync for Postini Services Administration Guide Release 1.3.
Google, Inc. 1600 Amphitheatre Parkway Mountain View, CA 94043 www.google.com Part number: DSS_1.3.35_15 February 3, 2012 © Copyright 2009 Google, Inc. All rights reserved. Google, the Google logo, Google Message Filtering, Google Message Security, Google Message Discovery, Postini, the Postini logo, Postini Perimeter Manager, Postini Threat Identification Network (PTIN), Postini Industry Heuristics, and PREEMPT are trademarks, registered trademarks, or service marks of Google, Inc.
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”.
Contents About This Guide 7 What This Guide Contains 7 Related Documentation 7 How to Send Comments About This Guide 8 Chapter 2: Introduction 9 About Google Apps Directory Sync 9 Features and Benefits 9 Comparison with Directory Sync Hosted Edition Architecture 11 Utility Overview 13 Chapter 3: Preparation 15 About Preparation 15 Overview 15 Checklist: Before You Begin 16 Useful LDAP Tools 17 Softerra LDAP Administrator 18 JXplorer 18 LDAP Queries 18 Syntax 18 Common LDAP Queries 19 Planning for Large o
Message Security Service Orgs 33 Exclusion Filters for Service Settings 34 Sample Message Security Exclusion Rules LDAP Settings 39 LDAP Connection 40 LDAP Users 42 LDAP User Attributes 43 LDAP User Sync 46 LDAP User Exclusion Rules 50 Sample LDAP User Exclusion Rules 53 LDAP Mailing List Overview 54 LDAP Mailing List Sync 56 LDAP Mailing List Exclusion Rules 59 Sample LDAP User Exclusion Rules 60 Notifications 61 Delete Limits 63 Log Files 65 Simulate Sync 66 Simulate Sync 66 Chapter 6: Synchronization 69
About This Guide What This Guide Contains The Google Apps Directory Sync Administration Guide provides information about: • Google Apps Directory Sync features. • Basic steps for installing the directory sync utility on your mail server. • Configuration for the directory sync utility. • Synchronizing users. • Troubleshooting the directory sync utility. This guide is intended for mail server administrators who are already familiar with mail server configuration and the message security service.
Document Description Directory Sync Configuration Guide Instructions for setting up your network environment and directory server for Directory Sync Hosted Edition. Directory Sync Hosted Edition is a different feature, that runs on the message security service and requires special configuration on your network to use. How to Send Comments About This Guide Google values your feedback. If you have comments about this guide, please send an email message to: postini-doc_comments@google.
Chapter 2 Introduction Chapter 2 About Google Apps Directory Sync Google Apps Directory Sync is a utility that adds, deletes, and moves your users in the message security service to match the user directory on your LDAP server. When you synchronize, any changes on your LDAP server are reflected in the message security service. The directory sync utility runs on a server machine in your network environment.
Comparison with Directory Sync Hosted Edition Google Apps Directory Sync is a separate utility run on your server, and is different from the Directory Sync Hosted Edition feature found in the Administration Console. Because of the functional advantages and ease of use, Google Apps Directory Sync is recommended over Directory Sync Hosted Edition for most administrators.
Architecture Google Apps Directory Sync runs on your server and updates the message security service to match your LDAP server. The directory sync utility never updates or changes your LDAP server. The following steps describe how the data flow of directory sync works. 1. The directory sync utility connects to your LDAP server (via port 389 or another port you specify) and generates a list of users on your directory. You can set up rules to specify how this user list is generated. 2.
3. The directory sync utility compares the two lists, and generates a list of changes. 4. The directory sync utility then updates the message security service to match your LDAP server settings. 12 Release 1.3.
Utility Overview The directory sync utility includes several components, designed to work together. These components are: • Configuration Manager - Use this graphical UI to configure how the directory sync utility will connect to the message security service and to your LDAP server. You can also create rules for user lists, search queries, organization mapping, aliases, distribution lists and exceptions. For more information, see “Configuration” on page 27.
Chapter 3 Preparation Chapter 3 About Preparation Successful deployment of Google Apps Directory Sync requires planning. Many steps in the configuration and synchronization process assume you already have key information about your LDAP directory server, mail server, and message security service organization structure.
Checklist: Before You Begin Before you configure synchronization, gather the information you need from the message security service, as well as your own LDAP server and mail server. Use this checklist to be sure you have the information you need: • Message Security Org Structure • Message Security Administrator • LDAP Structure Information • LDAP Base DN • LDAP Administrator • LDAP Queries • Org Mapping • Mail Server Each item on the checklist is detailed below.
LDAP Structure Information: Gather information about your LDAP directory server. You will need to know what OUs contain users you want to sync and which LDAP attributes contain important information. To collect this information, use an LDAP browser. For more information, see “Useful LDAP Tools” on page 17. LDAP Base DN: The directory sync utility will use this Base DN as the top level for all LDAP queries. You can use an LDAP browser to collect this information.
Note that these are third-party browsers, and this document does not include instructions or support on the use of an LDAP browser. Softerra LDAP Administrator To download Softerra LDAP Administrator, go to: http://www.ldapbrowser.com JXplorer To download the JXplorer Java Ldap Browser, go to: http://www.jxplorer.org LDAP Queries The directory sync utility uses the LDAP query language to gather information from your directory server.
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=
Synchronizing for a very large or complex organization may require special consideration. This may be the case for two reasons: • A complex deployment may include many different sub-groups which need to be synchronized using separate rules or message security service organizations. • A large deployment may be system-intensive and may require special work to be sure it runs quickly. A common way to handle a large deployment is to create multiple configuration files for different parts of your company.
Chapter 4 Installation Chapter 4 About Installation To run Google Apps Directory Sync, install the directory sync utility on your server. The directory sync utility is designed to run on Windows, Linux or Solaris machines. The installer is an executable program that installs all needed components on the server, including managing libraries, classpath variables, and other components. The installer also uninstalls any existing version of the directory sync utility in the same directory.
System Requirements Using Google Apps Directory Sync requires the following: • A server on which to install Google Apps Directory Sync, running Microsoft Windows (tested on XP and Vista), Linux or Solaris (version 8+, no support for x86). • Sufficient disk space on the server. You should have at least 5G 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. • Sufficient memory on the server.
3. Download and run the installer. 4. When you have completed all the steps of the installer, the directory sync utility has been installed. The installer contains all needed components and can be run offline without any outside connection. Upgrade Google Apps Directory Sync In Release 1.3.13 or later, Google Apps Directory Sync automatically checks to see if there are any updates available. If updates are available, you will be prompted to upgrade when you start Configuration Manager.
You can also update manually. The latest version of the directory sync utility is always accessible on the Google Apps Directory Sync website. To upgrade to the latest version, go to this site, and download and run the directory sync utility. Configuration files are backward-compatible. Future versions of the directory sync utility cans run configuration files created in earlier versions. The installer wizard automatically detects and uninstalls previous versions of the software in the same directory.
Chapter 5 Configuration Chapter 5 About Configuration Configuration Manager is a step-by-step graphical user interface that walks you through creating and testing an XML configuration file for Google Apps Directory Sync. Note: Before you use Configuration Manager, collect information about your LDAP directory server and your message security service organizations. For more information, see “Checklist: Before You Begin” on page 16.
The directory sync utility includes several ways to customize search rules and filters. When collecting information from your LDAP server, you can define LDAP queries to extract information. The directory sync utility supports RFC 2254, the international standard on LDAP Filters. For the details, see RFC 2254: http://www.ietf.org/rfc/rfc2254.txt The directory sync utility also includes some non-LDAP filters. In these, you can use regular expressions to filter for patterns of text.
Message Security Service Settings The Message Security Settings section governs how the directory sync utility connects to the message security service, and how the directory sync utility generates your message security service user list for comparison. Before you enter information in the Message Security Service Settings pages, collect the information from the message security service. You may need to create new organizations or administrators in the message security service.
Message Security Service Authentication Enter your message security service login and connection information in this section. Specify the following: Authentication Setting Description Admin Email The email address used to log into the Administration Console. This address should be a valid user on the Administration Console with administrative privileges over the user organizations you want to synchronize.
Authentication Setting Description Immediately send a welcome message to new users Typically, the message security service sends welcome notifications to new users within 24 hours, but not immediately. This is to prevent a flood of welcome that may overload your mail server. If you want to send all the notifications immediately, check the box labelled “Immediately send a welcome message to new users.
Authentication Setting Description HTTP Proxy Host Name If you use a different proxy server for HTML connections than SSL connections, enter the HTTP proxy host here. (if needed) Directory Sync always connects to the message security service on SSL. The only time the directory sync utility sends traffic by unencrypted HTTP is to validate a certificate with the issuing authority. If you do not use a proxy server, or you use the same proxy server for HTML and SSL connections, leave this field blank.
Test Connection Once you have configured Server settings, click Test Connection. Configuration Manager will connect to the message security service and attempt to log in. If the test fails, verify your admin email and password, and confirm that you are able to connect to the Internet from the machine. Message Security Service Orgs On this page, specify which orgs in the message security service to synchronize.
Any existing user in the specified orgs will be deleted if they are not in the user list generated from your LDAP server. Any users not in these orgs will be added (or moved from another org) if they are in the user list generated from your LDAP server. After synchronization, your users in the message security service will be the same as your users on your LDAP server. You make exceptions to this behavior by using exclusion filters.
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 contain two filters for default users. To add new exclusion filters, click the Add Exclusion Filter button at the bottom of the screen. On 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.
Add Exclusion Filter Click Add Exclusion Filter at the bottom of the page to exclude a user or organization from synchronization. Specify the following: 36 Exclusion Rule Setting Description Type Sets what type of exclusion filter to create, Primary Address or Postini Org. Release 1.3.32, October 2009 • Primary Address: Check the user’s primary address and exclude any users that match.
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. User Example: For a user, user1@mixateria.com would exclude that single user. Org Example: For an org, “Mixateria Florida Sales” would exclude all users in that single org. • Substring Match: The address or organization name must contain the text of the rule as a substring.
Default Users If your search includes your pdefault users, the directory sync utility will try to delete these users unless they are in your LDAP server. Therefore, every new configuration file includes the following two exclusion filters when created.
Alternate Offices The company has two other offices with separate LDAP servers. The three offices have intermingled org structures, but all orgs in the other two offices are labeled as “Dubai” or “London” in the org name in the Administration Console.
LDAP Connection Specify your LDAP connection and authentication in this page. LDAP Connection Setting Description Connection Type Choose whether to use an encrypted connection. If your LDAP server supports an SSL connection and you wish to use it, choose LDAP + SSL. Otherwise, choose Standard LDAP. Example: Standard Host Name Enter the domain name or IP address of your LDAP directory server. Example: ad.mixateria.com, or 10.22.1.1. Port Specify the host port. The default is 389.
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 to use when connecting to the server. This user should have read and execute permissions for the whole subtree. If needed, include the domain for the user as well.
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. Note: 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 the message security service. 42 Release 1.3.
LDAP User Attributes Specify what attributes Google Apps Directory Sync will use when generating the LDAP user list. LDAP User Attribute Setting Server Type Description The type of LDAP server that you are using with the directory sync utility. If you are using a Lotus Domino, Microsoft Active Directory, or Open LDAP directory server, select that server type. Otherwise, select Other.
LDAP User Attribute Setting Non-Address Primary Key Attribute (Optional) Description An LDAP attribute with a unique key other than an email address. This field is optional. If a user’s email address on your LDAP server changes (for instance, because of a name change), Google Apps Directory Sync will rename the user in the message security service without losing any quarantined mail or user settings. You can use a binary or string attribute for the nonaddress primary key.
LDAP User Attribute Setting Domino Alias Address Attribute (if needed) Description Only for Lotus Domino servers. One or more attributes used to hold internal Domino alias attributes, which are stored as usernames without domain information. These addresses will be formatted as email addresses and placed as aliases to the primary address listed in the Email Address Attribute field.
LDAP User Sync This shows a list of rules used when generating the LDAP user list. By default, all users that match these search rules will be added to the message security service user list (or moved if they are in a different organization) 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.
Add Search Rule To add a new search rule, click Add Search Rule. Specify the following: LDAP User Sync Setting Org Name Description Select Org Name or Org name defined by this LDAP attribute and enter an appropriate value. Configure where to put users in your message security service org hierarchy. The directory sync utility adds all users that match this rule into the specified org in the message security service.
LDAP User Sync Setting Org name defined by this LDAP attribute Description Select Org Name or Org name defined by this LDAP attribute and enter an appropriate value. For each user, the directory sync utility reads the value an LDAP attribute you specify, and adds the user to the message security service organization specified in this LDAP attribute. Collect this information from the message security service and your LDAP server. For more information, see “Checklist: Before You Begin” on page 16.
LDAP User Sync Setting Scope Description This determines where in the LDAP directory this rule applies. This could be an entire subtree, one level, or a single object. • Subtree: All objects matched by the search, and anything under those objects. (recursive) • One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. • Object: Only objects directly matched by the search. No recursion of any kind.
LDAP User Sync Setting Rule Description This is the search rule used. This rule uses standard LDAP filtering language, and allows sophisticated logic and complex rules for searching. For more information about LDAP search filters, see “LDAP Queries” on page 18. Example 1: To match all objects (this may cause load problems): objectclass=*.
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.
Add Exclusion Filter Click the Add Exclusion Filter at the bottom of the page to exclude a user or organization in your LDAP server from synchronization. Specify the following: Exclusion Rule Setting Description Match Type The type of rule to use for the filter. • Exact Match: The address must match the rule exactly. Example: maria@mixateria.com would exclude only the user maria@mixateria.com. • Substring Match: The address or organization name must contain the text of the rule as a substring.
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. • Alias Address: Directory Sync will exclude aliases that match this rule. 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.
First rule: • Match Type: Exact Match • Exclude Type: Primary Address • Rule: atif@mixateria.com Second rule: • Match Type: Exact Match • Exclude Type: Primary Address • Rule: svetlana@mixateria.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. All the test users follow the same name pattern: internaltestX, where X is a number, and all test users are in the same domain.
Mailing lists are often handled separately, because if a mailing list is added as a user, all recipients of the mailing list will receive notifications. This can cause confusion. To avoid this problem, Google Apps Directory Sync can import mailing lists as aliases to a user you specify. This section is optional. Fill out the information in this section if you wish to import mailing lists as aliases to a central user in the message security service.
LDAP Mailing List Sync Mailing lists are a special kind of email address that direct mail to many addresses at once. Most administrators prefer to create mailing lists as aliases to a separate user in the message security service, to avoid administrative notifications and quarantine summaries going out to all the members of a mailing list. This page shows the list of LDAP mail list rules. In a new configuration, this will be an empty list.
Add Mail List Click the Add Mail List at the bottom of the page to synchronize one or more addresses as mailing lists. Specify the following: Mailing List Setting Description Mail list owner The email address of the user who will manage the mailing list. If this user is not a user in the message security service, the directory sync utility will add this user in the specified Mail list owner org. The mailing list owner address is case sensitive.
Mailing List Setting Description Scope Where to apply the mail list rule. This could be a whole subtree, a single level, or a single object. • Subtree: All objects matched by the search, and anything under those objects. (recursive) • One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. • Object: Only objects directly matched by the search. No recursion of any kind.
LDAP Mailing List Exclusion Rules You can exclude particular addresses from being treated as mailing lists. If you have any entries in your directory server that match a mail list rule, but should not be treated as a mailing list, list them here. This might include: • Internal mailing lists that do not have outside email addresses • Printers, conference rooms, and other non-user resources • Mailing lists that should be treated as individual users, with separate archives and quarantines.
Add Exclusion Filter Click Add Exclusion Filter at the bottom of the page to prevent an address from being treated as a mailing list. Specify the following: Exclusion Rule Setting Description Match Type The type of rule to use for the filter. Rule • Exact Match: The address or organization name must match the rule exactly. • Substring Match: The address or organization name must contain the text of the rule as a substring.
Sample Substring Match: Internal Mailing Lists Several mailing lists are devoted to internal use only. Those lists all have “internal” in the address. • Match Type: Substring Match • Rule: internal Sample Exact Match: Secure Mailing Lists Three small-distribution mailing lists are top security and should not be archived with other mailing lists. Add a separate rule for each special mailing list. First rule: • Match Type: Exact Match • Rule: finance-early-statements@mixateria.
Consider adding a notification to send mail to your own address, and possibly the addresses of any concerned parties in your company. Note: Notifications do not support TLS. Specify the following: Notifications Setting Description Send notifications 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: dirsync@mixateria.
Notifications Setting Description SMTP Relay Host The SMTP mail server to use for notifications. The directory sync utility uses this mail server as a relay host. Example: 172.0.0.1 to run the mail server on the same machine. Example: mail.mixateria.com Username If the SMTP server you specify requires SMTP authentication, enter the user name to use here. (if needed) Example: admin5 Password If the SMTP server you specify requires SMTP authentication, enter the Password to use here.
The directory sync utility checks to be sure that synchronization will not delete too many users. If the synchronization would delete more users than the delete limits allow, the entire synchronization fails and no users are added, moved or deleted. This will be noted in the notifications email. Note: Delete limits apply during synchronization, but not during simulation. Simulation results will not include delete limits.
Log Files You can specify the file name and level of detail of logging for Google Apps Directory Sync. Specify the following: Logging Setting Description File name Enter the directory and file name to use for the log file or click Browse to browse your file system. Example: sync.log Log Detail 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 Simulate Sync After you enter configuration information, use this section to verify and test your Google Apps Directory Sync settings.
Once you’ve completed all required fields, you will be able to use the Simulate Sync button to simulate a synchronization. Once you’re ready, click Simulate Sync. You will see the Simulate Sync page. During simulation, Configuration Manager will: • Connect to the message security service and generate a registered user list. • Connect to your LDAP server and generate an LDAP user list. • Generate a list of differences. • Log all events.
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 73. If the synchronization was successful, check the Proposed Change Report and review it for unexpected results. Note: The Proposed Change Report doesn’t check your delete limits.
Chapter 6 Synchronization Chapter 6 About Synchronization Run the synchronization command to push your LDAP directory server user information to the message security service. The directory sync utility uses the command sync-cmd to run synchronization. This simple command line interface gives you the flexibility to incorporate synchronization into any scheduling or batch script you wish to use.
Replace [filename] with the name of the XML file you created in the Configuration Manager. Synchronization options The table below describes the possible arguments to the sync-cmd command. You can also see this information by running the following: sync-cmd -h in the directory where the directory sync utility is installed. Option Values -r,--report-out Write reports to the specified output file, in addition to writing them to the log. -a,--apply Apply detected changes.
Option Values -u, --users Do not analyze users. Note: If you use this option, Google Apps Directory Sync will not add, move or delete users. -v Display short application version information. Scheduling Synchronization Once you have successfully run a manual synchronization, you can set up automatic synchronization. Use existing third-party scheduling software to automate synchronization. In most cases, scheduling twice a week is recommended.
3. Complete the Scheduled Task wizard using the following information. (Steps may vary depending on your version of Microsoft Windows.) • Choose the program sync-cmd.exe, located where the directory sync utility is installed. • The frequency of the task depends on your synchronization needs. For most environments, twice per week is appropriate. • Use Advanced Properties to specify an exact command line.
Chapter 7 Troubleshooting Chapter 7 About Troubleshooting This chapter covers information about how to troubleshoot problems that may occur with Google Apps Directory Sync. Troubleshooting information includes information about common issues, system tests and researching issues. For information about LDAP queries, see “LDAP Queries” on page 18. Common Issues The following describes common issues and questions related to Google Apps Directory Sync.
The proxy environment requires a password challenge for external web access. The directory sync utility can use a proxy server but cannot respond to password challenges. To run synchronization, you will need to change your network setup to allow the directory sync utility to connect without a password challenge, or without a proxy server. The base DN information doesn’t seem to be correct. Check to be sure your base DN doesn’t include any spaces.
Is there a way to change the Non-Address Primary Key Attribute for users manually once the directory sync utility has synced users in the message security service? Yes. The purpose of this field is to store something stable and unique from LDAP directory and then use that to compare users later.
2. Under Message Security Service Authentication, click Test Connection to confirm you can connect to the message security service. 3. Under LDAP Connections, click Test Connection to confirm you can connect to your LDAP server. 4. Under Notifications, click Test Notification to confirm you can send a test notification. 5. Under Simulate Sync, confirm you have filled out all required fields. 6. Under Simulate Sync, click Simulate Sync to confirm that synchronization is running properly.
