Introduction

IBM WebSphere Portal runs as an application on IBM WebSphere Application Server, and provides aggregation of content, applications, processes, personalization, and other services. WebSphere Application Server and WebSphere Portal can integrate with an external security manager product, such as IBM Tivoli Access Manager for e-business or Netegrity® SiteMinder®.

One of the components of Tivoli Access Manager (hereafter referred to as Access Manager) is its reverse proxy security server called WebSEAL. WebSEAL can front-end any Web application server or Web server in an enterprise e-business infrastructure. When WebSphere Application Server (hereafter referred to as Application Server) and WebSphere Portal are implemented with WebSEAL, it is usually necessary to provide a single sign-on (SSO) experience for the end user. In order to achieve SSO, Application Server needs to be configured to "trust" the WebSEAL server so that if WebSEAL has already authenticated a user, Application Server will not challenge the user again.

Application Server provides the Web Trust Association framework that you configure for third party security servers. An implementation of the Trust Association Interceptor (TAI) is required for every type of security server. Application Server comes with a TAI for Access Manager which you configure. Based on the established trust, Application Server can map the WebSeal's resultant credential to a valid Application Server credential.

This article focuses on integrating WebSEAL with WebSphere Portal for authentication to provide SSO to WebSphere Portal. This information is for Application Server administrators, portal administrators, and others who need provide SSO for their WebSphere Portal applications. To make the best use of this article, you should be familiar with Application Server, WebSphere Portal, and Access Manager administration tasks. You should also be familiar with configuring an LDAP directory server, such as IBM Tivoli Directory Server, which is used in the scenario described in this article.

The target environment in this scenario consists of the following:

• Windows® 2000 with 2GB memory
• WebSphere Portal V5.02.1 installed and configured with a database and an LDAP server; the scenario uses IBM DB2® UDB V8.1 and IBM Tivoli Directory Server V5.2 (hereafter called Directory Server).
• Access Manager V5.1 installed and configured with a supported LDAP server (in our case, Directory Server).

Back to top

Terminology

Before getting into the details of SSO configurations, review some of the terms used in this topic, listed in Table 1.

Access Manager V5.1 includes some additional components, such as Policy Proxy Server, which are not required for integrating authentication with Application Server. Refer to Access Manager Administrator's Guide for more information on these components.

Now that you understand the terms, let us look at SSO between Application Server and Access Manager.

Back to top

Understanding a user request flow

First, look at the flow of a user request to Application Server when it is configured with an authentication proxy such as WebSEAL. Figure 1 shows a simple flow.

The numbers in Figure 1 relate to these flow steps:

1. A user requests a resource protected by WebSEAL, which serves as the proxy and intercepts all requests. The user is challenged by WebSEAL for credentials and the user supplies them.
2. WebSEAL authenticates the user by consulting with its LDAP user registry. It also determines if the user has access to (that is, is authorized to open) the requested URL.
3. If authentication is successful, WebSEAL passes the request to the IBM HTTP Server using the junction that has been configured for it. The junction from WebSEAL to IBM HTTP Server is configured to pass the iv-user, iv-groups information in the HTTP header. The identification of the end user must be passed to the TAI in a header called iv-user, which is inserted by WebSEAL into the HTTP request header sent from WebSEAL to the Application Server. Even though WebSEAL can be configured to pass the end user identity in other ways, the iv-user header is the only one supported by the TAI. The end user password is not passed in the HTTP header.
4. The Application Server plugin file checks the context root of the requested URL, determines the target Application Server or clone, and forwards the request to to it.
5. The TAI in the Application Server (for which TAI must be enabled), processes the request. After TAI processes successfully, Application Server creates an encrypted user authentication cookie called an LTPA Token . This cookie, which is unique for every user for every session, (that is, if the same user logs in multiple times he will see a different cookie created each time) is long lived (typically 2 hours), and lasts to the end of the user session. Therefore, the TAI does not need to process every user request.
6. After the TAI has accepted the end user identification and created an LTPA Token, WebSphere Portal performs additional queries against LDAP, such as group information. It queries the resource mappings from the database, and then displays the portal page.

Back to top

SSO configuration options

There are several ways to set up SSO between Access Manager and Application Server. In this section, you learn the pros and cons of each option. The two primary design choices are using TAI and using LTPA.

Option 1: Using TAI

You can set up the TAI option in two ways: with a trusted user or with a trusted connection.

TAI using a trusted user
In this configuration, the TAI identifies the WebSEAL server using the Basic Authentication header. A trusted user is created in LDAP and the TAI is configured with that userid. Only the password (not the userid) is placed on the Basic Authentication header by WebSEAL. This represents a "shared secret" which only the TAI and the WebSEAL server know.

At run time, the TAI examines the password and validates with the user registry that the password belongs to the trusted user. This procedure enables the TAI to trust that it really is the WebSEAL server asserting the end user's identity, and the TAI can therefore trust it.

To set up the junction to use the Basic Authentication header to identify the WebSEAL server, you use the -b supply option on the junction creation command. Then, WebSEAL builds the Basic Authentication header using the password, which is specified in the Webseald.conf file (basicauth-dummy-passwd property).

The junction may be encrypted or non-encrypted; an encrypted junction is recommended. In the scenario described later in this article, you configure a WebSEAL junction and TAI. You create a user in WebSEAL that is used to authenticate WebSEAL to Application Server. This user's password is set in the Webseald.conf file.

TAI using a trusted connection
In this configuration, the WebSEAL server identifies and authenticates itself to the Web server using its own client-side certificates. In this case, the TAI will do no further validation of the WebSEAL server. This configuration is set in TAI using:

com.ibm.websphere.security.WebSEAL.mutualSSL=true

When you set mutualSSL=true, the TAI validates the WebSEAL host using the hostname property, and does no further validation. It assumes that the connection from WebSEAL to Application Server is completely trusted; therefore, client-side certificates for authentication are required.

This setup requires an SSL junction. You set up an encrypted junction using SSL with client certificates, and you specify the certificate label.

