Introduction to TAM E-SSO dependencies
TAM E-SSO mandates the use of a database for storage of product data, including users' wallets and system configuration. The TAM E-SSO IMS server installation media embeds a version of Microsoft SQL Server Express (SQL2K5 Express) for ease of installation. Expect this to change in the future to accomodate IBM DB2 Express. In addition to this embedded database, TAM E-SSO v8 supports the use of IBM DB2 v9.5 and Oracle 9i databases. Many IBM customers' services teams want to leverage existing IBM software deployments to maximise re-use and minimise cost. Therefore, this article focuses on the use of DB2 as the database for TAM E-SSO.
TAM E-SSO also relies on an existing (or new) identity store for management of user data. TAM E-SSO refers to these user repositories as enterprise directories. Since TAM E-SSO is typically deployed within an intranet environment, many customers opt to leverage existing Active Directory deployments for TAM E-SSO. However, this does not suit all customer deployments, so TAM E-SSO provides support for LDAP-based products as enterprise directories. TAM E-SSO v8 supports IBM Tivoli Directory Server (ITDS) 6.1+, SunOne directory 5.1+, Novell eDirectory 8.6+ and Sun Java Directory 5.2+ as LDAP-based enterprise directories. This article outlines how to configure TAM E-SSO to use IBM Tivoli Directory Server (ITDS).
The operating architecture
In order to simplify the outline, this article assumes the simple deployment illustrated in Figure 1. This deployment best represents a single server TAM E-SSO IMS server installation connecting to an enterprise ITDS server.
Figure 1: TAM E-SSO v8 conceptual architecture
Although this environment is simplistic, scaling the components for higher availability should be transparent to the product configuration outlined in this article.
If the reader's intention is to follow the configuration steps outlined within this article, a number of pre-requisite tasks should be performed.
- ITDS v6.1 must be installed and configured on the ITDS server machine.
- TAM E-SSO v8 IMS server installation images must be available on the IMS server.
- DB2 9.5 must be installed on the IMS server.
- TAM E-SSO AccessAgent software needs to be copied onto the ITDS server.
- The servers will need to communicate over TCP/IP. Add the hostname to the %SystemRoot%\System32\drivers\etc\hosts file, so that server names can be used rather than IP addresses. This makes the configuration more portable.
Configuring TAM E-SSO to use DB2
DB2 should be installed and configured in accordance with the installation instructions on page 56 of the TAM E-SSO Deployment Guide. These instructions worked well for the installation used in this article's development.
After DB2 is configured, IMS server must be installed. Whilst performing the install, select the custom installation option, and point the installation at the DB2 server setup on the IMS server. One point to note is that when performing the IMS server installation, the DB2 database table setup seems to take a long time. This is normal, be patient during this step. If you are concerned about the time it is taking, monitor the IMS installation log at c:\TAM_E-SSO_IMS_installer.log When installed successfully, the tomcat stdout.log file, located as below, is a good reference for determining system state.
Figure 2: Tomcat file system error log
Note that no ITDS configuration is performed at setup time.
When the setup is complete, the IMS Web-based configuration utility starts. When the configuration utility loads, the domain configuration page is displayed.
Configuring TAM E-SSO to use ITDS
The ITDS instance now needs to be setup with the objects required for users registering through the TAM E-SSO AccessAgent. When this is done, IMS can be configured with the ITDS as the enterprise directory.
Setting up ITDS with test users
On the ITDS machine, the first step is to create the suffix for storing users and groups, for example, o=ibm,c=au. In the development of this article, the following LDIF was loaded into the ITDS server. This LDIF includes a number of test users.
Example LDIF for creating the LDAP objects
dn: o=ibm,c=au objectclass: organization o: ibm dn: cn=chrish,o=ibm,c=au objectclass: inetorgperson userpassword: passw0rd cn: chrish sn: hockings dn: cn=root,o=ibm,c=au objectclass: inetorgperson userpassword: passw0rd cn: root sn: root
You might want to grant the cn=root,o=ibm,c=au user the ability to search, add, delete and modify entries within the directory, but by default the user can search the repository, which is all that is required for TAM E-SSO. The next step is to configure the ITDS as the enterprise directory within the IMS.
Configuring the IMS to use ITDS
It is now time to setup the IMS to use the ITDS server as the identity and authentication store. Start the IMS configuration utility. Note that the IMS configuration utility starts at the Add a domain option, which is used for Active Directory domain configuration. This is a little confusing, because domain creation is not required for configuring other enterprise directories, such as ITDS.
On the IMS Configuration Utility landing page, select Enterprise Directories in the left column. On the right side, select Add Directory, as shown in Figure 3.
Note that after IMS installation, the AccessAnywhereEnterpriseDirectory is configured, allowing any user to register without validating credentials. Hence, if there is any attempt to create an IMS administrator prior to this point, it will accept any username/password combination. It is never checked against a directory.
Figure 3: Add enterprise directory
The next step is to add a name and description for the new enterprise directory, as shown in Figure 4.
Figure 4: IMS add enterprise directory
Make sure that Include this directory in TAM E-SSO user validation is selected. When this is done, this directory becomes the authentication service for registering users through AccessAgent.
Now select the Add button, and select the Generic LDAP connector, as shown in Figure 5.
Figure 5: IMS add LDAP details
The ITDS server information must now be entered in the screen shown in Figure 6.
Figure 6: IMS add standard LDAP configuration
Open the Advanced configuration keys twisty and configure ITDS details. SSL should not be configured at this point. The instructions for setting SSL up are provided later in this article. Note that the full class name, that is, com.sun.jndi.ldap.LdapCtxFactory, is not shown in the diagram below.
Figure 7: IMS add advanced LDAP configuration
The configuration can now be tested, by selecting the Save and test button. The result is a success message being displayed at the top of this configuration page. If an error appears, check the details entered. Consult the IMS stdout.log file if the problem cannot be determined from the configuration information. The Troubleshooting section below shows techniques for resoving issues encountered.
Provisioning your IMS administrator
The next step is to provision an IMS administrator, in this case, the cn=root,o=ibm,c=au account. On the IMS configuration utility Web page, select the Create an IMS Administrator link. Now enter root/passw0rd and complete the task.
Having configured an IMS administrator, that user can now login to the AccessAdmin to configure IMS session behaviour. Access the URL for AccessAdmin through the TAM E-SSO start menu folder. When prompted, authenticate using the IMS administrator, root/passw0rd. If the search user's option is now selected in AccessAdmin, the registered users will be displayed. Upon selecting a user, the enterprise directory that user was registered with can be determined. Check that the root user has an ims_ldap\ as its prefix. This provides confidence that ITDS enterprise directory is configured correctly.
Configuring the IMS server session behaviour through AccessAdmin
The next step is to configure the IMS server for connections from the AccessAgent instances. Select the Setup assistant on the left side menu of the AccessAdmin Web application. The following page is displayed. Note that the Begin button appears on the lower right side of the page.
Figure 8: Setup IMS user sessions
The system can now be configured in accordance with the requirements for user session management. This article simply enables self service using a shared desktop. Complete the configuration according to the specific requirements.
The following selections have been made for this article:
- Enable self-service options
- Support shared workstations
- Use a shared desktop
- Continue to select the defaults for all other options
Successful user registration
The next step is to install the AccessAgent on the ITDS server instance. Perform the installation in accordance with the product documentation. When installed, AccessAgent will ask for the IMS server location. Use the hostname of the IMS server in the environment. The system will then reboot.
When the system reboots, instead of the standard Windows Authentication window, the TAM E-SSO GINA is presented. By selecting the Go to Windows Logon option and authenticating using Administrator, the Windows desktop is displayed. Before proceeding, check that the ITDS server started successfully (through Microsoft services). Now, right click on the AccessAgent icon on the toolbar, as shown below.
Figure 9: AccessAgent Taskbar Options
Select the Sign up link. Enter the text chrish/passw0rd. The AccessAgent then performs first-time registration, asking the user to select two Q&A responses and to reset their wallet password. Note that this does not change the Enterprise Directory password.
When completed, the AccessAgent changes to a bright red color (not flashing). This signals that the user has registered and is now logged into their new wallet.
Unsuccessful user registration
Now, right click on the AccessAgent taskbar icon and select Logoff AccessAgent. Now try to register a user that does not exist within the ITDS. Proceed through the self-registration functions. When the final submit is performed, the AccessAgent displays the following message.
Figure 10: AccessAgent Failed Sign up
This then proves that the ITDS instance is authenticating users during registration.
Setting up SSL for the enterprise directory
As with any SSL configuration exercise, there is a client-side SSL component and a server-side SSL component to configure. The server in this case is the ITDS server, with TAM E-SSO IMS acting as the client. This section outlines the configuration steps required for both the server and the client. Before attempting to configure SSL, make sure the IMS server and ITDS server have the same timezone and time settings.
Setting up SSL for ITDS
The first step is to configure the ITDS server with a self-signed certificate to use for SSL connections. Self-signed certificates are a convenient way to configure a non-production server to perform SSL. Of course, production servers should use trusted certificate authorities to create certificates.
On the ITDS server machine, open a command prompt and issue the following commands.
Commands for setting up SSL with ITDS
C:\Program Files\IBM\GSK7\bin>gsk7cmd -keydb -create -db c:\serverkey -pw passw0rd -type cms -stash C:\Program Files\IBM\GSK7\bin>gsk7cmd -cert -create -db c:\serverkey.kdb -pw passw0rd -label testlabel -dn "CN='tam6',o=ibm,c=au -default_cert yes -expire 999 C:\Program Files\IBM\GSK7\bin>gsk7cmd -cert -list -db c:\serverkey.kdb -pw passw0rd Certificates in database: c:\serverkey.kdb Entrust.net Global Secure Server Certification Authority Entrust.net Global Client Certification Authority Entrust.net Client Certification Authority Entrust.net Certification Authority (2048) Entrust.net Secure Server Certification Authority VeriSign Class 3 Public Primary Certification Authority VeriSign Class 2 Public Primary Certification Authority VeriSign Class 1 Public Primary Certification Authority VeriSign Class 4 Public Primary Certification Authority - G2 VeriSign Class 3 Public Primary Certification Authority - G2 VeriSign Class 2 Public Primary Certification Authority - G2 VeriSign Class 1 Public Primary Certification Authority - G2 VeriSign Class 4 Public Primary Certification Authority - G3 VeriSign Class 3 Public Primary Certification Authority - G3 VeriSign Class 2 Public Primary Certification Authority - G3 VeriSign Class 1 Public Primary Certification Authority - G3 Thawte Personal Premium CA Thawte Personal Freemail CA Thawte Personal Basic CA Thawte Premium Server CA Thawte Server CA RSA Secure Server Certification Authority testlabel C:\Program Files\IBM\GSK7\bin>gsk7cmd -cert -create -db c:\serverkey.kdb -pw passw0rd -label testcert -dn "cn=tam6,o=ibm,c=au" -default_cert yes -expire 999
The next step is to create an LDIF file for uploading the certificate and configuration information into ITDS. The text file appears as follows:
Creating LDIF configuration for SSL
dn: cn=SSL,cn=Configuration changetype: modify replace: ibm-slapdSslAuth ibm-slapdSslAuth: serverAuth - replace: ibm-slapdSecurity ibm-slapdSecurity: SSL dn: cn=SSL,cn=Configuration changetype: modify replace: ibm-slapdSSLKeyDatabase ibm-slapdSSLKeyDatabase: c:\serverkey.kdb - replace:ibm-slapdSslCertificate ibm-slapdSslCertificate: testlabel - replace: ibm-slapdSSLKeyDatabasePW ibm-slapdSSLKeyDatabasePW: passw0rd
Upload the file contents with the following command:
Loading SSL configuration into ITDS
C:\Program Files\IBM\GSK7\bin>idsldapmodify -D cn=root -w passw0rd -i file.ldif -p 389 modifying entry cn=SSL,cn=Configuration modifying entry cn=SSL,cn=Configuration
The final server-side configuration task is to extract the self signed certificate, so that it can be loaded into TAM E-SSO. The gsk7ikm utility can be used to extract the certificate. Simply open the CMS file and export the certificate created above, as shown in Figure 11.
Figure 11: Export certificate in der format
Copy this certificate onto the IMS server, placing it in the c:\ directory.
Restart the ITDS server instance through the Windows service manager. Check that the server is listening on port 636 by issuing the netstat command and checking the server is listening on that port.
Setting up SSL for TAM E-SSO
The next step is to setup SSL for TAM E-SSO. There are two steps involved. First, the ITDS exported CA certificate must be added to the trusted CA certificate store used by tomcat. This can be done by issuing the following commands at the command prompt:
Loading the certificate CA into Java trust store
C:\Encentuate\IMSServer220.127.116.11\j2sdk1.5\bin>keytool -import -alias ldapcert -file c:\cert.der -keystore C:\Encentuate\IMSServer18.104.22.168\j2sdk1.5\jre\lib\security\cacerts Enter keystore password: changeit Owner: CN='tam6', O=ibm, C=au -default_cert yes -expire 999 Issuer: CN='tam6', O=ibm, C=au -default_cert yes -expire 999 Serial number: 7620914a145654c4 Valid from: 12/22/08 10:34 AM until: 12/23/09 10:34 AM Certificate fingerprints: MD5: C1:8B:81:C3:C3:EA:37:EB:68:4D:22:C8:59:39:6F:B9 SHA1: 35:0F:A6:20:C1:EF:43:5F:45:CB:24:F3:C4:E7:C3:D3:0E:5A:8D:07 Trust this certificate? [no]: yes Certificate was added to keystore
Restart the IMS server.
The next step is to configure IMS Enterprise Directory configuration to enable SSL. Open the IMS Configuration Utility, select Enterprise Directories and select the ITDS server entry. Now select Update directory. The LDAP server URI must now include the new protocol and port, as follows: ldaps://ldap-hostname:636. Within the advanced configuration keys, the LDAP security protocol must be changed to ssl. Now select Save and test, which results in a success message being displayed at the top of the configuration page.
You should now be able to re-test some user registration processes to guarantee the SSL changes were correct.
Most of the problems encoutered during the development of this article were not related to functional product issues (other than those where tips have been provided in the text above), but more around the networking and system configuration of the systems. The following section outlines methods that can be used to debug product specific issues.
A person skilled in the art should be able to debug server side issues with LDAP, so this section will not focus on this area.
Problems encountered in the development of this article were mainly due to actual connectivity issues as well as LDAP protocol request data anomolies.
Wireshark was used extensively to debug problems encoutered with connectivitiy and LDAP problems. To configure Wireshark to listen on a particular network interface, simply select Capture->interfaces from the menu and then select the adapter that the protocol information will flow through. Next run a test, like registering a new user. This should result in a Wireshark output similar to that shown below.
Figure 12: Wireshark trace of LDAP
You can also test connectivity simply by use a telnet client (telnet command on Windows) to access the port used by the ITDS server. You can do this by issuing telnet itds-server-name 389 from a command prompt. If connectivity is OK, you might need to install the ITDS client on the IMS machine and simulate the LDAP requests being performed.
Of course, Wireshark cannot be used for inspecting SSL encrypted payloads, so I recommend ensuring that the IMS to ITDS configuration be performed successfully without SSL. Wireshark can, at the very least, reveal problems within the SSL handshake, which can be useful at times. In addition to the handshake errors, inspecting the IMS server stdout log file will give stack traces for any other errors encountered.
The IMS server stdout.log file is the best place to identify issues at any time during the configuration exercise. Monitor it closely to ensure the system remains stable across your configuration changes. A number of other tips include:
- During installation, make sure you follow the product installation instructions closely, always rebooting whenever required.
- If for any reason an AccessAgent had been configured to a particular IMS server, and you attempt to point it at a different one, it fails. If this happens, try re-installing the AccessAgent.
- Also, make sure the IMS tomcat process is fully initialised before attempting any operations. When the IMS server has started and CPU drops to zero, the DB2 process hovers around 200MB, and the tomcat process is about 600MB.
- If you are setting up the IMS server on VMWare, I found it needed to be allocated 2GB of memory for that image. Any less than this amount caused issues on IMS server startup.
Although TAM E-SSO can be used internally to provide Single Sign-on services to intranet users, there are many use cases where enterprise directories might be considered more relevant in a TAM E-SSO deployment. If this is the case, this article provides detailed instructions on how to configure such a deployment without the need to use Active Directory. Without Active Directory, TAM E-SSO maintains its business benefits and extends the reach beyond the internal Active Directory deployment.