Address Synchronization Tool Administrator Guide

Transcription

1 Address Synchronization Tool Administrator Guide This guide is for systems administrators configuring the Address Synchronization Tool to update the information used by MessageLabs in the provision of its and Web Security Services. Service Version 1.3 Guide Version

2 Table of Contents 1 About the guide Audience and scope International considerations Conventions 1 2 Introduction Overview Features 3 3 Preparation Downloading the tool Obtaining a license key 5 4 Quick start Prerequisites Installation First time settings Creating a new configuration Preparing to synchronize to MessageLabs 11 5 Performing the synchronization 20 6 Address Synchronization Tool in detail Address Synchronization Tool settings The configuration wizard The main window Logging 38 7 Command line operation 40 8 Automatic operation 41 Appendix A Standard RegEx strings 42 Appendix B LDAP filters 44 Appendix C With or without JRE? 45 Further information 46

3 1 About the guide 1.1 Audience and scope This guide is for systems administrators configuring the Address Synchronization Tool to update the information used by MessageLabs in the provision of its and Web Security Services. The Address Synchronization Tool automates the process of updating your Registered Addresses. This tool can operate alongside ClientNet, which enables the manual upload and management of your Registered Addresses. 1.2 International considerations Due to local legislation, some features described in this document are not available in some countries. 1.3 Conventions In this guide, the following conventions are used: Formatting Denotes Bold Bold Italic Note: Text to type in Button, tab or field Window title or description Notes containing extra information that may be useful Text to type in Output from a computer Output from a computer Link A link to a website Screenshots normally display an Internet Explorer window. If only part of the window is shown, the side where it is trimmed may be shown with a wavy or dashed line. Areas of the screenshot may be highlighted in red. When a section of the guide is only relevant to a restricted set of Operating System platforms the text will appear in a box with one or more logos indicating the platform or platforms: Linux Microsoft Windows Sun Solaris Note: The use of the tool on Solaris is not currently supported by MessageLabs, nor is there a version of the tool available for download currently. However, there are comments in this guide concerning the use of the tool on Solaris. If you have a requirement to use the tool on Solaris, please contact MessageLabs, so that we can advise you when an appropriate version of the tool is available. Page 1

4 2 Introduction MessageLabs provides the Address Synchronization Tool (also known as Schemus both terms are used in this guide) to assist you in supplying and maintaining data required by the and Web Security Services. For Services the tool synchronizes the update of Registered Addresses. For Web Security Services the tool synchronizes the update of information on Users and Groups Group Synchronization. The Address Synchronization Tool extracts addresses from a variety of directory sources and synchronizes these with the MessageLabs and Web Security Services. Using the synchronization tool ensures that information from a variety of sources is synchronized with the MessageLabs system. The extent of the Address Synchronization Tool s capabilities is defined by one or more license keys, provided by MessageLabs, and may allow a combination of the following processes: To synchronize addresses (referred to as Mail Synchronization ) To synchronize group identities (referred to as Group Synchronization ) To synchronize user s identities, their addresses, and their group memberships (referred to as User Synchronization ) The Address Synchronization Tool guides you through the process of configuring the data to extract from your directory system. Once correctly configured, the synchronization process can either be run from the Address Synchronization Tool interface or from the command line. The process can be scheduled to operate automatically. The Address Synchronization Tool can also send notifications reporting its outcome at each invocation. Address Registration MessageLabs provides a means by which Services clients can protect themselves from dictionary-type spam attacks, by registering their valid addresses in order to allow MessageLabs to reject any destined for invalid addresses. The Address Synchronization Tool assists clients with the task of maintaining the registration of their valid addresses. The tool synchronizes the update of Registered Addresses in order to allow this task to be automated and, for example, integrated with staff leaver and joiner procedures. This tool may operate alongside the ClientNet portal interface that facilitates the manual upload and manipulation of the Registered Address data. The synchronization of Registered Addresses is accomplished using: A secure HTTP-based interface to the MessageLabs synchronization service; The Address Synchronization Tool provided to extract address data from your directory data sources and export this data via the synchronization service. Group Synchronization MessageLabs provides a means by which Web Security Services clients can utilize their existing directory definitions of user groups within web security policy rules. The Address Synchronization Tool assists clients by synchronizing the update of Groups and Users in order to allow this task to be automated and, for example, integrated with staff leaver and joiner procedures. This tool operates alongside the ClientNet portal interface that facilitates the manual upload and manipulation of Custom Groups. The synchronization of Group information is accomplished using: A secure HTTP-based interface to the MessageLabs synchronization service; The Address Synchronization Tool provided to extract User and Group membership data from your directory data sources and export this data via the synchronization service. 2.1 Overview The Address Synchronization Tool is provided as a Java executable that will operate on a range of platforms supported by the Sun Java Runtime Environment (JRE). The tool operates either in an interactive mode through a graphical user interface, or as a command line application suitable for invocation by other scheduling services (e.g. Windows Scheduler). In the interactive mode, a wizard interface guides the user through the configuration steps to establish connection and extraction of data from LDAP-based directory sources, with testing and verification of each step. The tool is installed on a suitable system within your network (see sections 3 and 4 of this guide for details), thus simplifying the task of accessing local directories and minimizing security risks by ensuring that direct access to your directories from outside the firewall is not required. When run interactively, a full update of all data may be performed. Otherwise, when run from the command line, the tool will calculate the incremental changes since the last run and pass only these changes to MessageLabs as shown in the diagram below. Page 2