The Web server for Application Server must have the signing certificates for the WebSEAL server's client certificate. The WebSEAL server must have the signing certificates for the HTTP Server's server certificate.

The Web server for Application Server must be configured to challenge the WebSEAL server for the certificate. Using the pdadmin command line, you can enter the appropriate command on a single line. Substitute the variables between the braces < > appropriately. See the next section for more information.

server task <Webseal_server_instance_name> create -t ssl -h 
<web_server_hostname> -p port -j -w -K <certificate_label> 
-c iv-user,iv-groups /<junction_name>

After completing these steps, you will have created a trusted link from WebSEAL to the Web server. If the Web server is not on the same machine as Application Server, you must set up another trusted link from the Web server to Application Server. Here again, client side certificates and client authenticated SSL are required. The steps for configuring this are described in the WebSphere Application Server Information Center.

Deciding which TAI setup to use
Now that you know how to set up both TAI options -- using a trusted user or a trusted connection -- consider the pros and cons of each to decide which to use.

Both TAI options provide a secure way of authenticating WebSEAL to Application Server. Neither is inherently superior to the other from the perspective of asserting identities to the Application Server WebSEAL TAI. The key points to remember are that by using a password, you must ensure and manage the password in the registry that the Application Server TAI is using for validation. Also, the link from WebSEAL to Application Server (through the Web server) should be over HTTPS to protect the password.

The certificate-based authentication approach avoids the password management issue, but exchanges it for the issue of managing client-side certificates. The link from WebSEAL to the Web server must use client certificate authentication, and the same must be true for the link from the Web server to the application server. Should either link be insecure, the TAI will still work, but it will not be secure. This is perhaps the one disadvantage of the certificate approach -- if there is a human error in configuration it may appear to work, but it will, in fact, be insecure. For this reason, we configure a TAI to use password authentication from WebSEAL in the example described later in this article.

That said, it is important to understand that if your system is relying on WebSEAL for more than just identity assertion to the TAI, password authentication from WebSEAL to Application Server may not be sufficient. For example, some systems rely on the WebSEAL HTTP headers for making security decisions. Those headers are not validated by the TAI. Therefore, those headers could potentially be forged if a Web client authenticated directly to Application Server (bypassing WebSEAL) and then forged the WebSEAL headers. This user would be a valid authenticated user (Application Server will ensure that), but the additional headers that would normally be provided by WebSEAL could be manufactured directly by the rogue client. Therefore, as a hack, an attacker might authenticate as a valid user, but then provide an HTTP header (perhaps the iv-cred) that implies more permissions than he actually has. This could be quite dangerous.

In summary, if WebSEAL is used solely for asserting the user identity to Application Server with the WebSEAL TAI, password or mutual SSL authentication works quite well. On the other hand, if the application is relying on additional information in the HTTP headers for security purposes, you should use mutual SSL authentication.

Option 2: Using LTPA

With this option, you do not have to configure a TAI in Application Server. Instead, you configure an LTPA junction in WebSEAL, and Access Manager issues the LTPA Token. Refer to Figure 2, below.

Now look at the request flow scenario for an LTPA junction. The step numbers below correspond to the lines numbered in Figure 2.

1. User requests a resource protected by WebSEAL. User is challenged by WebSEAL for credentials, and the user supplies them.
2. WebSEAL authenticates the user by communicating with its user registry. It also determines whether the user is authorized to open the requested URL. Upon successful authentication of the end user, WebSEAL creates the LTPA Token cookie.
3. The request is passed to the IBM HTTP Server using the junction that has been configured for it. The junction from WebSEAL to IBM HTTP Server is configured to pass the iv-user, iv-groups information, and the LTPA Token that was created in Step 2, in the HTTP Header.
4. The request is forwarded to the appropriate Application Server or clone, as determined by the Application Server plug-in.
5. In Application Server, the TAI is not enabled and Application Server gets the LTPA Token in the header. Application Server only creates the session cookie for this user and assumes that this user has been authenticated. WebSphere Portal searches LDAP for the group information, gets the resource mappings from the database, and then displays the portal page.

This paper does not discuss the configuration of the LTPA approach further. See the Access Manager documentation for more information on this configuration.

Back to top

Configuring Access Manager using TAI with a trusted user

The remainder of this article describes a scenario showing how to configure Access Manager to provide SSO to Application Server using TAI with a trusted user. The TAI accepts password-based authentication from WebSEAL, rather than assuming an SSL trusted connection.

This process guides you through setting up the TAI. See Resources for more help with specific tasks, such as installing Access Manager or WebSphere Portal. See the WebSEAL Administrator's Guide for help in understanding the role of WebSEAL, encrypted and non-encrypted junctions, and for using the WebSEAL junction command options.

This scenario assumes that IBM HTTP Server (hereafter called HTTP Server) is the Web server.

Step 1. Install and configure the base products

To begin, install and configure WebSphere Portal, DB2, LDAP, and HTTP Server. The WebSphere Portal installation program was simplified from V4 to V5. The V5 program installs:

• WebSphere Portal
• WebSphere Application Server (including IBM HTTP Server)
• IBM Cloudscape™ database.

For the TAI with trusted user environment, you need to:

1. Install WebSphere Portal V5.0.2.1 and configure it with DB2 and HTTP Server using the configuration tasks provided with WebSphere Portal. Refer to the WebSphere Portal Information Center for help with this step.
2. Install and configure IBM Tivoli DIrectory Server V5.2. Refer to the IBM Tivoli Directory Server installation documentation for instructions.
3. Create an LDAP suffix dc=ibm,dc=com. The LDAP used here is Directory Server, configured like this:
   • LDAP Admin id: cn=root
   • Password: ldap
   • Suffix: dc=ibm,dc=com
   • User Search Base for WebSphere Portal: cn=users,dc=ibm,dc=com
   • User object class: inetOrgPerson
   • Group Search Base for WebSphere Portal: cn=groups,dc=ibm,dc=com
   • Group object class: groupOfUniqueNames
   • Portal Admin: uid=wpsadmin,cn=users,dc=ibm,dc=com
   • Portal Admin Group: cn=wpsadmins,cn=groups,dc=ibm,dc=com
   • LDAP Bind Id for Application Server and WebSphere Portal: uid=wpsbind,cn=users,dc=ibm,dc=com
   Import the portalusers.ldif file from the Download section into your LDAP to create the LDAP Directory Tree.
   
   
