Configuration Guide for Postini Directory Sync
Postini, Inc. 959 Skyway Road, Suite 200 San Carlos, CA 94070 www.postini.com Part number: DSCON_6.10_08 5 June 2007
© Copyright 2007 Postini, Inc. All rights reserved. Postini, the Postini Logo, Perimeter Manager, Security Manager, Network Edition, AirPostini, and Postini Message Platform are either registered trademarks or trademarks of Postini Inc. Postini is a registered trademark of Postini, Inc. All other trademarks are the property of their respective holders. Use of any Postini solution is governed by the license agreement included in your original contract. Any source code is a confidential trade secret of Postini Corporation. You may not attempt to decipher, decompile, or develop source code for any Postini product or service offering, or knowingly allow others to do so. Postini documentation may not be sublicensed and may not be transferred without the prior written consent of Postini Corporation. Your right to copy this manual is limited by copyright law. Making copies, adaptations, or compilation works, without prior written authorization of Postini Corporation is prohibited by law and constitutes a punishable violation of the law. No part of this manual may be reproduced in whole or in part without the express written consent of Postini Inc. Postini Corporation provides this publication “as is” without warranty of any either express or implied, including but not limited to the implied warranties of merchantability or fitness for a particular purpose. Postini Corporation may revise this publication from time to time without notice. Some states or jurisdictions do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you.
2
Configuration Guide for Directory Sync
Contents
Chapter 1: Introduction to Directory Sync About Directory Synchronization 5 Installation Introduction 5 System Requirements 6
5
Chapter 2: Architecture 7 About Directory Sync Architecture 7 Technologies Used 7 Directory Servers 7 DSML 8 SSL with Basic Authentication 8 Data Flow 8 Mapping and Synchronization 9 Chapter 3: Microsoft Active Directory 11 Directory Sync with Microsoft Active Directory 11 Install Prerequisite Tools 11 Install IIS 12 Download and install MSXML 4.0 - SP2 12 Download and install .NET Framework Runtime Library Install and Enable DSML 12 Verify DSML 16 Set Up an SSL Certificate 18 Enable SSL 33 Adjust Server Settings 34 Disable token caching to prevent attacks 34 Disable search entries limit 35 Collect Information for Directory Sync setup 36 Troubleshooting 37 Chapter 4: IBM Lotus Domino Directory Server Directory Sync with IBM Lotus Domino 39 System Requirements 40 Setup Overview 41 Enable LDAP support on your DSML Server 42 Install Java libraries 43
12
39
Contents
3
Install WebSphere Express 44 Install WebSphere Application Server 44 Copy Libraries 44 Configure WebSphere Express 45 Install SOAP into WebSphere Application Server 46 Confirm WebSphere and SOAP installation 47 Install DSML 48 Unpack DSML.zip 49 Modify IBM DSML Deployment Descriptor 49 Configure CLASSPATH 50 Install IBM DSML into SOAP 50 Verify DSML installation 51 Collect information for Directory Sync setup 51 Create batchrequest.dsml file 52 Configure Directory Sync in the Administration Console Setup Checklist 54 Troubleshooting 55 Chapter 5: Sun ONE Directory Server 57 Directory Sync with Sun ONE DS 57 Enable SSL 58 Obtain and Install Server Certificates 58 Activate SSL 62 Install DSML 63 Configuring Basic Authentication 64 Configure DSML Identity Mapping 64 Collect Information for Directory Sync setup 66
4
Configuration Guide for Directory Sync
54
Introduction to Directory Sync
Chapter 1
About Directory Synchronization The email protection service is a managed service which filters messages, protecting your mail flow from spam, viruses, and attacks. The service stores a list of users, to allow each user to have custom quarantine and mail filter settings. With Directory Sync, the email protection service can contact your directory server to collect your user list information. Directory Sync will add, delete or move users so that the registered users in the email protection service match the registered users on your directory server. Directory Sync connects to your directory server securely, using standard XML technology. Some setup is required to enable Directory Sync to connect to your directory server. This guide describes the software and settings needed for compatibility with Directory Sync.
Installation Introduction To install Directory Sync, you’ll need to set up your network to allow Directory Sync to connect to a server on your network. This can be a new or existing server, so long as the server is accessible from the Internet. You’ll need to install and a few components on this server. These components are freely available from your directory server vendor. Directory Sync uses the following technologies: •
DSML, Directory Services Markup Language, a component to translate LDAP information to standard XML.
•
SSL, Secure Sockets Layer, a secure means of transmitting sensitive data through the Internet.
•
Basic Authentication, a standard way to authenticate administrators on your directory server with a user name and password.
Once you’ve enabled these components, you’ll collect information from your directory server. Directory Sync uses this information to contact your server and import settings.
Introduction to Directory Sync
5
System Requirements Directory Sync requires the following:
6
•
A directory server. Directory Sync can connect to Microsoft Active Directory 2000 or 2003, and Sun ONE Directory Server.
•
DSML v2.0. Directory Sync collects information from your directory server using the DSML v2.0 standard to translate between XML and LDAP.
•
SSL. Directory Sync connects to your DSML server as an SSL client. We will accept any valid certificate, including self-signed certificates.
•
An open port. Directory Sync will connect to your directory server through a standard SSL port. Usually, this is port 443.
•
Basic authentication. Directory Sync logs in to your directory server with a user name and password. The user must have read access to the LDAP directory used.
Configuration Guide for Directory Sync
Architecture
Chapter 2
About Directory Sync Architecture Directory Sync is an optional feature included with the enterprise edition of the email protection service. Directory Sync connects to your directory server, using a Secure Sockets Layer (SSL) connection and basic authentication. Directory Sync runs on the email protection servers. You’ll need to set up a DSML server to allow Directory Sync to connect and upload information. See “Microsoft Active Directory” on page 11 for more setup information for Microsoft Active Directory, and “Sun ONE Directory Server” on page 57 for more setup information for Sun ONE Directory Server. This section provides an architectural overview of how organization structures are mapped, technologies used, and synchronization data flow.
Technologies Used Directory Sync connects to your network using DSML v2, through an SSL connection and basic authentication.
Directory Servers A directory server is a repository for information about an organization, which typically includes user properties. Other applications can then connect to the server to collect, use and sometimes change this information. One way to store and provide this information is a protocol called LDAP (Lightweight Directory Access Protocol), which stores organization information in a hierarchy called a tree. A Base DN (Distinguished Name) provides a location on the tree for particular information. For instance, a Base DN might specify where to find the user list for a particular department. Directory Sync acts as a client, connecting to the directory server and collecting information about users and aliases. It then updates your the email protection service’s user lists based on this collected information, adding, deleting and moving users. This allows you to update large user lists quickly and thoroughly.
Architecture
7
DSML DSML (Directory Services Markup Language) is a protocol which uses XML (Extensible Markup Language), a machine-readable standard format, to encode LDAP information. DSML allows different applications to share directory information over the Internet in a standard format. With DSML, applications usually communicate through HTTP, the protocol used most often for serving web pages. Directory Sync relies on DSML for all directory information. DSML is freely available for most directory servers, but requires additional configuration and setup. For full information about installing DSML, see “Install and Enable DSML” on page 12 for Microsoft Active Directory, and “Install DSML” on page 63 for Sun ONE DS.
SSL with Basic Authentication SSL (Secure Sockets Layer) is a protocol for communicating securely over the Internet. Because the user lists gathered by Directory Sync are sensitive information, only secure connections are used. To accept SSL connections, your DSML server will need a certificate. Certificates can be assigned by a certificate authority such as Verisign or THAWTE, but can also be self-signed. Directory Sync will accept any certificate authority used, including self-signed certificates. SSL is freely available for directory servers, but you must install a certificate and configure SSL on your directory server first. Directory Sync also uses basic authentication to assure that your user lists are protected. When Directory Sync connects to your directory server, it logs in to the server, using a user name and password you provide. This user will need to be able to read information from your directory server, but will not need to modify any information. You will need to enable basic authentication on your web-accessible DSML server. If you do not have a user with read privileges for Directory Sync to use, you will need to create a new user on your directory server with proper authorizations. For full information about installing SSL, see “Enable SSL” on page 33 for Microsoft Active Directory, and “Enable SSL” on page 58 for Sun ONE.
Data Flow Once your directory server is set up, and Directory Sync is configured with necessary connection information, the email protection service will be able to connect to your server and read data. Directory Sync is initiated by the email protection service. 1. Directory Sync runs when your administrator logs into the Administration Console and begins synchronization.
8
Configuration Guide for Directory Sync
2. Directory Sync opens a secure SSL connection to the address you have provided, and logs on to your DSML server using basic authentication. 3. Directory Sync requests a user list for a Base DN that you provide from your directory server. 4. Your DSML server opens the LDAP directory and queries the user list for the appropriate organization. Depending on the Directory Sync settings, this may be a request for a user list for the base DN, or a recursive request for information for the base DN and the whole subtree beneath it. 5. Your DSML server collects this information from the LDAP directory, and reformats it into XML. 6. Your DSML server sends this information back to the email protection service in response to the DSML request. The session closes. 7. Directory Sync checks the user list against the current list of registered users in the email protection service. Directory Sync generates a list of changes needed to update the email protection service’s user list to match the user list on the directory server. 8. Directory Sync displays a list of changes to the email protection service for verification. If there are any problems with connectivity, or if the changes exceed any limits the administrator has set, an error will be displayed. Otherwise, the administrator will have the option to synchronize the email protection service’s user lists. 9. If the administrator approves changes, the email protection service’s user list is updated.
Mapping and Synchronization Users in the email protection service are organized in a hierarchical structure. One or more organizations will be mapped to organizations in your directory server.
Architecture
9
Directory Sync acts as a one-way synchronization tool. Your users and aliases in the email protection service are added, moved or deleted, but your directory server is not changed in any way. Directory Sync is launched manually from the Administration Console in the email protection service. Directory Sync is set up on a specific user organization, and synchronizes that organization with an organization unit (OU) on your directory server. Directory Sync can synchronize with one particular organization unit, or with a whole subtree. It’s also possible to set up several organizations with Directory Sync. Usually, each organization in the email protection service is set to map to a distinct OU on your directory server.
10
Configuration Guide for Directory Sync
Microsoft Active Directory
Chapter 3
Directory Sync with Microsoft Active Directory Microsoft Active Directory is an LDAP based directory which holds organizational information, and is often used with Microsoft Exchange. If you are using Active Directory 2000 or 2003, Directory Sync can collect this information. Allowing this connection requires setting up SSL and DSML in your environment. DSML (Directory Services Markup Language) allows an HTTP session to use SOAP to access Active Directory. DSFW runs as a module on a server running Internet Information Services (IIS) version 5.0 or later. It uses SOAP over HTTP to transmit and receive directory requests from client computers. Directory Sync acts as a client sending DSML requests to the customer server to query the users in the customer’s Active Directory. Setting up Directory Sync with Microsoft Active Directory consists of six steps: 1. Install Prerequisite Tools. 2. Install and Enable DSML. 3. Set Up an SSL Certificate. 4. Enable SSL. 5. Adjust Server Settings. 6. Collect Information for Directory Sync setup.
Install Prerequisite Tools You’ll need to install several components before you’ll be able to install DSML and SSL on your server. This includes IIS, MSXML and the .NET Framework Runtime Library. Download and install all of these components, using the instructions below.
Microsoft Active Directory
11
Install IIS DSML services require that IIS be installed on your server: 1. Double click the “Add / Remove Programs” option in the Control Panel. Windows will display the “Add / Remove Programs” dialog box. 2. Click the “Add / Remove Windows Components button”, and Windows will launch the Windows Components Wizard. 3. Select the “Application Server” option. 4. Click Details. 5. Check the Internet Information Services (IIS) box 6. Click OK followed by Next to install IIS. IIS is now installed on your server.
Download and install MSXML 4.0 - SP2 DSFW requires that MSXML 4.0 be upgraded to at least Service Pack 1. MSXML is the core XML service for Windows. At the time of this writing, MSXML 4.0 Service Pack 2 is available. You can download Service Pack 2 from the Microsoft web site at: http://www.microsoft.com/downloads/details.aspx?FamilyID=3144B72BB4F2-46DA-B4B6-C5D7485F2B42&displaylang=en
Download and install this package.
Download and install .NET Framework Runtime Library The .NET Framework Runtime Library is required for configuring DSML Services for Windows. Follow this link to download .NET Framework Runtime Library: http://msdn.microsoft.com/netframework/downloads/framework1_1/
Download and install this library.
Install and Enable DSML To set up DSML, you’ll install the DSFW (DSML Services For Windows) component. This is available for free online. Follow this link to download the DSFW: http://www.microsoft.com/windowsserver2003/downloads/featurepacks/ default.mspx
Once you have downloaded the DSFW, begin installing the DSML services.
12
Configuration Guide for Directory Sync
1. Double-click on the DSFW.msi file that you have downloaded earlier. 2. Windows will launch the DSML Installation Wizard. 3. Click Next on the Welcome screen to see the software’s end-user license agreement. 4. Read and accept the license agreement 5. The setup wizard will prompt you for an installation path and ask you whether everyone should be able to use it or just you. Select either option. 6. Make your selection. 7. Click Next twice. Installation will begin. When the installation process completes, you’ll see a message informing you that DSML has been successfully installed. 8. Click Next and Close. After you’ve installed DSML, enable the services. You must configure the DSML services before you can enable them. 1. Go to Start->All Programs->Microsoft DSML->Configuring DSML Services to open DSML Services Configuration.
Microsoft Active Directory
13
2. Enter the IIS web site name that you want to associate with DSML. If you are not sure which site to use, use the default. 3. In the IIS Virtual Directory Name field, enter “dsml” or another directory name. 4. Uncheck the Require SSL to connect to DSML Server. You will enable SSL in a later step. Disable SSL for now so that we can run the test programs that come with DSFW. 5. Click Create IIS Virtual Directory Now to move to Step 2.
14
Configuration Guide for Directory Sync
.
6. In Step 2 of the configuration and enabling process, make sure the name of your Active Directory domain is correct and click Add to DSML Configuration File Now. 7. Click Close on the DSML Services Configuration dialog box to finish. The configuration and enabling process is completed. You are now ready to test for DSML setup.
Microsoft Active Directory
15
Verify DSML Use the sample Visual Basic test (included with DSML Services for Windows) to test your configuration. The sample programs do not support SSL, so be sure SSL is not enabled in the DSML module for this step. Disable SSL in the DSML Module
1. Launch IIS Manager, from Start->Administrative Tools->IIS Manager. 2. Locate DSML module inside (local machine) under Web Sites->Default Web Sites. 3. Right-click on the DSML module and select Properties. 4. Click on the Directory Security tab. 5. In the Secure communications box, click Edit… 6. Uncheck Require secure channel (SSL). 7. Click OK twice to close both dialog boxes. The sample VB programs are located in the folder where you installed DSML services for Windows. For example, if DSML services for Windows was installed in C:\DSFW, the sample code would be found at: C:\DSFW\Documents\Samples\programming\vbscript
Open a command prompt and go to the sample VB programs directory.
16
Configuration Guide for Directory Sync
In the sample directory, use cscript to run “dsmltestcred.vbs”. You may want to view the sample code by typing “type dsmltestcred.vbs” to see the command line options. Remember to supply the command with a user name and password.
Troubleshooting DSML Verification
If running the test program is not successful, check your DSML setup by going back to Configuring DSML Services. Make sure the name of your AD is correct. If you need to make corrections, consider deleting the DSML module from IIS and recreating it. If the test program fails, there are several factors that can cause this problem. Make sure that Local System account is configured for the IIS Admin service: 1. Go to the Control Panel at Start->Settings->Control Panel. 2. Click Administrative Tools and then Services. 3. Double-click on IIS Admin Service. 4. On the Log On tab, verify that the option for Local System Account is selected. 5. On the Dependencies tab, verify that the following system components depend on the IIS Admin Service: FTP Publishing Service, Indexing Service, Simple Mail Transport Service (SMTP, World Wide Web Publishing Service. If problems still occur, verify that the user name that is used for authentication to DSML services has log-on privileges to the IIS machine. Try to log on to the IIS server with the user name and password to used with DSML services. Lastly, verify that the NTFS permission on the DSML modules allows read and execute access to the group of users that includes the user that is used for authentication to DSML services. With Windows Explorer, right-click on C:\DSFW\bin\adssoap.dll (and then again on C:\DSFW\bin\adssoap.dsmlx), select “Properties” and click on “Security” tab to verify the NTFS file permission on these files.
Microsoft Active Directory
17
Enable SSL in the DSML Module
Once you have completed the test, enable SSL in the DSML to set a secure connection. 1. Launch IIS Manager, from Start->Administrative Tools->IIS Manager. 2. Locate DSML module inside (local machine) under Web Sites->Default Web Sites. 3. Right-click on the DSML module and select Properties. 4. Click on the Directory Security tab. 5. In the Secure communications box, click Edit… 6. Check Require secure channel (SSL). 7. Click OK twice to close both dialog boxes.
Set Up an SSL Certificate Because Directory Sync extracts company information over the Internet, it is vital that all connections are secure. Every time Directory Sync connects to your directory server, it will make a secure SSL connection to collect the data. Note: This is the most basic, step-by-step way to create a self-signed certificate.
You may not need to make these steps. If you already have an SSL Certificate, skip this step and go to “Enable SSL” on page 33. To install an SSL certificate
1. Go to Control Panel -> Administrative Tools -> IIS Manager 2. Open your IIS web site. 3. Right-click on Default Web Sites and select Properties. 4. Go to the Directory Security tab on the Properties dialog box.
18
Configuration Guide for Directory Sync
5. Click Server Certificate... to start the IIS Certificate Wizard.
Microsoft Active Directory
19
6. Click Next.
7. Choose Create a new certificate and click Next.
20
Configuration Guide for Directory Sync
8. Choose to Prepare the request now, but send it later. Click Next.
9. Enter a name for the new certificate and leave the bit length as 1024. Click Next.
Microsoft Active Directory
21
10. Enter the names for organization and organization unit that will be stored in the new certificate. and click Next.
11. Enter the full DNS name for the IIS machine which you're installing the certificate. Click Next to continue.
22
Configuration Guide for Directory Sync
12. Enter the State/province and City/locality fields. Click Next.
13. Enter the location to store the certificate request file. Note this location for later. Click Next.
Microsoft Active Directory
23
14. View the summary and confirm that the information is correct. Go back and make any changes if needed. When your settings are complete, click Next. 15. Click Finish to generate the new certificate request. You now have a pending certificate request, which can be processed and accepted in Microsoft Certificate Services. Add Certificate Services to IIS
Enable Certificate Services, if your server does not already have Certificate Services enabled. 1. In the Control Panel, open Add / Remove Programs and choose Add / Remove Windows Components.
24
Configuration Guide for Directory Sync
2. Check the Certificate Services check box. A popup confirmation will appear.
3. Click Yes to confirm that you wish to enable this service. The Windows Component Wizard will open.
Microsoft Active Directory
25
4. Choose Stand-alone root CA. Click Next.
26
Configuration Guide for Directory Sync
5. Enter the name of the IIS machine for the Common Name for this CA. Click Next to continue.
6. Use the default locations for the certificate database settings and click Next. A confirmation dialog box will open.
7. You will need to stop and start your IIS server to enable Certificate Services. Click Yes to restart the server. 8. On the Completing Windows Component Wizard page, click Finish. Submit the Certificate Request
One you have set up Certificate Services, you can connect to the service to process your certificate request. 1. Launch Internet Explorer and navigate to Certificate Services on your local machine: http://localhost/certsrv
Microsoft Active Directory
27
2. Click Request a certificate.
3. Click Advanced certificate request.
28
Configuration Guide for Directory Sync
4. Click Submit a certificate request by using a base-64-encoded CMC or PKCS #10 file, or submit a renewal request by using a base-64-encoded PKCS #7 file.
5. On this screen, insert the content of the certificate request, which you saved to disk from the IIS Certificate Wizard. Cut and paste the content from the saved file into the dialog box. 6. Click Submit to process the request.
Microsoft Active Directory
29
Issue Pending Certificate Request
After a certificate request is submitted, it remains in the queue waiting to be accepted and issued. Log on as an administrator to issue the certificate you have just requested. 1. Log into the IIS machine as a user with admin privileges. 2. Go to Start -> Administrative Tools -> Certification Authority.
3. Open the tree and click Pending Requests. 4. Right-click the pending request on the right pane and click All tasks -> Issue. 5. Close Certification Authority. You have now issued the certificate, using your own Certificate Authority. Retrieve the Newly Issued Certificate
Now that certificate is issued, retrieve and save the certificate. 1. Launch Internet Explorer and go to the Certificate Server on your local machine: http://localhost/certsrv
30
Configuration Guide for Directory Sync
2. Click Check on a pending cert.
3. Click on the saved certificate on the screen. 4. Click Download Certificate and save the certificate. Note the location where you save the certificate. Select Base-64 encoded.
Microsoft Active Directory
31
Install the New Certificate
Install the new certificate to IIS. 1. Launch IIS Manager from Start -> All Programs -> Administrative Tools -> IIS Manager. 2. In (local machine), navigate to Web Sites -> Default Web Sites. 3. Right-click on Default Web Sites and select Properties. 4. Go to the Directory Security tab. 5. In the Secure communications box, click Server Certificate… Windows will launch the Web Server Certificate Wizard. 6. Click Next to step through the Welcome screen to go to the Pending Certificate Request screen.
7. Click Process the pending request and install the certificate” and click Next. 8. On the confirmation screen, enter the path to the new certificate and click Next. 9. On the SSL Port screen, specify the port number for SSL, or leave it at the default 443. 10. Click Next twice, then click Finish to return to Default Web Sites Properties.
32
Configuration Guide for Directory Sync
Enable SSL Configure Basic Authentication for Default Web Site and /dsml
There are several web site authentication methods available in Windows IIS. Directory Sync tool uses Basic Authentication over SSL, which is the most common and secure method for HTTP communication. To use Basic Authentication, you must have a user account with rights to log on locally and to have access to necessary files. To select and enable Basic Authentication for the DSML module in IIS: 1. Launch IIS Manager from Start -> All Programs -> Administrative Tools -> IIS Manager. 2. In (local machine), navigate to Web Sites -> Default Web Sites. 3. Click on the Directory Security tab. 4. In the Authentication and access control box, click Edit… 5. Uncheck Enable anonymous access. 6. Check Basic authentication. A dialog will appear to warn you that your user name and password will be sent over the net in clear text. Since the connection will be through SSL, this warning does not apply. Click Yes to continue. 7. In Authenticated access, make sure all other boxes besides Basic Authentication are unchecked. 8. Click OK to close the dialog box. Also, configuration Basic Authentication in the /dsml directory 1. In (local machine), navigate to Web Sites -> Default Web Sites. 2. Click on the Directory Security tab. 3. In the Authentication and access control box, click Edit… 4. Uncheck Enable anonymous access. 5. Check Basic authentication. A dialog will appear to warn you that your user name and password will be sent over the net in clear text. Since the connection will be through SSL, this warning does not apply. Click Yes to continue. 6. In Authenticated access, make sure all other boxes besides Basic Authentication are unchecked. 7. Click OK to close the dialog box.
Microsoft Active Directory
33
Enable SSL
Now that you have configured basic authentication, you can enable SSL for connections to the machine hosting your DSML Server. 1. In the Default Web Sites Properties dialog box, go to the Directory Security tab 2. In the Secure communications box, click Edit. 3. Check the Require secure channel (SSL) box. 4. Check the Require 128-bit encryption box. 5. Click OK to close Secure communications. 6. Click OK again to close Default Web Sites Properties. 7. Restart IIS by right clicking on the root node and select All tasks -> Restart IIS. Once you’ve enabled SSL, your directory server can accept connections from Directory Sync.
Adjust Server Settings You’ll need to take a few extra configuration steps to assure that your installation is smooth and problem-free.
Disable token caching to prevent attacks Enabling Basic Authentication creates a security flaw. It is important to disable token caching to avoid a serious vulnerability on your system.
WARNING:
Windows stores user tokens in a token cache. If you log on using Basic Authentication with an account that has high level of user logon rights, a successful attacker could use the account to gain access to the resources on your computer. The following procedure will configure the token cache to flush all tokens. This procedure involves modifying the Windows Registry using Regedit.exe. Before you edit the registry, make sure you understand how to restore it if a problem occurs: 1. From the Start menu, click Run. 2. In the Open box, type regedit.exe. 3. Find and double-click the following key in the registry: HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\InetInfo\P arameters.
4. From the Edit menu, click Add and choose DWORD Value to add a new registry entry.
34
Configuration Guide for Directory Sync
5. Add the following registry value: Name: UserTokenTTL Type: REG_DWORD Data: 0
6. Quit Registry Editor. 7. Restart IIS.
Disable search entries limit By default, Active Directory will only allow 1000 search entries. If your server has more than this number of returned entries, you will need to override the default 1000 LDAP search size limit in Active Directory. The size limit is kept as a LDAP policy. You can modify the LDAP policies using Ntdsutil.exe tool in the Active Directory server.
1. Log in as an Active Directory admin. 2. In the Support Tools folder on the Windows 2000 installation CD-ROM, launch launch the following program: ntdsutil.exe.
By default, Ntdsutil.exe is installed in the System32 folder. 3. At the Ntdsutil.exe command prompt, type LDAP policies
4. At the LDAP policy command prompt, type connections
Microsoft Active Directory
35
5. At the server connection command prompt, type connect to server ServerName
ServerName is the DNS name of the Active Directory Server. 6. At the server connection command prompt, type q
You will be returned to the previous menu. 7. At the LDAP policy command prompt, type Show Values
8. Verify that MaxPageSize is set to 1000. 9. At the LDAP policy command prompt, type Set MaxPageSize to 15000
10. At the LDAP policy command prompt, type Set MaxResultSetSize to 6000000
11. At the LDAP policy command prompt, type Commit Changes
12. Verify the new settings. Type Show Values
13. Exit the current menu. Type q
14. Quit Ntdsutil.exe. Type q
Your search limit has now been reset.
Collect Information for Directory Sync setup Once you’ve enabled these components, you’ll collect information from your directory server. Directory Sync uses this information to contact your server and import settings. You’ll need to collect the following information:
36
•
Authorized user (name only)
•
Password (case-sensitive)
•
Host Name (no http://)
•
Path (including leading forward slash)
•
Port (no colon, just the number)
Configuration Guide for Directory Sync
•
Server Type (MS Active Directory 2000 or 2003)
•
Base DN (distinguished name)
Troubleshooting If you experience problems with using Directory Sync with Active Directory, check the following steps. Configuration Checklist
1. Is the Common Name for the SSL certificate identical to the hostname entered in the Directory Sync configuration page in the Administration Console? The hostname must be an Fully Qualified Domain Name (FQDN) with a DNS entry. For example, dsml.domain.com is fine, as is dirsync.domain.com or mail.domain.com. The actual FQDN is not important; what is important is that there is an A record which resolves to the machine in question, and that theFQDN chosen matches the SSL certificate's Common Name. 2. Does the account specified for the sync have sufficient authorizations? 3. Have you set the "Email Address Attribute" and the "Alias Attribute" correctly? For an "out of the box" Active Directory, they will be "mail" and "proxyAddresses" respectively. 4. Did you set the Authentication Method on the "dsml" virtual directory correctly? 5. Can you browse to the website https://hostname/dsml? You should be asked to log in, and if you do so, using the credentials used in the Directory Sync configuration page, you should get the error: "Directory Listing Denied. This Virtual Directory does not allow contents to be listed." 6. Did you enter the correct Base DSN? It is not recommended to sync from the top level as this will populate Directory Sync with all your AD objects including Exchange System Objects unless an Org Exclusion Attribute or a User Exclusion Attribute is specified. 7. Have you correctly specified in your Exclusion Attributes any Active Directory objects you do not want to be synced? 8. If you have multiple User OUs to sync, you can do this using a single sync by creating a placeholder OU and moving the User OUs into it, then setting Directory Sync to use a Base DN of the form "OU=placeholder,DC=domain,DC=com". Then ensure the "Search entire subtree" box is checked.
Microsoft Active Directory
37
38
Configuration Guide for Directory Sync
IBM Lotus Domino Directory Server
Chapter 4
Directory Sync with IBM Lotus Domino This document gives instructions on how to install and configure the DSML module for IBM Lotus Directory Server and optionally IBM Tivoli Directory Server, as well as requirements and details on how it works. IBM Lotus Domino Server is a server that provides e-mail, collaboration and custom application services. IBM Lotus Domino often uses IBM Lotus Directory Server or IBM Tivoli Directory Server as an LDAP-based directory that holds organizational information. Directory Sync can connect to these servers and collect user information. Directory Sync uses Directory Services Markup Language (DSML) to query your LDAP directory server for user information. DSML is an international standard that is supported by all major directory server vendors. Some Lotus Domino servers use other directory servers, including Microsoft Active Directory. If you are using a Lotus Domino server with Microsoft Active Directory, see “Directory Sync with Microsoft Active Directory” on page 11 for details on setting up Active Directory for use with Directory Sync. To allow Directory Sync to work with IBM Lotus Directory Server or IBM Tivoli Directory Server, set up an application server and DSML in your environment. These instructions include steps to install the WebSphere Application Server. You may be able to use other application servers, such as Apache Tomcat, but other application servers are unverified and are not described in this document.
How it Works Directory Sync connects to your application server through the Internet securely through an SSL connection. The application server then connects to a DSML server. The DSML server connects directly to a directory server on the same machine to collect user information. If you are not using an IBM Tivoli Directory Server, your DSML server connects to an IBM Lotus Domino directory server on the same machine. This can be your primary directory server, or a mirrored copy of your directory server.
IBM Lotus Domino Directory Server
39
If you are using an IBM Tivoli Directory Server, the DSML server connects to the IBM Tivoli Directory Server on the same machine. The IBM Tivoli directory server collects user information from your IBM Lotus Domino server, and exports it to your DSML server.
Note: It is possible to use another application server, such as Apache Tomcat.
However, this has not been validated. Instructions and support are available only for WebSphere Application Server (WAS).
System Requirements Directory Sync for IBM Lotus Domino Directory Server requires the following components:
40
•
DSML Server: A server machine must be available, and accessible to HTTPS traffic from the Internet.
•
Directory Server: IBM Lotus Domino version 6.5 or 7.0, with IBM Lotus Directory Server version 6.5 or 7.0, or IBM Tivoli Directory Server version 6.0. Your LDAP directory server must be located on the same physical machine as your DSML server. This can be your original directory server or a mirror, but must contain the user lists you wish to import. It is not possible to direct this to another server.
•
Libraries: Several Java libraries are required to support DSML. Instructions for installation are given below.
Configuration Guide for Directory Sync
•
Application Server: Using DSML requires an application server. These instructions describe the use of the Express version of WebSphere Application Server version 5.1. It is possible to use another server, such as Apache Tomcat. However, this has not been validated and instructions are not included.
•
Authorization: Directory Sync requires a username and password of a user with read and execute permissions on your directory server.
•
Base DN: For importing users, you will need to find your Base DN. If you also wish to import Mailing Groups and Aliases, use an empty Base DN and search subdirectories. Mailing Groups and Aliases are located outside the standard Base DN and require special setup.
Tivoli Directory Server These instructions are written with the assumption that you have IBM Tivoli Directory Server available. WebSphere Application Server and IBM Directory Server come bundled with IBM Tivoli Directory Server, and are needed for this installation. Tivoli Directory Server 6.0 can be downloaded on a trial basis from the following link: http://www14.software.ibm.com/webapp/download/ search.jsp?go=y&rs=ldap
Download the full ITDS v6.0 version (which has a file name like itds60-winia32-ismp.zip, for Windows environment) and the latest Service Pack (which has the file name like 6.0.0.1-TIV-ITDS-Win32-IF001.zip). At the time of this writing, the latest Service Pack is 6.0.0-TIV-ITDS-FP0002 (6.0.0.14). Check with your IBM representative regarding licensing rights for IBM DSML and WebSphere Express. These instructions assume you have appropriate licenses for software used. When selecting the destination directory, select a simple directory name (such as C:\IBM) to save your typing because you will need to type this path name many times.
Setup Overview Setting up Directory Sync with Tivoli Directory Server consists of six steps: 1. Enable LDAP support on your DSML Server 2. Install Java libraries 3. Install WebSphere Express 4. Install SOAP into WebSphere Express 5. Confirm WebSphere and SOAP installation
IBM Lotus Domino Directory Server
41
6. Install DSML 7. Collect information for Directory Sync setup Each of these steps is documented in a separate section below.
Enable LDAP support on your DSML Server LDAP service is not enabled by default in a Lotus Domino server. To enable LDAP services on an existing Domino server, load LDAP support and create a server configuration document. Load LDAP support in a Domino Server
1. In the Domino server command prompt, enter the following: load LDAP
2. Open the notes.ini file. Add LDAP to the end of the line starting with “ServerTasks=” and save the file. 3. If you are using a partitioned server, add the text LDAPAddress=[IP Address]
to a new line, where [IP Address] is the IP address for the partition that is running the LDAP server. Create a server configuration document
To make configuration changes to your LDAP server, you will need to create a server configuration document. 1. From the Administrator client, click the Configuration tab, expand the Server section, and click the Configurations icon. 2. Click Add Configuration to create a new configuration document. 3. Check the box marked “Use these settings as the default settings for all servers”. You can only have one default document. 4. Click the LDAP tab to view LDAP configuration settings. The screen should look like the picture below.
42
Configuration Guide for Directory Sync
Install Java libraries Running the DSML server requires downloading and installing several Java libraries. Download libraries and install them on your Domino server. Note: This list includes two different versions of the Apache Xerces library. Be
sure to install both. 1. Apache SOAP v2.3.1 http://www.apache.org/dyn/closer.cgi/ws/soap/ Note: There is an older version of SOAP.jar in WebSphere Express. In a
later step, you will copy the soap.jar file from the Apache SOAP package into your WebSphere library. 2. Java J2SE SDK v1.4.2 Update 10 http://java.sun.com/j2se/1.4.2/install_jdk1_4_2_10-nb41_all.html
3. Apache Xerces v1.4.4 http://archive.apache.org/dist/xml/xerces-j/
4. Apache Xerces v2.7.1 http://archive.apache.org/dist/xml/xerces-j/ Note: When unpacking (unzipping) Xerces v2.7.1, rename xml-apis.jar to XMLParserAPIs.jar for later use.When unpacking (unzipping) Xerces v2.7.1, rename xml-apis.jar to XMLParserAPIs.jar for later use.
IBM Lotus Domino Directory Server
43
Install WebSphere Express These steps describe installing WebSphere Application Server, which is bundled with IBM Tivoli Directory Server. If you do not already have WebSphere Application Server installed on a publicly accessible machine, follow these steps to install it. If you already have WebSphere Application Server installed, skip to the next step.
Install WebSphere Application Server If you do not have WebSphere Application Server installed, run the install process now. 1. In the IBM Tivoli Installation program, select “Web Administration Tools 6.0” and “embedded version of WebSphere Application Server – Express”
2. For your destination directory, enter C:\IBM. You will be using this directory in future steps.
Copy Libraries Before you can set up WebSphere Application Server, you need to copy a few files into appropriate directories: 1. WebSphere has an older version of soap.jar than the version you downloaded. Copy the soap.jar file from the Apache SOAP package you downloaded into C:\IBM\LDAP\V6.0\appsrv\lib.
44
Configuration Guide for Directory Sync
2. Copy the soap.war file from the directory where you’ve unpacked the Apache SOAP v2.3.1 package to the C:\IBM\LDAP\V6.0\appsrv\installableApps directory.
Configure WebSphere Express Open a command line session and go to the appsrv\bin directory under WebSphere. 1. Start WebSphere Application Server (WAS) by using the following command from a command prompt. startserver server1
If you are using a server than other than server1, enter that server name instead. You can find the server name in the WAS log files in the logs directory under WebSphere Application Server.
2. In a web browser, go to http://schemas.xmlsoap.org/soap/envelope/
Copy all content into a new file named C:\IBM\LDAP\V6.0\appsrv\properties\schemas\soap-env.xsd
3. In a web browser, go to the address http://www.oasis-open.org/committees/dsml/docs/DSMLv2.xsd
Copy all content into a new file named C:\IBM\LDAP\V6.0\appsrv\properties\schemas\DSMLv2.xsd
IBM Lotus Domino Directory Server
45
4. Copy the file server.xml to server.xml.original as a backup. The server.xml file is in the directory: C:\IBM\LDAP\V6.0\appsrv\config\cells\DefaultNode\nodes\DefaultN ode\servers\server1
As in Step 1, if you are using a server than other than server1, enter that server name instead. You can find the server name in the WAS log files in the logs directory under WebSphere Application Server. 5. Open “server.xml” in a text editor and add the following: xmlns:dsml="http://www.ibm.com/websphere/appserver/schemas/5.0/ DSMLv2.xmi" xmlns:SOAP-ENV="http://www.ibm.com/websphere/ appserver/schemas/5.0/soap-env.xmi":
This should be as the second to last entry, immediately before the following line: xmlns:pmiservice="http://www.ibm.com/websphere/appserver/ schemas/5.0/pmiservice.xmi" >
6. Create a new directory: C:\IBM\LDAP\V6.0\appsrv\lib\app
Search for the following files and copy them into the directory you created: activation.jar (Modified 3/30/2005 11:33AM, 54,368 bytes) auibase.jar (Modified 1/31/2005 05:56 AM, 346,819 bytes) dsml.jar (Modified 04/05/2005 01:28PM, 197,952 bytes) ibmjsseprovider.jar (Modified 03/30/2005 12:33AM, 320,513 bytes) IBMLDAPJavaBer.jar (Modified 04/05/2005 01:05PM, 41,398 bytes) mail.jar (Modified 03/30/2005 11:33AM, 280,984 bytes) regex4j.jar (Modified 04/05/2005 12:42PM, 79,466 bytes) soap.jar (Modified 06/10/2002 03:00AM, 232,498 bytes) xerces.jar (Modified 11/15/2001 03:51PM, 1,812,019 bytes) xercesImpl.jar (Modified 07/26/2005 05:10PM, 1,203,860 bytes) xmlParserAPIs.jar (Modified 7/26/2005 05:10PM, 194,205 bytes)
7. Restart WebSphere Application Server (WAS) by using the following commands from a command prompt. stopserver server1 startserver server1
If you are using a server than other than server1, enter that server name instead.
Install SOAP into WebSphere Application Server Using DSML on WebSphere Application Server requires that SOAP is installed and enabled. Copy the appropriate .jar and .war files, then run a batch command to install the SOAP. 1. Copy the file soap.jar from the Apache SOAP v2.3.1 package into C:\IBM\LDAP\V6.0\appsrv\lib\soap.jar.
46
Configuration Guide for Directory Sync
2. Copy the file soap.war from the Apache SOAP v2.3.1 package into C:\IBM\LDAP\V6.0\appsrv\installableApps\soap.war. 3. To install SOAP into WebSphere, enter the following in a command line in the appsrv\bin directory: C:\IBM\LDAP\V6.0\appsrv\bin\wsadmin.bat -conntype NONE -c "$AdminApp install {C:\IBM\LDAP\V6.0\appsrv\installableApps\soap.war} {-configroot \"C:\IBM\LDAP\V6.0\appsrv\config\" -node DefaultNode usedefaultbindings -nodeployejb -appname soap.war -contextroot \"soap\"}" Note: Because this is a long command, and exact syntax is important, you
may wish to copy it into a batch file and run that batch file. 4. Restart WebSphere Application Server (WAS) by using the following commands from a command prompt. stopserver server1 startserver server1
If you are using a server than other than server1, enter that server name instead.
Confirm WebSphere and SOAP installation Confirm that your installation of WebSphere Application Server and SOAP was successful.
Read the SystemOut.log file The SystemOut.log file contains information about your WebSphere installation. You can find it in the C:\IBM\LDAP\V6.0\appsrv\lib\app directory. Search the log for the word SOAP. You should see a line with the following format: [3/13/06 15:17:40:288 PST] 731e794c JMXSoapAdapte A ADMC0013I: SOAP connector available at port 12103
If you cannot find a line indicating that a SOAP connector is available, there is a problem with your SOAP installation. For troubleshooting steps, see “Troubleshooting” on page 55. Also, check the port number for HttpTransport. You should see a line with the following format: [3/13/06 15:17:45:928 PST] 731e794c HttpTransport A SRVE0171I: Transport http is listening on port 12,100.
This indicates that the SOAP HTTP server is running at port 12100. You will use the port number for the browser verification page.
IBM Lotus Domino Directory Server
47
Use the browser verification page You can also use a web browser to test the WebSphere application. 1. Find the port number of the SOAP connector in the SystemOut.log file. 2. In a web browser, navigate to: http://localhost:[port number]/soap/servlet/rpcrouter
Where [port number] is the port number from the SystemOut.log file. 3. You should see a page showing the SOAP RPC router. You should see a page titled “SOAP RPC Router.” If this page is not available, check your SOAP and WebSphere settings.
This indicates a successful SOAP installation. Ignore the “Sorry, I don’t speak via HTTP GET” error message. If there is a problem with SOAP which requires you to uninstall and start over, or if you need to uninstall the SOAP component, use the following command from a command prompt: C:\IBM\LDAP\V6.0\appsrv\bin\wsadmin.bat -conntype NONE -c "$AdminApp uninstall soap.war"
Install DSML To install DSML, unpack DSML.zip, modify the deployment descriptor, configure your CLASSPATH, install IBM DSML into SOAP, and verify the installation. Details are found below
48
Configuration Guide for Directory Sync
Unpack DSML.zip 1. Find the DSML.zip file in C:\IBM\LDAP\V6.0\idstools. 2. Unzip the DSML.zip into C:\DSML.
Modify IBM DSML Deployment Descriptor 1. Modify the file C:\DSML\deployDSMLSoap.xml. The original deployDSMLSoap.xml file in C:\DSML looks like this:
org.apache.soap.server.DOMFaultListener
2. Cut and paste the following text into the file to replace the existing file:
org.apache.soap.server.DOMFaultListener
IBM Lotus Domino Directory Server
49
xml2JavaClassName="org.apache.soap.encoding.soapenc.BeanSerializer "/>
3. Save your changes.
Configure CLASSPATH WARNING: These Java name spaces need to be before other Java instances in the CLASSPATH, or the wrong version will be used. CLASSPATH is used in many Java programs, and problems with an incorrect CLASSPATH can be very difficult to debug. The exact settings for your CLASSPATH will depend on what other Java programs you are using.
Be sure your CLASSPATH includes the following files, in the order given: 1. Current directory 2. Xerces.jar (Apache Xerces 1.4.4) 3. Jar files for IBM DSML 4. activation.jar and mail.jar (can be found in C:\IBM\LDAP\V6.0\appsrv\java\jre\lib\ext) 5. XercesImpl.jar and XMLParserAPIs.jar (Apache Xerces 2.7.1) 6. soap.jar (Apache Soap v2.3.1) 7. Ibmjsseeprovider.jar in C:\IBM\LDAP\V6.0\appsrv\java\jre\lib) For example, here is a sample CLASSPATH for Windows environment: CLASSPATH=.;C:\Xerces-J-bin.1.4.4\xerces1_4_4\xerces.jar;C:\DSML\jars\auibase.jar;C:\DSML\jars\dsml.jar;C: \DSML\jars\regex4j.jar;C:\DSML\jars\IBMLDAPJavaBer.jar;C:\DSML;C:\ IBM\LDAP\V6.0\appsrv\lib\j2ee.jar;C:\IBM\LDAP\V6.0\appsrv\lib\acti vation.jar;C:\IBM\LDAP\V6.0\appsrv\lib\mail.jar;C:\IBM\LDAP\V6.0\a ppsrv\lib\XercesImpl.jar;C:\IBM\LDAP\V6.0\appsrv\lib\XMLParserAPIs .jar;C:\IBM\LDAP\V6.0\config\csa_runtime\swing11spinner_Runtime.ja r;C:\IBM\LDAP\V6.0\appsrv\lib\soap.jar;C:\IBM\LDAP\V6.0\appsrv\ins talledApps\DefaultNode\soap.war.ear\soap.war\WEBINF\classes;C:\IBM\LDAP\V6.0\jre\lib\ibmjsseprovider.jar
Install IBM DSML into SOAP In a command line in the C:\DSML directory, run the following command: install.bat C:\IBM\LDAP\V6.0\appsrv\installedApps\DefaultNode\soap.war.ear\soa p.war http://localhost:12100/soap/servlet/rpcrouter
50
Configuration Guide for Directory Sync
Note: If you are using a different URL for the SOAP server, specify the correct
URL for the SOAP server. The URL can be found in the file C:\IBM\LDAP\V6.0\appsrv\lib\app\SystemOut.log. For information about
reading this file, see “Confirm WebSphere and SOAP installation” on page 47.
Verify DSML installation Run the following command from C:\DSML directory to verify DSML installation: java com.ibm.ldap.dsmlClient.DsmlSoapClient "cn=Bob Level" "rulost2" -i "batchrequest.dsml" -o "result.xml" -l "log.out" -S http://localhost:12100/soap/servlet/messagerouter Note: If you are using a different URL for the SOAP server, specify the correct
URL for the SOAP server. The URL can be found in the file C:\IBM\LDAP\V6.0\appsrv\lib\app\SystemOut.log. For information about
reading this file, see “Confirm WebSphere and SOAP installation” on page 47.
Collect information for Directory Sync setup After you have set up SOAP and DSML, collect DSML information for Directory Sync. This information is used in the DSML files and in Directory Sync configuration. You will also use this information to create the batchrequest.dsml file, which is detailed in the next section.
Verify LDAP Information You will need an LDAP browser to verify the parameters to be used with DSML. One such browser you can use is Softerra LDAP Administrator. You can download Softerra LDAP Administrator from the following URL: http://www.ldapbrowser.com
IBM Lotus Domino Directory Server
51
Use the LDAP browser to collect the following information: •
User name and password to connect to your LDAP server
•
The proper spelling of the base DN from which to start the query
You will also need to collect the following information for Directory Sync configuration: •
Authorized user (name only)
•
Password (case-sensitive)
•
Host Name (no http://)
•
Path (including leading forward slash)
•
Port (no colon, just the number)
•
Server Type (IBM Lotus Notes)
•
Base DN (distinguished name)
Create batchrequest.dsml file To complete setup, create a batchrequest.dsml file. The batchrequest.dsml file is used to connect to the LDAP server. Create batchrequest.dsml.
1. Using an LDAP browser, find the Base DN you will use for your LDAP server.
52
Configuration Guide for Directory Sync
2. With a text editor, create a file with the following content and name it “batchrequest.dsml” and save it in your C:\DSML directory. Substitute
with the base DN you found in the LDAP browser.
person
IBM Lotus Domino Directory Server
53
3. Run the following command from C:\DSML directory, substitute “cn=Domino Admin” and “secret” with the proper user name and password that you were able to connect with the LDAP browser. Use double-quotes around the user name and password. Make sure you specify the correct URL for the SOAP server (see the steps to verify the SOAP installation). C:\DSML>java com.ibm.ldap.dsmlClient.DsmlSoapClient "cn=Domino Admin" "secret" -i "batchrequest.dsml" -o "result.xml" -l "log.out" -S http://localhost:12100/soap/servlet/messagerouter
If the test was successful, the query result will be created in the “result.xml” file. The file should have the following format:
[email protected] [email protected] [email protected]
If you do not see these results, check your DSML and LDAP settings.
Configure Directory Sync in the Administration Console After successfully verified DSML installation, use the parameters that you have entered in the verification step to configure Directory Sync in the Administration Console. Be sure to use fully qualified DNS name for the host name. For more information about setting up Directory Sync in the Administration Console, see the Email Protection Service Administration Guide.
Setup Checklist To confirm your configuration for compatibility with IBM Lotus Domino servers, be sure you have completed the following steps: •
54
Load LDAP and add LDAP to server tasks
Configuration Guide for Directory Sync
•
Create a server configuration document
•
Download Apache Xerces v1.4.4, Apache SOAP v2.3.1, Java J2SE SDK v1.4.2 Update 10
•
Install these libraries on your DSML Server
•
Download Apache Xerces v2.7.1 and rename xml-apis.jar to XMLParserAPIs.jar
•
Install this library on your DSML Server
•
Install WebSphere Application Server on your DSML Server
•
Copy soap.jar and soap.war files into your installation
•
Create DSMLv2.xsd and place the file in your schemas directory
•
Create soap-env.xsd and place the file in your schemas directory
•
Edit the server.xml file
•
Place .jar files in your app directory
•
Install SOAP into WebSphere Application Server
•
Stop and restart WebSphere Application Server
•
Unpack DSML.zip
•
Modify deployDSMLSoap.xml
•
Install DSML into SOAP on WebSphere server
•
Configure CLASSPATH on your DSML Server
•
Collect LDAP information from your directory server
•
Create batchrequest.dsml file
Troubleshooting If an error occurs when you attempt to verify the installation, check the error message against the error messages below to find the source of the problem. Exception in thread “main” java.lang.NoClassDefFoundError: com/ibm/ldap/ dsmlClient/DsmlSoapClient
Cause: .jar files for IBM DSML are not in your CLASSPATH. Refer to section 2.9 for information about setting your CLASSPATH [SOAPException: faultCode=SOAP-ENV:Client; msg=Error opening socket: java.net.ConnectException: Connection refused: connect; targetException=java.lang.IllegalArgumentException: Error opening socket: java.net.ConnectException: Connection refused: connect]
Cause: WebSphere Express is not running. Refer to section 2.4 and section 2.7 to verify the WebSphere is running and SOAP is installed.
IBM Lotus Domino Directory Server
55
[SOAPException: faultCode=SOAP-ENV:Server; msg=Exception while handling service request: org/apache/soap/Envelope]
Cause: WebSphere Class Loader can not find the SOAP libraries. Refer to section 2.6 for information about WebSphere Class Loader. [SOAPException: faultCode=SOAP-ENV:Server; msg=service 'urn:oasis:names:tc:DSML:2:0:core' unknown
Cause: IBM DSML was not installed properly. Refer to section 2.10 for information about installing IBM DSML. Error Msg: InvalidRegex: Pattern value '((([0-2](\.[0-9]+)+)|([a-zA-Z]+([a-zA-Z09]|[-])*))(;([a-zA-Z0-9]|[-])+)*)' is not a valid regular expression. The reported error was: ''-' is an invalid character range. Write '\-'.'.
Cause: Xerces.jar (Apache Xerces 1.4.4) is not in your CLASSPATH or the reference to xerces.jar in your CLASSPATH is incorrect. Refer to section 2.9 for information about configuring CLASSPATH.
56
Configuration Guide for Directory Sync
Sun ONE Directory Server
Chapter 5
Directory Sync with Sun ONE DS The Sun ONE Directory Server 5.2 product includes a Directory Server, an Administration Server to manage multiple directories, and Sun ONE Server Console to manage both servers through a graphical interface. Because Directory Sync extracts company information over the Internet, it is vital that all connections are secure. Directory Sync always connects to your directory server using SSL. DSML (Directory Services Markup Language) allows an HTTP session to use SOAP to access the directory server. Although not enabled by default, Sun ONE Directory Server 5.2 includes support for DSML interface. Directory Sync Tool acts as a client sending DSML requests to the directory server to query for the users information. You can perform most Directory Server administrative tasks from the Directory Server console. Some require command-line utilities, or editing configuration files manually. You must restart your directory server for the new settings to take effect. Most commands are run through the directory server console. To start the console, locate where your Sun ONE server is installed and run the following command with root privileges: # ./startconsole &
To set up a Sun ONE Directory Server to work with Directory Sync, you’ll need to complete four steps: •
Enable SSL
•
Install DSML
•
Configure DSML Identity Mapping
•
Collect information for Directory Sync setup
Sun ONE Directory Server
57
Enable SSL Secure Sockets Layer (SSL) provides encrypted communications between a client and server. Directory Sync uses SSL encryption and basic authentication to guarantee confidentiality and data integrity. Basic authentication requires a user name and password to connect to a directory server. SSL makes sure that transmitted data is encrypted and protected. To enable SSL in the Sun ONE Directory Server, you will need to obtain and install a certificate, then activate and configure SSL on your directory server. You can obtain a server certificate from a Certificate Authority such as Verisign or Entrust. Sun provides a a tool (certutil tool) to manage certificates in the Sun ONE Directory Server Resource Kit (DSRK). You can download the DSRK at: http://www.sun.com/download/products.xml?id=3f74a0db
To set your Sun ONE Directory Server up to accept connections from Directory Sync, use SSL with simple authentication. This uses a bind DN and password to authenticate a user, and SSL to ensure confidential data transmissions. Enabling SSL in the Sun ONE Directory Server consists of two parts: obtaining and installing the certificate, and activating SSL. These steps are summarized here, and detailed in later sections. Obtain and install a certificate
1. Create a certificate database. 2. Generate a certificate request. 3. Send the certificate request 4. Install your new certificate. 5. Set your directory server to trust your Certificate Authority. Activate SSL
1. Activate SSL in your directory server 2. Configure SSL, including the secure ports for LDAP and DSML operations.
Obtain and Install Server Certificates This section describes the process of creating a certificate database, obtaining and installing a certificate for use with your Directory Server, and configuring Directory Server to trust the Certificate Authority's (CA) certificate. Directory Server will accept any SSL-compliant Certificate Authority, including self-signed certificates.
58
Configuration Guide for Directory Sync
The first time you configure SSL on your server, you must set the password for your security device. Be sure to keep this password, as you will need it later. If you are not using an external hardware security device, the internal security device is a certificate and key database stored in the following files: ServerRoot/alias/slapd-serverID-cert7.db ServerRoot/alias/slapd-serverID-key3.db
ServerRoot is the root directory of your directory server. ServerID is the ID number of your server. Create a certificate database
If you do not already have a certificate request set up, you will need to create one. The directory server will create the certificate database files automatically the first time you invoke the certificate manager dialog. You can also create the certificate database manually. This step uses the command-line interface. 1. On the server host machine, create a certificate database with the following command: certutil -N -d ServerRoot/alias -P slapd-LCserverID-
LCserverID is your server name in all lower-case letters. ServerRoot is your server root. 2. The tool will prompt you for a password to protect the keys of the certificates. Keep track of this password. You will use it in later steps. Generate a certificate request
Generate a PKCS #10 certificate request in PEM format. PEM is the Privacy Enhanced Mail format used to represent a base64-encoded certificate request in US-ASCII characters. 1. Log into the directory server console. Start the console from the directory where your Sun ONE Directory Server is installed. You will need root privileges. # ./startconsole &
2. On the top-level Tasks tab of the Directory Server console, click Manage Certificates. The Manage Certificates dialog is displayed. 3. Go to the Server Certs tab. Click Request. The Certificate Request Wizard is displayed. 4. Click Next to continue. 5. Enter the following Requestor Information in the blank text fields:
Sun ONE Directory Server
59
Text Field
Value
Server Name
Enter the fully qualified hostname of the Directory Server as it is used in DNS lookups, for example, east.example.com.
Organization
Enter the legal name of your company or institution. Most CAs require you to verify this information with legal documents such as a copy of a business license.
Organizational Unity
(Optional) Enter a descriptive name for your division or business unit within your company.
Locality
(Optional) Enter your company's city name.
State or Province
Enter the full name of your company's state or province, with no abbreviations.
Country
Select the two-character abbreviation for your country's name in ISO format. The country code for the United States is US.
6. Click Next to continue. 7. Enter the password of your security device, then click Next. This is the password you set when you created the database. 8. Select Save to File to save the certificate request information. You will send this information to the Certificate Authority. 9. Click Done to dismiss the Certificate Request Wizard. Send the certificate request
Contact a Certificate Authority (CA) to process your certificate request and generate a certificate. Because there are many different Certificate Authorities, you’ll need to contact your CA for instructions on how to do this. Transmit the request from the previous section to your Certificate Authority, according to the CA procedures. You may be asked to send the certificate request in an email, or you may be able to enter the request through the CA's website. Once you have sent your request, you must wait for the CA to respond with your certificate. Response time for your request varies. For example, if your CA is internal to your company, it may only take a day or two to respond to your request. If your selected CA is external to your company, it could take several weeks to respond to your request.
60
Configuration Guide for Directory Sync
When the CA sends a response, save the information in a text file. Back up the certificate data in a safe location, so you can reinstall the certificate using your backup file if needed. Install your new certificate
When you receive your server certificate from the CA, you are ready to install it in your server's certificate database. 1. Log into the directory server console. Start the console from the directory where your Sun ONE Directory Server is installed. You will need root privileges. # ./startconsole &
2. On the top-level Tasks tab of the Directory Server console, click the Manage Certificates button. Alternatively, with the Tasks tab showing, select the Manage Certificates item from the Console->Security menu. The Manage Certificates window is displayed. 3. Select the Server Certs tab, and click Install. The Certificate Install Wizard is displayed. 4. Choose one of the following options for the certificate location: In this file. Enter the absolute path to the certificate in this field. In the following encoded text block. Copy the text from the Certificate Authority or from the text file you created and paste it in this field. For example: 5. Click Next to continue. 6. Verify that the certificate information displayed is correct, then click Next. 7. Specify a name for the certificate, then click Next. This is the name that will appear in the table of certificates. 8. Verify the certificate by providing the password you added when creating the certificate database. Your new certificate appears in the list on the Server Certs tab. Your server is now ready for SSL activation. Set your Directory Server to trust the Certificate Authority
Once you have the CA certificate, you can use the Certificate Install Wizard to configure the Directory Server to trust the Certificate Authority. 1. Log into the directory server console. Start the console from the directory where your Sun ONE Directory Server is installed. You will need root privileges. # ./startconsole &
Sun ONE Directory Server
61
2. On the top-level Tasks tab of the Directory Server console, click the Manage Certificates button. The Manage Certificates window is displayed. 3. Select the CA Certs tab, and click Install. The Certificate Install Wizard is displayed. 4. If you saved the CA's certificate to a file, enter the path in the field provided. If you received the CA's certificate via email, copy and paste the certificate including the headers into the text field provided. Click Next. 5. Verify that the certificate information displayed is correct for your Certificate Authority, then click Next. 6. Specify a name for the certificate, then click Next. 7. Set the purpose of trusting this CA to Accepting connections from clients (Client Authentication). 8. Click Done to exit the wizard.
Activate SSL Once you have installed your server certificate and trusted the CA's certificate, you are ready to activate SSL. 1. Log into the directory server console. Start the console from the directory where your Sun ONE Directory Server is installed. You will need root privileges. # ./startconsole &
2. On the top-level Configuration tab of the Directory Server console, select the root node with the server name, and then select the Encryption tab in the right-hand panel. The tab displays the current server encryption settings. 3. Check Enable SSL for this Server. 4. Check Use this Cipher Family. 5. Select your certificate from the drop-down menu. 6. Click Cipher Settings and select the RC4 128-bit cypher. 7. Allow client authentication. This is the default setting. 8. Click Save. 9. Restart the Directory Server.
62
Configuration Guide for Directory Sync
Install DSML Enable DSML through the Directory Server console. 1. Log into the directory server console. Start the console from the directory where your Sun ONE Directory Server is installed. You will need root privileges. # ./startconsole
2. On the top-level Configuration tab of the Directory Server console, select the root node in the configuration tree, and select the Network tab in the righthand panel.
3. Check Enable DSML. 4. Select Only secure port. If this option is not available, you need to activate and enable SSL. 5. Enter the port number for SSL. The default SSL port is 443. If you decide to use a port other than 443, write the port number down so you can refer to it later. Note that unlike LDAP queries, DSML queries use port 443, and an HTML connection. 6. Enter the full relative URL. Set the path name to “/dsml”. The full relative URL includes the path name, combined with the host and the port number. 7. Click Save. 8. Restart the directory server.
Sun ONE Directory Server
63
Configuring Basic Authentication 1. Log into the directory server console. Start the console from the directory where your Sun ONE Directory Server is installed. You will need root privileges. # ./startconsole
2. On the top-level Configuration tab of the Directory Server console, select the root node in the configuration tree, and select the Encryption tab in the righthand panel.
3. Near the bottom of the right-hand panel, in the DSML Client Authentication drop-down menu, select HTTP Basic (use authentication in HTTP header). 4. Click Save. 5. Restart the directory.
Configure DSML Identity Mapping After you’ve installed DSML, set up Identity Mapping. In DSML, the directory server uses a mechanism called identity mapping to determine the bind DN from the HTTP Authentication header.Rather, you must tell the directory server how to map the user name in the Authentication header (such as “testuser”) to the bind DN (such as “cn=Directory Server”).
64
Configuration Guide for Directory Sync
Note: You can not use cn=Directory Server as the user name in the HTTP
Authentication header. To set up DSML Identity Mapping: 1. Stop the directory server 2. Using a text editor, open the dse.ldif configuration file. This configuration file is found in the same directory as the directory server. 3. Change the following settings in the file: Variable
Value
dsSearchBaseDN
The base DN where the bind DN can be found. Normally, this base DN would be the suffix you defined when installing the directory. For example: ou=people,dc=company,dc=com
dsSearchFilter
(uid=${Authorization})
4. Enter the following new settings: Variable
Value
dsMatching-pattern dsMatching-regexp
${Authorization}
A regular expression for the basic authentication user name. For example: ^username$
dsMappedDN
The base DN for the username. For example: cn=Directory Manager
You will need to add this section to the configuration file. This tells the directory server that, for basic authorization, the username specified will map to the specified DN. 5. Save the configuration file. 6. Restart the directory server.
Sun ONE Directory Server
65
Collect Information for Directory Sync setup Once you’ve enabled all components, you’ll collect information from your directory server. Directory Sync uses this information to contact your server and import settings. You’ll need to collect the following information:
66
•
Authorized user (name only)
•
Password (case-sensitive)
•
Host Name (no http://)
•
Path (including leading forward slash)
•
Port (no colon, just the number)
•
Server Type (Sun ONE Directory Server)
•
Base DN (distinguished name)
Configuration Guide for Directory Sync