5 For Services clients, MessageLabs also operates harvesting of your sender addresses in order to automatically update the Registered Address list. To reflect these harvested changes the tool may also refresh its local change-tracking database from the list held by MessageLabs. Address Synchronization Tool 2.2 Features The Address Synchronization Tool provides the following features: Wizard-based configuration guiding the user through each configuration step Templates for common mail system directories - including Microsoft Exchange 2000 and 5.5 Configuration testing checking of each wizard step, and full configuration verification Filtering allowing specific or wild-carded addresses to be excluded or converted Safety thresholds update limits may be set in order to detect anomalous situations Reporting comprehensive logging and optional alerting via notifications Custom configuration advanced settings to refine the LDAP operations Multi-platform operation a direct benefit of Java application portability Full control of automation invocation from task schedulers or by other client tools Safe test mode no modification of live data using test output to text files Page 3

6 3 Preparation You will need to decide on a suitable system within your network on which to install and run the Address Synchronization Tool. This system should have internal network access to your directory system (via LDAP) and have external network access to the MessageLabs service (via HTTPS). If you intend to run the tool on an automated basis then you should also decide on whether the tool is to be invoked by a scheduling system (e.g. MS Windows Scheduler) or by other applications. For automated use it is important to note that the tool builds a local database, for the purposes of tracking changes to your source data, and so it is best if only a single instance of the tool is synchronizing any given set of source data. 3.1 Downloading the tool Download the Address Synchronization Tool from ClientNet from either: Configuration > Services Configuration > Platform > Tools Configuration > Web Security Services Configuration > Tools > Tool Download or Page 4

7 Before downloading the Address Synchronization Tool from ClientNet, decide whether you need the version with or without the Java Runtime Environment (JRE). If you already have JRE 1.5 or greater then either download image may be used, otherwise you will need to download the image with the JRE included. Appendix C With or without JRE? in this guide describes how to discover what JRE you are running and the impact of installing the Address Synchronization Tool with a JRE. 3.2 Obtaining a license key In order to enable the tool to use the MessageLabs synchronization interface (i.e. the remote HTTPS interface) you will need to acquire a relevant license key. Note: You can use the tool without a key, in order to prepare and test for live synchronization, by using the text file export capability to assess the collection of data. Note: There is a small one-off charge to obtain the license key. When you request a key, MessageLabs will contact you to ensure that you are aware of the charge Address registration A key can be requested from ClientNet and is supplied to you in a confirmation from a Client Services representative once they have verified your details. 1. Select Configuration > Services Configuration > Platform > Tools. 2. In the Synchronization Interface Activation area, click the Request key button: 3. Enter the address to receive the key and click OK. Page 5

8 3.2.2 Web group synchronization A key can be requested from the ClientNet portal and will then be displayed within the request page. 1. Select Configuration > Web Security Services Configuration > Tools > Tool Download. 2. In the Synchronization Interface Activation area, click the Request button: Page 6