4. Configure an Access Control List (ACL) for your directory such that the wpsbind id has read and search access for the Directory Tree under the suffix dc=ibm,dc=com. Configuring an ACL is a directory specific task. Refer to your chosen LDAP's documentation for configuring the ACL.
   
   To configure an ACL for Directory Server V5.x, login as cn=root to the browser-based Directory Server V5.x admin console using the following format for the URL:

   http://<hostname>:<transport-port>/IDSWebApp/IDSjsp/Login.jsp

   
   
   For example:

   http://localhost:9080/IDSWebApp/IDSjsp/Login.jsp

   
   
   
5. Go to Directory management => Manage entries. Select the suffix dc=ibm,dc=com and click on Edit ACL.
   Figure 3. Editing the ACL
   
   
6. On the left, click on the Non-filtered ACLs. Select the Propagate ACLs check box to allow descendants without an explicitly defined ACL to inherit from this entry. Enter the distinguished name of the wpsbind user: uid=wpsbind,cn=users,dc=ibm,dc=com.
7. For Type, select access-id, because this DN is a user, then select ADD.
   Figure 4. Adding an ACL for the wpsbind user
   
   You will see the window shown in Figure 5. The Security class section defines permissions for attribute classes:
   • Normal attributes, such as a commonName attribute, require the least security.
   • Sensitive attributes, such as homePhone, require a moderate amount of security.
   • Critical attributes, such as userPassword, require the most security.
   • System attributes are read-only attributes maintained by the server.
   • Restricted attributes are used to define access control.
   
   Figure 5. Adding an ACL
   
   
8. Assign grant to the Read, Search, and Compare security classes. Assign deny to the Write security class. Click OK, then OK again on the following screen to save your changes.
   Figure 6. Saving your changes
   
   
9. To verify the ACL that you have just set, logout and login to the console as wpsbind by entering your fully qualified DN. Select Directory management and click on Manage entries. Select the suffix dc=ibm,dc=com and click Expand, as shown in Figure 7. (Look for the "+" sign next to dc=ibm,dc=com.)
   Figure 7. Logged in as wpsbind
   
   

You have now completed the ACL configuration for the wpsbind user for LDAP.

Next, you will configure WebSphere Portal with Directory Server.

1. Use wpsbind as the LDAP Bind ID for Application Server and WebSphere Portal. Use SSO Domain ibm.com.
2. To verify your WebSphere Portal Directory Server configuration, go to the WebSphere Portal console and login as wpsadmin. For example:

   http://rhaalab1.raleigh.ibm.com/wps/myportal

   
   
   
3. Check that you can see the Administration tab.
4. Login to the Application Server admin console as wpsbind and ensure that you can login.

Step 2. Install Access Manager and configure it with LDAP

In this step, you first install Tivoli Access Manager V5.1 and apply patch 2 (recommended). Alternatively, you can use Access Manager V4.1 with Fixpack 6. Next, on the LDAP Server machine, you configure Directory Server for Access Manager. Finally, you need to configure Access Manager components. After this part is complete, you should be able to login to the Access Manager Web Portal manager as sec_master.

Install Access Manager V5.1

1. Install the Access Manager Base components from the Access Manager Base CD, then apply patch 2. For detailed directions, see the Access Manager Installation documentation, listed under Resources.
2. Next, install the Access Manager Web Portal Manager.
3. Install Web Security runtime and WebSEAL.

Add the Access Manager attribute file to the LDAP schema
If you are using Directory Server V5.2, you can skip to Create a secAuthority suffix.

Access Manager requires special LDAP attributes to be added to the LDAP Schema. These attributes are added by Directory Server V5.2 for you. If you are using Directory Server V5.1, follow the steps below, and use the V3.am file in the download file.

1. Stop the IBM Directory Server service.
2. Copy the schema file V3.am.at from the download file to the Directory Server schema directory <LDAP_INSTALL_DIRECTORY>\etc where, LDAP_INSTALL_DIRECTORY is the directory where LDAP is installed (default is c:\Program Files\IBM\LDAP).
3. To open the Directory Configuration Tool on Windows, select Start => Programs => IBM Directory Server V 5.1 => Directory Configuration.
4. In the left pane, click on Manage schema files. In the right pane, select the file name with the full path to the VM.am.at file. In the Schema validation rules, make sure that Version 3 (Lenient) is selected, and then click Add.
5. Check that the V3.am.at file shows in the list of current schema files, and then click OK.
   Figure 8. Directory Server V 5.1 Configuration Tool
   
   

Important: You must click OK in order for the changes to be committed.

Create a secAuthority suffix
Access Manager requires a suffix to maintain its metadata. The required suffix is secAuthority=Default. The suffix distinguished name is not case sensitive.

1. To open the Directory Configuration Tool in Windows, select Start => Programs => IBM Directory Server V5.2 => Directory Configuration.
2. On the right pane, click on Manage suffixes. Enter the suffix secAuthority=Default, and then click Add. You will see the suffix in the list of current suffix DNs in the right pane.
   Figure 9. Adding the secAuthority=default suffix
   
   
3. Click OK. Remember, the changes are committed only after you click OK . Otherwise, the suffix will not be added.

Add a container to store the Access Manager GSO data
Next, you need a container in LDAP so that Access Manager can store its Global Single Sign-on (GSO) data. Extract the file c:\wpstam\tamgso.ldif from the download file.

