Using Tivoli Access Manager Enterprise Single Sign-on with IBM middleware

Removing the dependancy on Microsoft components

IBM® Tivoli® Access Manager Enterprise Enterprise Single Sign-on (TAM E-SSO) provides cross application (that is, Web, Java™, mainframe or terminal services) single sign-on capabilities. The TAM E-SSO AccessAgent and IMS server are supported on Microsoft® Windows® operating system platforms, and typically leverage Active Directory for user management. However, many customers want to leverage their existing investment in IBM middleware products, and also extend the reach for TAM E-SSO beyond their intranet. This article shows how TAM E-SSO can be deployed into an environment consisting of IBM middleware, namely DB2® and IBM Tivoli Directory Server.


Christopher Hockings, IT Specialist (certified), IBM

Christopher HockingsChris works as a Senior IT Specialist and Team Leader in the Tivoli Security Australian Development Lab located on the Gold Coast, Australia. He leads a team of Software Engineers and IT Specialists working with Tivoli Security products.

28 January 2009

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.

Note: For all components deployed on the same machine, IBM DB2 v9.5 shipped with Tivoli Directory Server v6.2 technically can be used to host the TAM E-SSO database, but licensing restrictions might apply. This might be the perfect arrangement for a Proof Of Concept, but take care to ensure the DB2 database instances are suitably scaled according to the usage patterns of the products.

Figure 1: TAM E-SSO v8 conceptual architecture
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
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.

The stdout.log file contains the most useful information for witnessing server operation.

You also might want to consider changing the IMSService windows service to a manual startup option at this point. Making the IMSService a manual startup processs provides greater control over the process at the time of reboot.

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
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
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
IMS add LDAP details

Notice the username is simply root. The IMS server automatically (either sensibly or not) adds the cn= to the front and the user container to the end, to result in cn=root,o=ibm,c=au.

The ITDS server information must now be entered in the screen shown in Figure 6.

Figure 6: IMS add standard LDAP configuration
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
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
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:

  1. Enable self-service options
  2. Support shared workstations
  3. Use a shared desktop
  4. 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
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
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 Global Secure Server Certification Authority Global Client Certification Authority Client Certification Authority Certification Authority (2048) 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

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
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
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\IMSServer8.0.0.12\j2sdk1.5\bin>keytool -import -alias ldapcert -file
   c:\cert.der -keystore C:\Encentuate\IMSServer8.0.0.12\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

Are the timezones in synch ? This might be a good time to check while the IMS server is restarting.

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.

ITDS problems

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
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.

IMS problems

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.




developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into Tivoli (service management) on developerWorks

Zone=Tivoli (service management), Tivoli, Sample IT projects, Security
ArticleTitle=Using Tivoli Access Manager Enterprise Single Sign-on with IBM middleware