9 4 Quick start This section of the guide provides procedures for installing the Address Synchronization Tool and for synchronizing address data from their local LDAP directory server to their MessageLabs account. There are two types of synchronization: mail users to MessageLabs, and groups and users to MessageLabs. 4.1 Prerequisites Before starting, ensure that you have the following items to hand: MessageLabs ClientNet portal account details Note: MessageLabs strongly encourages you to establish a separate ClientNet account for synchronization purposes. The Address Synchronization Tool license key Note: this is required to activate the MessageLabs synchronization interface. You can use the tool to extract address data to a file without a license key but not to perform tasks that access the MessageLabs infrastructure, which includes synchronization. There is a small one-off charge to obtain the license key. Address of your Directory Server and any authentication details you might need to be able to perform searches on it Note: authentication may be possible anonymously. Before downloading the Address Synchronization Tool from ClientNet, decide whether you need the version of the Address Synchronization Tool with or without the Java Runtime Environment (JRE). If you already have JRE 1.5 or greater then either download image may be used; otherwise you will need to download the image with the JRE included. For details of how to discover the JRE you are running and the impact of using the Address Synchronization Tool with a JRE, see Appendix C With or without JRE? 4.2 Installation Once you have downloaded the install image, open a terminal and ensure that the execute bit is set before running the script, for example: $ chmod +x Schemus_linux_jre.sh $./Schemus_linux_jre.sh Before starting the Address Synchronization Tool installation image, take the usual precaution of ensuring that all other applications running on the machine are closed. Then run the installer (the file downloaded as in section 3.1): Figure Initial window on the Windows Platform Throughout the installation press the Next > button to progress to the next stage. When the Next > button is disabled it means that additional information is required on the page before progressing. Page 7

10 1. Click the Next > button now to move to the license agreement window. 2. Read through the license agreement and (if your company is in agreement with the conditions) click the I accept the agreement option button to enable the Next > button. To stop the installation process, clicking the Cancel button. 3. Click the Next > button now to move to the installation location window. Figure Installation location window on Windows Platform The default install location will vary depending on the platform. Clicking on the directory window will automatically change the text of the directory path at the top of the window to that directory and then append schemus. So in the above figure, clicking on Common Files will change the text to C:\Program Files\Common Files\schemus. If you don t want to install in the sub-directory schemus, change the text of the directory path before clicking Next >. Figure shows the window to select where Schemus appears on your Windows Start Menu folder. If you want Schemus available to all users, ensure that the box is ticked. Figure Selecting the Start Menu Folder Click on Next > to move to the Windows shortcut window. This window is your last chance to update the installation options; clicking Next> starts the copying phase of the installer. Page 8

11 Figure shows the window to select where Schemus places a symbolic link on your filing system. Tick the Don t create symlinks if you want to run Schemus from its installed directory only. Figure Selecting the Symbolic link location This window is your last chance to update the installation options as clicking Next> will start the copying phase of the installer. Once the copying of files has completed the installer will display any release notes and change logs. The release notes will contain any additional information that has been introduced since this guide was written. Additional features and bug fixes will appear in this list as well as the history of changes. Click Next > to move to the end of the installer and Click Finish to quit the installer. 4.3 First time settings The first time that the Address Synchronization Tool is started, it will prompt you with a window enquiring about the type of synchronization that you will be using the Address Synchronization Tool for. Note: Selecting an option for which you do not have a valid license key will enable the tool in Safe Test Mode only, using test output to text files. This preference can be changed after installation, if required see section Figure First time settings Page 9

12 Click the relevant checkbox followed by the OK button. This setting is used when creating configurations so that when you create a new configuration it can automatically prompt you on the type of configuration and on completion of a component as to whether further configuration is necessary. The Address Synchronization Tool will only prompt you for this setting the first time it is run. If you decide to change this setting it can be found on the Settings menu off the main Edit menu. There is a tab labeled Synchronization which has the same two check boxes. Start the Address Synchronization Tool and select Settings from the Edit menu. Enter the client identity and the associated license key that was returned to you. The licensing procedure is covered in detail in the section Address Synchronization Tool in Detail. Click on MessageLabs in the left panel: Figure Configuring your MessageLabs details The Access URL is the address used to connect to MessageLabs and it is unlikely you will want to change this setting. Enter your MessageLabs account Username and Password and click the Apply button. If you receive an error message when you press the Apply button then it may be because your local network is setup to prohibit direct access to the Internet for https (i.e. secure http communication). See Address Synchronization Tool in Detail for further information. Click OK to close the Address Synchronization Tool settings window. Page 10