1. Open the Directory Server Configuration Tool (if you do not already have it open), and click on Import LDIF data.
2. Click on Clear results.
3. Browse to the file c:\wpstam\tamgso.ldif, and click Import to begin the import process, as shown below.
   Figure 10. Import tamgso.ldif file
   
   You should see this message, as shown in Figure 11:

   ldif2db: 2 entries have been successfully added out of 2 attempted.

   
   
   Figure 11. Successful import of ldif file
   
   

Alternatively, you could use the command line to import this ldif file. Use the ldapadd command in this format:

ldapadd -D <LDAP ADMIN ID> -w <ldap _admin_password> -f <ldif_file_name>

For example:

ldapadd -D cn=root -w ldap -c -f "C:\wpstam\tamgso.ldif"

You have completed the LDAP configuration for Access Manager components.

Set up Access Manager base components
After you have installed the Access Manager base components, you need to configure them. On Windows, you use the pdconfig tool to configure the components:

1. Open a command prompt and type pdconfig. A configuration utility opens.
2. Select Access Manager Runtime and click on Configure.
3. Select Registry as LDAP, then Next. Enter the LDAP hostname and port; in our example, rhaalab3.raleigh.ibm.com and 389, respectively.
4. If you configured SSL with communication with LDAP, enter the specific port.
5. If you need to enable SSL, see "Enabling Secure Sockets Layer" in the Tivoli Access Manager Base Installation Guide.
6. Select Access Manager Policy Server and click Configure as shown below.
   Figure 13. Configure Access Manager Policy Server
   
   
7. On the following screen, enter the LDAP Administrator user name and password and click OK.
8. Specify the sec_master password and click OK.
9. Accept defaults for SSL Connection parameters for Access Manager. You will see Configuring Access Manager Policy server and then this message:
   Figure 14. Configure Access Manager Policy Server message
   
   The Policy server configuration creates a default SSL certificate authority file named pdcacert.b64. For an Access Manager runtime system to authenticate to Access Manager servers, each runtime system requires a copy of this file. To obtain this file, do one of the following:
   • During configuration of the Access Manager runtime package (using the pdconfig utility), select to download the pdcacert.b64 file automatically.
   • Manually copy the pdcacert.b64 file to the Access Manager system before configuring the Access Manager runtime component.
     
     
10. Next, select Authorization Server and click Configure as shown in Figure 15.
    Figure 15. Configure Access Manager Policy Server message
    
    
11. Specify the domain name. The default is Default, which indicates the management domain. Do not change this.
12. Select Next .
    Figure 16. Domain should be Default
    
    
13. Enter the Policy Server information on the next screen. Policy Server host name is the host name used by the policy server to contact this server. Default is the local system host name. Policy Server port is the port the policy server listens for requests, which by default is 7135.
14. Click Next.
15. Enter the sec_master password. Do not change the value of sec_master. Click Next.
16. On the next dialog, local host name specifies the fully qualified name of the host on which the authorization server will reside. Administration request port specifies the administration request port. The default port is 7137. Authorization request port specifies the authorization request port number. The default port number is 7136. Click OK.
17. This should complete successfully.

Next you will configure the Java runtime environment component for use within the Application Server JRE.

1. Select Access Manager Java Runtime Environment and click Configure.
2. Select the Full configuration type and click Next.
3. Specify the JRE that was installed with IBM Application Server (example: c:\WebSphere \AppServer \java \jre) and click Next.
4. Specify the Policy Server information.
5. Click Next and then click Finish on the Common Logging Screen. You should see a message that the configuration is complete.

Access Manager WebSEAL configuration is next:

1. Select Access Manager WebSEAL package and click Configure.
   Figure 17. Access Manager WebSEAL configuration
   
   
2. Click on Configure again to configure a new instance of WebSEAL.
   Figure 18. Configure new WebSEAL instance
   
   
3. Continue through the following screens to enter a name for WebSEAL instance, the hostname, and listening port, which by default is 7234. Give it the HTTP port number 81 and the HTTPS port number 444, and set a document root.
4. Click Close on the configuration utility.

To verify you have installed Access Manager V5.1 components on the host (for example, RHAALAB2):

1. Open a command prompt and type pdadmin.
2. Enter these commands:

   Pdadmin > -a sec_master <your password> pdadmin sec_master> server list

   
   
   This should give you the newly configured instance of WebSEAL.
   
   
3. Make sure you can access your equivalent of: http://rhaalab2.raleigh.ibm.com:81.
4. Click on the link stating re-access the page using https. It should redirect you to your equivalent of: http://rhaalab2.raleigh.ibm.com:444.
5. Verify that you can log in.

You have now completed the Access Manager configuration.

Step 3. Configure HTTP Server for SSL

If you are setting up WebSEAL junction to use SSL (which we recommend), you must perform this step so that HTTPS traffic uses a self-signed certificate. If you are using TCP, instead of SSL for your WebSEAL junction, skip this step and proceed to Step 5. The Web server must have a port defined for SSL, usually 443. You will use the IBM Key Management Utility, iKeyman, to generate a self-signed certificate.

1. Create a directory called c:\ihs\keytab.
2. Select Start => Programs => IBM HTTP Server => Start Key Management Utility.
3. Select Key Database File => New. Enter the following information:
   • Key Database Type: CMS key database file
   • File Name: keyfile.kdb
   • Location: \ihs\keytab as shown below.
4. Click OK.
   Figure 19. Key files
   
   
5. Enter test for the password. Check the boxes for Set expiration time and Stash password to a file. Click OK. You will see a message saying that the password has been encrypted and saved in the file c:\ihs\keytab\keyfile.sth.
   Figure 20. HTTP Server key file
   
   
6. Select Create => New Self Signed Cert. For Key Label, enter IHS. Common Name defaults to the hostname. Click OK.
   Figure 21. Creating a self signed certificate
   
   
7. Click Extract certificate to extract the certificate to a file. Enter the Certificate file name as cert1.arm as shown below. Click OK.
   Figure 22. Extracting a certificate to a file
   
   