13 4.4 Creating a new configuration Before the Address Synchronization Tool can be used you need to create a configuration profile specifying details of the data source and destination systems. Figure Creating the first configuration To create a profile for the first time, either click the New Configuration button in the center of the window or click the "New" button located to the right of the Configuration drop down list or select New from the File menu. A new window will appear and the wizard will lead you through the configuration process. At each stage of the wizard the "Next >" button will be enabled once sufficient details have been entered to allow you to proceed. Whether you are intending to synchronize your mail data to MessageLabs, your group and user data or all three, the same name that you type here will encapsulate all these combinations of configuration. If you are configuring more than one type (and group and users counts as two types, the group and then the users) then you will proceed through the wizard multiple times although you may save your details after completing a single type. 4.5 Preparing to synchronize to MessageLabs The panel on the left hand side of the window displays how far through the creation process you are. If you wish to go back to modify a previously filled screen in the wizard either click the appropriate heading on this panel or successively click the "< Back" button. The figure below shows the selection of the configuration name (in this example we shall use the name example ). If you checked both the Mail and Groups+Users options when you first ran the Address Synchronization Tool then you will have a similar window to the one shown allowing you to select Mail, Groups or Users. If you just selected the Mail checkbox then you will not have a Synchronization Type drop down entry as the Address Synchronization Tool will assume you are creating a mail configuration. Page 11

14 Figure The Configuration Wizard The Configuration Name should be unique to other configurations and may contain most characters allowed by your operating system. When the Address Synchronization Tool is used in automatic mode (covered in the section Address Synchronization Tool in detail ) the name will be used to specify the configuration that you are using. For this reason you are recommended to restrict the characters to alphanumeric so the name may easily be given as a command line parameter. For this step-by-step guide, we shall use the name example. The Synchronization Type can be selected using the drop down list. Existing configurations appear in the list with the text (configured) following them. If you want to delete the configuration from a specific synchronization type (rather than all the synchronization types, which is done from the configuration menu on the main screen) then first select the entry from the drop down list then click the Remove button. To create a new synchronization type first select the entry from the drop down list and then click the Next > button. Note that the name at the top of the left hand side panel has changed to example and is followed by your synchronization type in brackets and that Data source is now highlighted in the panel. As you progress through the wizard the panel names will be enabled behind your current position. If you are modifying an existing configuration then all entries will be available in the left panel. Page 12

15 Click the Next > button to continue to move onto entering your source type. The figure below shows the default window for selecting your (in this example) mail data source. Figure Configure data source The Source Type is a drop down list containing different types of LDAP servers and the setting File. If you need to be able to configure multiple sources of data, for example if your data is distributed across multiple LDAP servers, or you would like to know how to source your data from a file then read the Data Source section in the Address Synchronization Tool in Detail section. Select the appropriate LDAP server from the list and click the Next > button to continue to the LDAP configuration. The figure below shows the LDAP configuration details for a Microsoft Active Directory server. Figure Configure LDAP Type in the host name of your LDAP server, unless you know otherwise, leave the port number as the default value (this differs depending on the authentication setting). Page 13

16 Type in your user name and password to retrieve results from your LDAP server. It may be that your server allows you to retrieve results anonymously, in which case set the authentication to anonymous but be careful that some servers restrict the results returned to anonymous users. In order to retrieve data from Active Directory it is recommended that the user identity used has read-only privileges equivalent to those of a domain administrator. Click the Next > button to continue to the LDAP search configuration. The figure below shows the LDAP search configuration window when configuring synchronization. The text appearing in the Search filter may differ from the example shown below depending on your configured data source. Figure Configure LDAP search This window allows you to select at what level of the hierarchical tree structure on the LDAP server to search. The "Search base" field, and drop down list and arrow buttons below it, allow you to navigate over the LDAP directory. Enter the path and directory to search or select a directory from the drop-down list. Some LDAP servers will not allow you to search for entries at their root and it may be necessary to manually type in a search base before you can browse further. The Search Scope field determines whether attributes from the LDAP server are searched below the level set in the search base. Setting this to Sub-tree will return the most results. The details of searching on your LDAP server are described in the section Address Synchronization Tool in Detail, but for most configurations we hope that editing the Search Filter field or clicking the advanced button will not be needed. If you accidentally change one of these fields, or wish to return to the top of your LDAP server s tree, then click the Defaults button. Page 14

17 Figure Configuring LDAP search for Groups The LDAP search configuration for groups and users have an additional field; the Name template. The name template defines a rule for constructing a text name that will be used to represent individual users and groups. Using simple template replacement strings the name may be constructed from other LDAP attributes. Text enclosed in percent (%) symbols is treated specially as an attribute otherwise it is just passed through as text. The full syntax and examples are described in Address Synchronization Tool in Detail section Click the Next > button to test your setting. Figure Example test results from mail configuration If you don t see any results check that: 1. The Source type on the Data Source screen is correct (changing this setting will automatically fill in a number of the advanced configuration settings which are explained in the Address Synchronization Tool in Detail section of the guide). 2. The Search scope on the LDAP search screen is set to Subtree (this will return the most results). Page 15

18 3. The Search base on the LDAP search screen is set to a suitably high enough place on your LDAP server s hierarchy to encompass the mail addresses/groups and users that you re searching for. 4. The Search base has not accidentally been altered so that the location typed in this field doesn t exist. If in doubt navigate to the top of the LDAP server tree and re-navigate to where you want to be. 5. You haven t accidentally changed the Search filter. Click the Defaults button to reset this field setting. 6. Your authentication on the LDAP screen is sufficient to return details from the LDAP server. If you had selected anonymous and no results are being returned then you may like to select simple and type in a username and password. For users and groups, the test results will show the names constructed by the Name template. You should check that these are returning representative names e.g. for users in a Microsoft environment this should represent the domain\username identity of individual users. Click the Next > button to select where to write your data to. Figure Selecting the data repository For this quick start guide we are setting the repository type to MessageLabs, so select it from the drop down menu. If you have not yet entered your license details, as described in the First time Settings earlier in this section, then you will not be able to synchronization your details with MessageLabs. Click Next > to progress to entering the ClientNet user setup details. Page 16

19 Figure ClientNet user setup If you followed the instructions in the First time settings you will notice that your MessageLabs user name and password details have already been set and you can click the Next > button to progress to the domain setup or configuring your filters. If you have not previously filled in your account details the Next > button will be disabled and you can either clicking the Address Synchronization Tool main window and select Settings from the Edit menu and then click Back then Next on this window to reload the details. Alternatively, you can click the Custom account details for this synchronization checkbox and enter the details here and then click the Set as default button. The Setting window also has the facility for setting your proxy details, should it be necessary to use an http proxy in order to access the Internet. If you are configuring a mail system, rather than groups or users that don t have this setting, you now need to select the domains you wish to use. There may be a slight delay as the MessageLabs service is contacted to retrieve your domain details. Figure Selecting MessageLabs domains To select the domains to use, click on the available domains and click the > button to use them (they will appear in the Domains to use list). To remove domains, click on them in the Domains to use area and click the < button. Page 17

20 You have now completed the basic source and destination configuration required for this type of synchronization. Now you can set up optional filters, to exclude or change details as they are found on your LDAP server and before they are written to the MessageLabs server. If you intend to use filters, see the section Address Synchronization Tool in Detail otherwise click Next > to continue to the limits settings. The optional limits settings allow you to protect an existing synchronization against accidental modification due to misconfiguration of the Address Synchronization Tool or your LDAP server returning incorrect results (perhaps due to its misconfiguration). By setting limits on the maximum number of synchronization changes, a radical change in the number of additions, deletions, or modifications can halt the process thereby safeguarding your data. Again, if you intend to use limit settings, see the section Address Synchronization Tool in Detail otherwise click Next > to continue to the Notification settings. The optional notification settings request the Address Synchronization Tool to send an notification on completion of synchronization, whether or not it was successful. If you are running the Address Synchronization Tool from the graphical user interface this should not be required, however if the Address Synchronization Tool is scheduled to run from the command line this option is strongly recommended. See the section Address Synchronization Tool in Detail for a description of this functionality. Click the Next > button to continue to the Summary screen. Figure Validating your configuration To complete your synchronization type configuration you should first verify your existing settings by clicking the Verify button or clicking Save, which will offer you the option of performing the verify. Click Next > to move to the final step for creating your synchronization type. Page 18

21 Figure Completing a synchronization type configuration You now have the option of configuring alternative types of synchronization. In particular, if you have just created a group configuration, you are expected to select a Synchronization Type of Users and complete the configuration for that. To add another synchronization type under this configuration name (in this case example ) just select the type from the Synchronization Type drop down list and then click the Add button. Alternatively click Finish to complete the wizard configuration and close the window. Page 19

22 5 Performing the synchronization Once you have created your configuration, you can synchronize your data with MessageLabs. First ensure your newly created configuration is selected from the drop down list on the configuration window shown below. Select the required configuration from the drop down list on the configuration window (select Configuration from the View menu). Figure The Configuration Window The functions on the left hand panel are also accessible from the Configuration menu with the exception of Delete (removes your currently selected configuration) which is only available from the Configuration menu. Summary displays a summary of the synchronization. If you have multiple synchronization types, examine each in turn by clicking the appropriate tab. Clicking the Modify button allows you to edit your settings for the current synchronization type. Test Update looks at the addresses on your source (file or LDAP server) and lists which are additions, removals or exclusions but does not change any details on your repository. Clicking on an entry in one of these columns will provide additional information about the entry; for users this will include address and groups that the user is a member of. Update compares the details held in your local change tracking database and sends those that have been removed or added. This incremental update is an efficient way to pass changes to MessageLabs and preserve unchanged data. Replace recreates your local change tracking database and resends all data to MessageLabs. Refresh retrieves all data from MessageLabs and uses this to recreate your local change tracking database. This allows subsequent update operations to be based upon calculating changes from a current copy of the data held by MessageLabs. Figure Successful repository update Page 20