8. You have now extracted the certificate in a file cert1.arm. Exit the iKeyman utility.
9. Add the following lines to the end of the <IHS_INSTALL_ROOT>\conf\httpd.conf file:

   Listen 443 LoadModule ibm_ssl_module modules/IBMModuleSSL128.dll <virtualhost *:443> SSLEnable Keyfile "C:\ihs\keytab\keyfile.kdb" SSLV2Timeout 100 SSLV3Timeout 1000 </virtualhost>

   
   
   
10. In this code, replace the * with your specific virtual host.
11. Stop and restart the HTTP Server. Verify that it is listening on 443 by going opening a page like this one in a Web browser: https://yourserver.domain.com/. For example: https://rhaalab1.raleigh.ibm.com/.

You have completed the SSL configuration for HTTP Server.

Step 4. Load the certificate into the WebSEAL key store

Now you need to load the certificate you created in the last step into the key database of WebSEAL:

1. If your HTTP Server is on a different machine than WebSEAL, copy your certificate from Step 3 from the HTTP Server machine c:\ihs\keytab\cert1.arm to the WebSEAL machine in the same directory.
2. Start the IBM Key Management Utility on the WebSEAL machine.
3. Select Key Database File => Open from the menu bar.
4. Change the directory to <Access Manager_Install_root>\PDWeb\www-default\certs and enter pdsrv.kdb in the File name field. This is the keyring used by WebSEAL to store acceptable CA certificates for SSL junctions. Enter the password as pdsrv and click OK.
5. Select Signer Certificates from the pull down menu and click the Add button.
   Figure 23. Add a signer certificate
   
   
6. Enter the file name as cert1.arm and enter the location as c:\ihs\keytab\ as shown below. Click OK.
   Figure 24. Get the certificate from the file saved earlier
   
   
7. Enter IHS as the Label and press OK to continue.
8. Exit the IBM Key Management utility.
9. Stop and restart the Access Manager WebSEAL service.

You have completed importing the HTTP Server Certificate into the Key database of WebSEAL.

Step 5. Enable forwarding of HTTPS traffic

You need to configure the Application Server plug-in to forward HTTPS traffic to the application server. To do that, you need to update the virtual host list for Application Server to include the correct hostname and port number, and regenerate the plug-in configuration. You add MIME types for ActiveX Controls and Java Archive files. These MIME types are needed for the Lotus components of WebSphere Portal Extend.

1. On the machine running Application Server and WebSphere Portal, ensure that server1 is running: https://rhaalab1.raleigh.ibm.com:9090/admin
2. Login to the Application Server admin console using wpsbind id and password.
3. On the Console on the left pane, select Environment => Virtual Hosts => default_host => Host Aliases => New.
4. Add a host alias for the hostname and SSL port that you added to the Web server in Step 3. The hostname may be * or a fully-qualified hostname. Usually this would be the hostname of the Web server. Click OK to add the virtual host at port 443 (the SSL port of the HTTP Server).
   Figure 25. Adding a virtual host in the Application Server Admin console
   
   
5. Click Save to save the changes to the configuration.
6. Select Environment => Update Web Server Plugin and click OK to update the plug-in. Wait for the message Plugin update successful.
7. If the Web server is on a different machine, copy the plugin-cfg.xml file to the Web server machine. (For a full description of the virtual host function of Application Server, see its documentation.)
8. Verify that you can get to snoop: https://rhaalab1.raleigh.ibm.com/snoop.
9. To add a MIME Type, select Environment => Virtual Hosts => default_host => MIME Types => New. Enter the following values:
   • Mime Type: application/java-archive
   • Extensions: jar
10. Click OK, and then save your changes to the Master configuration.

You have completed adding a virtual host and MIME Type. Now, configure WebSphere Portal for SSL.

1. Edit the <WP_ROOT>\shared\app\config\services\ConfigService.properties file as follows: (443 is the HTTP Server SSL port)

   redirect.logout.ssl = true redirect.login.ssl = true redirect.logout.url = https://<webseal-host-name>:<webseal- port>/pkmslogout host.port.https = 443

   
   
   
2. Save and close this file.

Step 6. Create the trusted user account in Access Manager

The Distinguished Name for this user in this scenario is: uid=taiuser,cn=trustedusers,dc=ibm,dc=com. This is the userid and password that WebSEAL uses to identify itself to Application Server. To prevent potential vulnerabilities, do not use the sec_master or <wpsadmin> users for the trusted user account. The trusted user account should be for the TAI only. The Distinguished Name of this taiuser must be in the Directory Information Tree which Application Server can search on; for example, dc=ibm,dc=com.

1. Import the portalusers.ldif file from the download file to create the taiuser in LDAP. You can use the LDAP Configuration Utility, or you can use ldapadd or ldapmodify to add the user.

   ldapadd -D cn=root -w ldap -f <full path to portalusers.ldif>

   
   
   
2. Ensure that the taiuser has been created in Directory Server.
3. Next, login to pdadmin and execute the following commands to import the the taiuser into Access Manager:

   pdadmin sec_master> user import taiuser uid=taiuser,cn=trustedusers, dc=ibm,dc=com pdadmin sec_master> user modify taiuser account-valid yes pdadmin sec_master> user modify taiuser password-valid yes pdadmin sec_master> user list * 10

   
   
   The last line should give you taiuser in its output. Now, TAM has knowledge of the taiuser.

You have created the taiuser and imported it in Access Manager.

Step 7. Configure WebSEAL junction to HTTP Server

Next, configure a WebSEAL junction from the WebSEAL Server to the Web server. You perform the configuration on the WebSEAL machine (RHAALAB2, in this scenario).

1. On the WebSEAL machine, use the pdadmin command line to create a WebSEAL junction. Enter the following commands (see also Figure 26):

   pdadmin -a sec_master <your paassword> server list server task <WebSEAL-instance-name> create -t ssl -h <webserver_host> -p <SSL port> -j -w -b supply -c iv- user,iv-groups -f /ssl1 server task <webseal-instance-name> list

   
   
   The server list command gives you a list of WebSEAL instances. The <SSL port> is for your Web server, which is 443 in this scenario.
   Figure 26. Creating a WebSEAL junction
   
   