23 Once the update has completed, you can click on Mail, Groups and Users to inspect the results. To sort the list, click on the grey title bar of the column to sort. Stop is only enabled while synchronization is ongoing. Clicking Stop halts the synchronization. Replace resets the contents of your change tracking database and resends all the data again. Page 21

24 6 Address Synchronization Tool in detail This section of the guide provides a detailed description of the functionality of the Address Synchronization Tool. Depending on what features are enabled in your license key, some of the functionality described below may not be available to you. 6.1 Address Synchronization Tool settings This section describes the functions available from the Settings menu, found on the Edit menu on the Address Synchronization Tool main window License To use the full functionality of Schemus a license key is required and is available from MessageLabs. Each key may be entered from the Settings menu, which is under the Edit menu. Select License from the left hand panel and click the Add license tab. Figure Entering license details The Licensed to field is the client identity supplied to you for registration purposes. The License key is an alphanumeric field with no spaces, as provided by MessageLabs. Once your licensing details have been entered click the Apply button and then click the tab Show License to see which features have been enabled, your serial number and license expiry date. Figure Viewing license details If you have entered multiple licenses, left and right arrow buttons appear to enable you to view each license. Licenses with duplicate features are automatically removed. If an expiry period is specified in the license, the license with the longer expiry period is retained. Page 22

25 6.1.2 Synchronizations This setting is initially set when the tool is started for the first time. When you create a configuration, the options you selected determine the synchronization types that are presented here. This setting is independent of the features that your license enables; an option that you do not have a valid license key for enables the tool in Safe Test Mode only, using output to text files. Figure Configuring the types of synchronizations Log settings This specifies the maximum number of days that logs are retained before they are automatically removed by LDAP Synchronization Tool. If the number of days is set to 0 then the logs files are held indefinitely. Note: If the logs are held indefinitely in this way, check periodically that you have enough disk space to permit the creation of new logs when the tool is run. Figure Configuring log settings Page 23

26 6.1.4 LDAP This setting is the LDAP string used to search for entries when browsing the LDAP server on the search configuration screen. Figure Configuring LDAP browsing search string This window is explained in Appendix C MessageLabs Figure Configuring your MessageLabs details Unless instructed to do so by MessageLabs, do not change the default value in the Access URL. If you change this line by accident, click Reset Defaults to put the original value back into this field. The Username and Password are the account details provided to you by MessageLabs. When these details are entered, click the Apply to connect to MessageLabs using these details. If you receive an error message when you click Apply, you may need to connect to MessageLabs via an http proxy. Page 24

27 Figure Configuring your MessageLabs details through a proxy If you need to access the Internet through an http proxy then change the HTTPS Proxy setting to Manual and enter the connection details in the newly appeared fields. If in doubt, start your Internet browser and look at the connection settings being used for that. 6.2 The configuration wizard This section describes the windows available by clicking Modify on an existing configuration on the Address Synchronization Tool main summary window, or by creating a new configuration Data sources There may be a single or multiple data sources for each type of synchronization. The single data source is show in the figure below. A selection from a drop down list of the different types of LDAP servers and the file data source may be made. For LDAP servers, the type chosen here determines the default attributes used to retrieve data later in the wizard. By choosing the correct type of server from the drop down list most default values, appearing later in the wizard, will automatically be chosen. Figure Configuring a single data source Page 25

28 For more complex configurations (e.g. using multiple disparate directories) it may be necessary to have multiple data sources. To enable this feature check the Advanced check box. The window will be redrawn similar to the figure below. Figure Configuring multiple data sources Select <Add another source> from the drop down list and a new source is generated. The drop down list for Source is initially populated with a name beginning with the type of synchronization (mail, groups or users) and other entries that you have entered and fully filled, although you may change the current name to something more representative. For each source that you create, there is a Source Type and, on subsequent screens, for LDAP settings each source will be associated with its own server name and port, (optionally) any proxy settings, the top of the search point in the directory tree, and attributes to retrieve from the server. Until you have completed these fields, you cannot select your source from the list. Once multiple sources have been defined the Advanced check box is disabled and it is not possible to switch back to the simple data source definition screen until only one source remains. To remove a data source definition, select it from the drop down list and click the Remove button. It is not possible to remove all data sources. Page 26

29 6.2.2 LDAP server configuration The Host Name is the address of your directory access server, for example, exampleserver.examplecompany.com and Unless you know to the contrary, leave the Port number set to 389 (this is the default port number used for communicating with an LDAP server in plain text mode). Changing the communication protocol may change this default setting. Figure Entering LDAP Server details Although you may be able to retrieve search details from the LDAP server anonymously, connecting in this mode may restrict the number of search results. If the protocol used to communicate with the server is not plain then you will need to ensure that either the server uses a certificate which has been signed by a trust point already held in the JRE root certificate store (cacerts) or that if the server uses a self-signed certificate then it has been imported. You can import your certificate into the file {installation directory}/jre/lib/security/cacerts using the utility {installation directory}/jre/bin/keytool. Note: Further documentation may be found on the Sun website at Clicking the Advanced button will move onto paging settings and referral settings. Figure Advanced LDAP Configuration Page 27

30 Using a page size of 100 results is the default setting and means that a maximum of 100 results are retrieved from the LDAP server at a time. Not all LDAP servers support paging but the Address Synchronization Tool will automatically switch to using non-paging mode if unavailable and log this fact. The configuration of some directory servers may limit the maximum number of results that may be provided in one go. The paging facility is provided to overcome this. For a server that has 220 results, a page size of 100 would retrieve entries 1 to 100 the first time, 101 to 200 the second time and 201 to 220 the third time. As displayed by the Address Synchronization Tool, this would just appear as though 220 results had been returned. An LDAP server may contain referrals to other points on the server, or indeed to points on other LDAP servers. The default action is for the Address Synchronization Tool to follow these referrals to continue retrieving results. If you notice that a directory server referred to is intermittently available then there are two schemes for handling this: either set the referral action to Abort update or set threshold limits to ensure that the update doesn t continue if there is an abrupt difference in the number of results returned. Note that the DNS name or IP address that the Address Synchronization Tool follows is the one that is seen by the machine running the Address Synchronization Tool application. If you experience problems with the Address Synchronization Tool following referrals, ensure that you are able to contact the referred servers by the use of an application like ping. Clicking the Next > button will move onto editing your LDAP search criteria. If there are problems with your LDAP connection details, from the previous window, then these will be shown in red at the bottom of the window. Click the < Back button to amend your LDAP server settings LDAP search configuration Common to configuring mail, groups or users are the Search base, the base of the hierarchical tree to search for data, and the Search scope, the detail at which to search for data. Figure Configuring LDAP search configuration The "Search base" field, and drop down list and arrow buttons below it, allow you to navigate over the LDAP directory. Initially the search base field will show the text <Enter search base or browse list below> but clicking on the text will clear it. The drop down list will contain all the entries at that level of the directory. The criteria for which object classes are returned are defined in the setting LDAP (see appendix B for details of the syntax). Selecting an entry from the drop down list will result in that entry appearing in the search base field. The drop down list will now contain all entries at your new position in the hierarchical tree. Clicking on the first item in the drop down list (an up arrow on a directory folder icon) moves you back up the tree. Most LDAP servers will not allow you to search for entries at their root and it may be necessary to manually type in a search base before you can browse further. The "Search scope" field contains three options for selecting the depth at which entries are looked for at the point in the tree specified by the search base field. Page 28

31 "One-level" will search for all objects at the level specified in the search base field. "Object" will search for a single object specified by the search base. "Sub-tree" will search from the level specified in the search base field downwards until restricted by the LDAP server or the bottom is reached (to return the most results use this option). The "Search filter" is the type of object to return data on. See appendix B for a description of the syntax and how to specify a different search filter Mail attributes Clicking the Advanced button reveals the mail search attributes. The default settings for these attributes are derived from the type of LDAP server you selected in the data source. Figure Configuring advanced mail attributes The "Mail attribute" are the attributes within the object returned by the search filter that contain the mail address. The "Alias Attribute" is an optional alternative to the Mail attribute. If you need to supply multiple alias attributes then these should be comma separated. If an address returned from this attribute is preceded by smtp: then this is automatically removed. Page 29

32 Group attributes The Name template field provides simple parameter substitution to generate the name attribute. Attribute names are delimited by percent (%) symbols and the special attributes DN[n] and DC[n] allow a portion of the object class s distinguished name to be used. Anything not enclosed between % symbols is treated as literal text. The number (n) following the DN or DC is an index, starting from 1, from the least significant component. When used with DN, the index references components of the distinguished name. When used with DC, the index references only the DC components of the distinguished name. If the number exceeds the number of components then an empty string is substituted. A negative value of n references the components starting from the most significant component first. For example, if we were to find the following object class: dn: cn=marketing, ou=security, dc=examplecompany, dc=com objectclass: group Name: SecureMarketing SamAccountName: SecurityMarketingServices The template %Name%\%DN[-2]%.%DN[-1]% would resolve to: SecureMarketing\Security.Marketing The template %DN[1]%\%SamAccountName% would resolve to: com\securitymarketingservices The template %Name%\%DC[1]%SamAccountName% would resolve to: Com\SecureMarketingServices The template %DC[-1]%\%SamAccountName% would resolve to: messagelabs\securitymarketingservices Figure LDAP group search configuration Click the Advanced button to edit the group attributes. Page 30

33 Figure LDAP group search attributes The Group GUID attribute is a unique identifier maintained by the LDAP server. Not all servers are guaranteed to support this attribute (Microsoft Active Directory does) but it should be used if available. If this attribute is omitted then an identifier will be derived from the distinguished name (DN) of the object class instead. Using a DN has the undesirable effect of the group entry being removed and added again if the group is renamed rather than just modifying the entry this would mean that any association with that entry in the ClientNet domain would be broken, and would have to be re-established. The Group Token attribute is the optional attribute that holds the number that this group is in. The value may in turn be referred to by the Primary Group attribute in the user object class settings. If a user has its primary group set to this group s group token then the user is part of this group. The Group Parent attribute is used to relate one group to its parent group, if it exists. The optional attribute retrieved from the directory may consist of a single DN which contains the parent of this group. The Group Members attribute is the name of the multi-value attribute that holds the users (in DN form) that are part of this group. Within Active Directory this attribute is not used, and may be left blank, as the symmetrical details are available from the user details and automatically maintained by the server. Page 31

34 User attributes See the previous section for details on the Name template and the mechanism to generate unique names using templates. For users in a Microsoft environment, the names constructed by the Name template should represent the domain\username identity of individual users i.e. a name form suitable for authentication purposes. Figure LDAP user search configuration Click the Advanced button to edit the user attributes. Figure LDAP user search attributes The Primary Mail attribute is used to retrieve the address for this user. The Primary Group attribute is the token number attributed to this user and potentially matching a group s Group Token attribute value which places this user in that group. This attribute should be considered as an extension to the Other Groups attribute for placing a user in a particular group and not all LDAP directories will offer support for it. The Other Groups attribute is the attribute name that describes which group or groups this user belongs to. For Active Directories this will be symmetrical to the Group Parent attribute for the group object class which points from each group to its users. If this attribute is omitted, or your directory does not support this feature, then the Address Synchronization Tool will search for each user in the entire list of groups. For users to be correctly associated with groups either the Group Parent Attribute must exist and the User GUID attribute and Group GUID attribute must be omitted or the group attribute Group Members attribute must exist. Page 32

35 The User GUID attribute is a unique identifier assigned to each user in a similar fashion to the Group GUID attribute for groups and similarly the omission of this attribute will result in an identifier being derived from the object class s distinguished name. If this attribute is omitted then the Group GUID attribute should be omitted too Testing LDAP attributes If you have needed to change any of the default attributes used for the LDAP search then the advanced version of the test screen will allow you to confirm that you have correctly retrieved the attribute you were expecting. Ensure that the check box Show detail is checked. Columns in the table may be reordered by clicking and dragging the top of the column. Figure Detail of attributes returned by an LDAP search There is no detailed option available for mail addresses. For groups, each line will contain: The result from the name template, subsequent to it being changed using any template rule. The GUID. If no Group GUID attribute has been provided then this will have been derived from the DN. The Group Token retrieved using the Group Token attribute. The DN automatically retrieved for you by the Address Synchronization Tool. The number of parents that this group belongs to (normally none or 1) and the DN of the first of these groups. Retrieved using the Group Parents attribute. The number of users in this group and the DN of the first of these users. Retrieved using the Group Members attribute. For users, each line will contain: The result from the name template, subsequent to it being changed using any template rule. The GUID. If no User GUID attribute has been provided then this will have been derived from the DN. The address retrieved using the Primary Mail attribute. The Primary Group retrieved using the Primary Group attribute. Groups. The DN automatically retrieved for you by the Address Synchronization Tool. For both groups and users, if the Name, the GUID, or the DN is blank, correct the attribute names before commencing. Page 33