2. Verify the following URLs before you move ahead:
   • WebSEAL home page: https://rhaalab2.raleigh.ibm.com:444
   • HTTP Server home page: https://rhaalab1.raleigh.ibm.com/
   • HTTP Server junctioned through WebSEAL (should display the HTTP Server home page): https://rhaalab2.raleigh.ibm.com:444/ssl1
3. To enable the Junction to Request Mapping Table (JMT) function, define an ASCII text file called jmt.conf. The format for data entry in the file jmt.conf consists of the junction name, a space, and the resource location pattern. You can also use wildcard characters to express the resource location pattern. The location of this file is specified in the [junction] stanza of the configuration file:

   <Access Manager_install_root>/PDWeb/etc/webseald-default.conf

   
   
   For example:

   jmt-map = lib/jmt.conf

   
   
   This statement indicates that jmt.conf resides in: <Access Manager_install_root>/PDweb/www-default/lib/. Enter the following in the jmt.conf file: /ssl1 /wps/*:
4. After you add data to the file, use the jmt load command to "load" the data so that WebSEAL has knowledge of the new information.
   Figure 27. Creating a WebSEAL junction
   
   

You have completed creating a junction and creating and loading a jmt.

Step 8. Edit webseald.conf file

In this step, you will edit the WebSEAL configuration file to configure some timeouts and the dummy password that will be passed in the HTTP Header:

1. Open the file: <Access Manager_install_root>/PDWeb/etc/webseald-default.conf.
2. In the [junction] stanza , change the basic-auth-dummy-password to the user password of the taiuser:

   basicauth-dummy-passwd = taiuser1

   
   
   In the same stanza, change the following:
   • http-timeout = 300
   • https-timeout = 300
3. In the [forms] stanza, enable WebSEAL authentication using forms: forms-auth = https
4. In the [script-filtering] stanza, set: script-filter = yes
5. Because you are using forms-based authentication and not basic authentication, change the ba-auth from https to none:

   ba-auth = none

   
   
   
6. Stop and start the WebSEAL server.

Step 9. Import WebSphere Portal users and groups into WebSEAL

In this step, you will import the WebSphere Portal users and groups into WebSEAL using the pdadmin utility.

Login to pdadmin with sec_master. Import wpsadmin and wpsbind users using these commands:

pdadmin sec_master> user import wpsadmin uid=wpsadmin,cn=users,dc=ibm,dc=com
pdadmin sec_master> user modify wpsadmin account-valid yes
pdadmin sec_master> user modify wpsadmin password-valid yes

pdadmin sec_master> user import wpsbind uid=wpsbind,cn=users,dc=ibm,dc=com
pdadmin sec_master> user modify wpsbind password-valid yes
pdadmin sec_master> user modify wpsbind account-valid yes
pdadmin sec_master>

Step 10. Configure TAI in Application Server

Now, configure the WebSEAL TAI in Application Server to enable SSO with Application Server:

1. Login to the Application Server admin console. For example, open in a Web browser your equivalent to: https://rhaalab1.raleigh.ibm.com:9090/admin.
2. Navigate to Security => Authentication mechanism => LTPA => Trust Association, and then click Enable.
3. Click on Interceptors under Additional properties. The Interceptor class name is : com.ibm.ws.security.web.WebSealTrustAssociationInterceptor.
4. Click on Custom properties and then add the properties listed in Table 2. Copy the property names exactly as they appear in this table. Note the values and their explanations enclosed in { }, and tailor these values for your environment.

   Table 2. Custom properties

   Name	Value
   com.ibm.websphere.security. trustassociation.types	webseal
   com.ibm.websphere.security. webseal.hostnames	RHAALAB2 {The output of the "hostname" command is to be entered here in the exact same case. This field is case sensitive. This is not the fully qualified hostname. You can enter a comma separated list of hostnames.}
   com.ibm.websphere.security. webseal.id	iv-user {This is the header field that WebSEAL sends in the request to the Application Server. This tells the TAI which field to use for the end user identity.}
   com.ibm.websphere.security. webseal.loginId	taiuser {The password of this id is in the basicauth-dummy-passwd property in WebSEALd.conf file.}
   com.ibm.websphere.security. webseal.ports	444 {This is the port number of the WebSEAL host that is expected in the request header. Include any proxy ports. If the com.ibm.websphere.security. WebSEAL.ignoreProxy value is set to true, add the port numbers from the WebSEAL host names but omit any proxy ports.}
   com.ibm.websphere.security. WebSEAL.mutualSSL	Optional {By default this is set to false. If you created a junction using SSL with client certificates to identify the WebSEAL server to the TAI, this value should be set to true. Otherwise, this value should be false. If true, no further validation will be done by the TAI. In effect, the TAI simply trusts the identity of the WebSEAL machine as established by the mutually-authenticated SSL connection.}
   com.ibm.websphere.security. WebSEAL.ignoreProxy	Optional {When there are proxies involved, set this to true. When this is set to true or yes, it tells Access Manager to ignore the proxy info hostnames and ports. By default, this property is set to false. If there are no proxies involved, this is irrelevant.}

5. Compare your settings with those shown in Figure 29, below. Important: The hostname is case specific, and in this scenario the hostname RHAALAB2 is all capital letters to match the name we used for testing. Yours may be mixed or lower case; use your exact hostname.
6. Save the configuration.
   Figure 29. Custom properties
   
   
7. Save the configuration and logout of the Application Server admin console. Delete the precompiled JSPs from: <Application Server_ROOT>/temp/<nondename>/WebSphere_Portal
8. Restart WebSphere Portal after deleting the precompiled classes. Check the following message in the <WebSphere Portal_HOME>/log/SystemOut.log file. These messages indicate that the TAI loaded successfully:

   TrustAssociat A SECJ0121I: Trust Association Init class com.ibm.ws.security.web.WebSealTrustAssociationInterceptor loaded successfully [6/2/04 14:28:09:685 EDT] 4de6fe46 WebSealTrustA W SECJ0225W: PD Authentication disabled. [6/2/04 14:28:09:695 EDT] 4de6fe46 TrustAssociat A SECJ0122I: Trust Association Init Interceptor signature: WebSeal Interceptor Version 1.1

   
   
   
9. Verify that you get SSO by going to your version of this URL: https://rhaalab2.raleigh.ibm.com:444/ssl1/wps/myportal.
10. Login as wpsadmin to the Access Manager and check that you get the Administration tab.

Congratulations! You have successfully configured SSO between Access Manager and WebSphere Portal.

Post setup steps

Now that you have successfully configured Web SSO between Access Manager and WebSphere Portal, consider a few additional points. While SSO is working, there are some interesting corner cases that you may wish to address to create a particular user experience. These changes are not recommendations, merely a listing of the most common changes that customers make to Access Manager and WebSphere Portal as part of configuring SSO. You need to decide if these changes are appropriate or necessary in your environment.

Remove the original login page
Now that you have configured Access Manager, if a user clicks on the WebSphere Portal login icon, he or she will be sent to the myportal page which is protected by Access Manager, which in turn will result in an implicit authentication by Access Manager to the Portal. However, the original login page (if there is one for your theme) is still there. A user could type in the login URL directly, if they were really motivated. It's most likely something like wps/portal/.scr/Login.

To prevent this situation, you can simply delete the login page for your theme. If you are using the default theme, you would first make a backup copy of this file, and then delete the Login.jsp located in: <AppServ_HOME>\installedApps\<nodename>\wps.ear\ wps.war\screens\html.

Modifying logout behaviour
You might also need to change the logout behavior. The preferred and default behavior is for users to logout of WebSphere Portal, but to retain their Access Manager SSO credentials. Access Manager is, after all, an enterprise SSO product and is likely providing SSO to more than just WebSphere Portal. However, in some cases you might prefer that, when users logout of WebSphere Portal, their Access Manager credentials are also destroyed. If you want this behavior, do the following:

1. Make a backup copy of the ConfigService.properties file in: <WP_ROOT>/shared/app/config/services/ConfigService.
2. Edit the file as specified below:

   redirect.logout= true redirect.logout.ssl=false or true, depending on your environment redirect.logout.url=<protocol>://<host_name>/pkmslogout

   
   where:
   • <protocol> is the protocol of the WebSEAL machine (http or https).
   • <host_name> is the fully qualified WebSEAL URL.
   The value for redirect.logout.url must appear on a single line.

Disable user creation in WebSphere Portal
Because Access Manager is in charge of managing users, you should ensure that users are not created through WebSphere Portal. You should not allow this behavior because these users will not have access to Access Manager until you manually import them as Access Manager users through the Access Manager admin tools. WebSphere Portal creates entries in the directory automatically in two ways: administratively, using the Manage Users and Groups portlet, or users can self-register. To prevent this, you can remove the Manage Users and Groups portlet from its page. In order to remove the self registration link from the ToolBarInclude.jsp:

1. Make a backup copy of the <Application Server_ROOT>/installedApps/<hostname>/wps.ear/ wps.war/themes/html/<theme_name>ToolBarInclude.jsp file, located in the subdirectory of each theme, and then edit the file as in the next steps.
2. Open the file in a text editor and comment out the enroll button as shown below:

   <!-- <%-- enroll button --%> <wps:if loggedIn="no"> <% String dt = com.ibm.wps.puma.UserManager.instance().getDirectoryType(); if (dt==null) { dt = ""; } if (!dt.equals("SSPM")) { %> <td class="wpsToolBar" valign="middle" align="<%=bidiAlignRight%>" nowrap> <a class="wpsToolBarLink" href='<wps:url command="PrepareEnrollment" home="public" reqid="no"/>'><wps:text key="link.enrollment" bundle="nls.engine"/></a> </td> <% } %> </wps:if> -->

   
   
   
3. Delete the compiled JSPs from the WebSphere Application Server cache by removing the contents of this directory: <Application Server_ROOT>/temp/<node_name>/WebSphere_Portal/.

Back to top

Troubleshooting

1. Test Web server:

   http://rhaalab1.raleigh.ibm.com https://rhaalab1.raleigh.ibm.com

   
   
   If you cannot get to either of them, stop your Web server and restart it. If your Web server is NOT listening at port 80 or 443, make sure you use the port number.
2. Check the Web server config file, httpd.conf file for the ports. Search for port 80 and check if it is listening at that port. Search for port 443 and check the syntax. When in doubt, comment out the SSL piece and restart the Web server.
3. Check Web server documentation for details. The Web server should be working fine with SSL before you move on further and you should have verified that both URLs (above) display the Web server home page.
4. Test Snoop without WebSEAL. Strong recommendation: try to get the snoop to work when troubleshooting. First check that you can get to snoop without WebSEAL and without SSL:

   http://rhaalab1.raleigh.ibm.com/snoop

   
   
   If this does not work, check the virtual host entries in the Application Server admin console and ensure that a virtual host has been defined for the Web server's http port. Make sure that you can get to snoop without SSL from your Web server.
5. Now, try to get to snoop though Web server https:

   https://rhaalab1.raleigh.ibm.com/snoop

   
   
   If this does not work, check the virtual host entries in the Application Server admin console and ensure that a virtual host has been defined for the Web server's SSL port. Open the httpd.conf file to check the SSL port and then check the Application Server Admin Virtual hosts for SSL Port and host. Don't forget to use the port, if its not 443.
6. If you cannot to get to snoop from the Web server still, stop all the Java processes on your machine. Clear out the log files from WebSphere/AppServer/logs/server1 directory. Start server1 by : WebSphere/AppServer/bin/startServer server1. Check WebSphere/AppServer/logs/server1/tracefile to ensure that it started by checking for an open for e-business message at the end.
7. If you get errors, check virtual hosts alias for default_host. Check that default_host has an entry for SSL port and the non-SSL port. If you need to add the ports, be sure to Save the configuration.
8. Regenerate the plug-in file. Stop and restart server 1 and stop and restart Web server. Copy the plugin-cfg.xml file if your Web server is on a different machine. Before you move to the next step, ensure that you can get to snoop using https://rhaalab1.raleigh.ibm.com/snoop.
9. Verify WebSEAL: https://rhaalab2.raleigh.ibm.com:444/.
10. Verify the Web server through WebSEAL: https://rhaalab2.raleigh.ibm.com:444/ssl1. You should get the Web server home page. If you don't get this, then there may be a problem with the junction. Use the server task create command again to create a junction and use -f to force a new one.
11. Verify snoop using WebSEAL: https://rhaalab2.raleigh.ibm.com/ssl1/snoop.
12. Single sign-on not occurring: This is the most common problem with TAI configuration. Try going to https://rhaalab2.raleigh.ibm.com/ssl1/snoop. Enter the wpsadmin user and password at the Access Manager form. If you get another challenge for username and password from WebSphere Portal, then it indicates that the SSO is not occurring. At this point, you should systematically follow these steps in the order given:
    • Check if the TAI class got loaded. Search in c:\WebSphere\AppServer\logs\server1\SystemOut.log for messages of the format:

      TrustAssociat A SECJ0121I: Trust Association Init class com.ibm.ws.security.web.WebSealTrustAssociationInterceptor loaded successfully [6/2/04 14:28:09:685 EDT] 4de6fe46 WebSealTrustA W SECJ0225W: PD Authentication disabled. [6/2/04 14:28:09:695 EDT] 4de6fe46 TrustAssociat A SECJ0122I: Trust Association Init Interceptor signature: WebSeal Interceptor Version 1.1

      
      
      
    • If this is not happening, then check the Application Server admin console if you marked the check box that says Trust Association and click Apply, click OK, and then save. Also check the custom entries. Check Step 10. Configure TAI in Application Server.
13. If your TAI class got loaded and you followed all the above steps, but you are not seeing single sign-on , then you need to enable TAI trace:
    • Go to the admin console: http://rhaalab1.raleigh.ibm.com:9090/admin and login using wpsbind.
    • Go to Troubleshooting => Logs and Trace => server1 (if you are troubleshooting snoop) or WebSphere_Portal (if you are troubleshooting WP => Diagnostic Trace). Check Enable trace.
    • Enter the following for trace specification: com.ibm.ws.security.*=all=enabled:com.ibm.ejs.security.*=all=enabled
      Figure 30. Diagnostic trace service
      
      
    • Click Apply, then OK , and then save. Logout.
14. Repeat your experiment once. Now take a look at your trace file. Search for the WebSEALTrust keyword for messages of the format:

    [10/16/03 21:11:05:502 EDT] 442f8f56 WebSEALTrustA d isTargetInterceptor: VIA=HTTP/1.1 RHAALAB2:443 [10/16/03 21:11:05:502 EDT] 442f8f56 WebSEALTrustA > checkVia for RHAALAB2:443 [10/16/03 21:11:05:502 EDT] 442f8f56 WebSEALTrustA < getCheckID: -1 [10/16/03 21:11:05:502 EDT] 442f8f56 WebSEALTrustA d Host and port: rhaalab2:443 is not trusted.

    
    
    
15. If you get errors of the type marked in bold, then you need to update com.ibm.websphere.security.WebSEAL.hostnames to list the hostname sent from Access Manager as the VIA keyword. The com.ibm.websphere.security.WebSEAL.hostnames file should have RHAALAB2 (note the case difference). Our hostname is all capital letters. Check the correct case for your hostname and enter it precisely in the TAI property in Application Server Admin console.
16. If you get a message: No or Bad LTPA, then regenerate the keys. Login to admin console and select Security => Authentication mechanism => LTPA => Generate Keys Click Save. See the the WebSphere Application Server Information Center for more information.
17. Single Sign-on Domain: Check the SSO Domain in the Application Server admin console. If you use an IP address for the Web server, it may not work.

Back to top

Conclusion

This paper discussed different ways in which a TAI can be configured for integrating Tivoli Access Manager with WebSphere Portal for authentication. You also learned about the potential misconfigurations possible when integrating Access Manager with Application Server. You walked through a scenario where you set up WebSphere Portal. You configured the various Access Manager components with Directory Server. You configured WebSphere Portal and Application Server for authentication using Access Manager. You also learned how to systematically troubleshoot most of the components in your topology.

Back to top

Download

Name	Size	Download method
password-authentication-samples.zip	3 KB	FTP|HTTP

Information about download methods

Resources

• IBM WebSphere V5.0 Security WebSphere Handbook Series
  
  
• IBM HTTP Server documentation
  
  
• WebSEAL Administrator's Guide
  
  
• Tivoli Access Manager installation documentation
  
  
• Tivoli Access Manager Administrator's Guide
  
  
• developerWorks Tivoli
  
  
• WebSphere Portal Information Center
  
  
• developerWorks WebSphere Portal zone
  
  
• developerWorks WebSphere Application Server zone
  
  
• developerWorks
  
  
• WebSphere Portal product documentation
  
  
• IBM Redbooks
  
  
• IBM Tivoli Directory Server library
  
  
• IBM Tivoli Directory Server installation documentation
  
  
• Browse for books on these and other technical topics.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Terminology
• Understanding a user request flow
• SSO configuration options
• Configuring Access Manager using TAI with a trusted user
• Troubleshooting
• Conclusion
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Tivoli Access Manager for Enterprise Single Sign-on
• Webcast: Achieve an Agile Organization through Enterprise Architecture
• Briefing: Introduction to Tivoli service management environment
• Buy: Tivoli Access Manager for Enterprise Single Sign-on

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers