Tivoli Access Manager for e-Business

Demonstration EAI Server README

Overview

This document describes the installation and deployment of the demonstration EAI server for WebSEAL 6.1. The demo, a J2EE application written for the WebSphere Application Server, takes advantage of WebSEAL's new External Authentication Interface and Local Response Redirect features, demonstrating how an enterprise can create a custom application to provide authentication and serve administrative pages through a WebSEAL junction. The External Authentication Interface, or EAI, feature allows for the separation of the authentication process into an application on a server protected by WebSEAL. Local Response Redirect allows for account management pages to be housed on a server separate from the WebSEAL server. These features can be used independently, but the combination of the two allows you to create a autonomous application for authentication and account management. This demo performs a simple user name mapping function that generates a credential for the same user at every login.

When users submit the demo login form, the server generates a credential for a preconfigured user with the following attributes:

• The user name input by the user attempting to log in.

• The authentication level supplied by the user.

The demo runs in two “modes,” simple and advanced. The simple demo provides the user’s credential using HTTP headers. The advanced demo provides the user’s credential in a PAC. The choice of demo mode is left to the user upon logging in, by choosing the desired radio button corresponding to the desired demo mode.

The demo is comprsied of a number of servlets and JSP pages, described below.

• JSPs
• eailogin.jsp: allows a user to enter a user name that will be used as an extended attribute, select an authentication level, and choose between the Simple and Advanced demo modes. Is also used by the built-in local response redirect handler as the login page for reauth and step up handling.
• eaiconfig.jsp: config form that allows an administrator to establish the parameters that the demo application uses to process and generate EAI authentication data. If you plan on testing this application in a multi-user environment, be sure to attach an appropriate ACL to this page!
• error.jsp: displays error information when WebSEAL's local response redirect feature reports an error operation.
• Servlets
• com.tivoli.am.eb.web.eaidemo.EAIConfigServlet: processes configuration data submitted using the eaiconfig.jsp page.
• com.tivoli.am.eb.web.eaidemo.SimpleEAIDemoServlet: processes data from eailogin.jsp and creates EAI authentication data using http headers.
• com.tivoli.am.eb.web.eaidemo.AdvancedEAIDemoServlet: processes data from eailogin.jsp and creates EAI authentication data using a PAC.
• com.tivoli.am.eb.web.localresponsedemo.TAMOperationHandler: local response redirect handler that redirects the user based on WebSEAL's local response redirect feature (see Admin Guide for more information).

Requirements

The demo EAI server requires the following components:

• WebSphere Application Server 5.1.1 or later

• TAM e-Business Java Runtime Environment

• TAM e-Business ADKs
  

Contents

The demo EAI server is shipped with the following:

• EAR file containing application binaries

• JAR file containing application sources, javadoc, and Ant build file

Installation

To install the demo EAI server, perform the following tasks. This section assumes that the WebSphere server and PDJRTE are already installed.

1. Configure the WebSphere for use with TAM as specified in the WebSphere Application Server InfoCenter (the InfoCenter provides the information required to execute the PDJrteCfg and SvrSslCfg commands).

2. The EAI Demo will need to point to its own configuration file. This is used in the creation of PDAuthznContext. Therefore, the EAI Demo will need to be configured using the SvrSslCfg command, as follows:

   On UNIX
   Run the following commands:
   touch /opt/pdwebrte/eai_demo/eaidemo.conf
   svrsslcfg -config -f /opt/pdwebrte/eai_demo/eaidemo.conf -d /opt/pdwebrte/eai_demo -n eai_demo -s remote -r 1234
   
   On Windows
   Create an empty file named 'eaidemo.conf' under the 'c:\Program Files\tivoli\pdwebrte\eai_demo' directory.
   From the command line, run the following command:
   svrsslcfg -config -f "c:\Program Files\tivoli\pdwebrte\eai_demo/eaidemo.conf" -d "c:\Program Files\tivoli\pdwebrte\eai_demo" -n eai_demo -s remote -r 1234
   

3. Locate the file DemoEAIServer.EAR. This is the Enterprise Application that must be installed on the WebSphere server. On Unix, it’s found in /opt/pdwebrte/eai_demo; on Windows, look in c:\Program Files\tivoli\pdwebrte\eai_demo.
   

4. Use the WAS Administration Console to install the EAR file. No changes need to be made in the installation wizard.

5. Start the Demo EAI Server application.

6. Create a tcp junction to the Demo EAI Server application using pdadmin.  Create an ACL that allows unauthenticated access (if one doesn't already exist).  Attach the ACL to the junction.
   

1. pdadmin> server task [WebSEAL server] create -t tcp -h [WAS hostname] -p [WAS port, usually 9080] /eai

2. pdadmin> acl create unauth

3. pdadmin> acl modify unauth set any-other Tr

4. pdadmin> acl modify unauth set unauthenticated Tr

5. pdadmin> acl modify unauth set user sec_master TcmdbsvaBRrxl

6. pdadmin> acl attach /WebSEAL/[WebSEAL server]/eai unauth

7. Configure WebSEAL for EAI as specified in the WebSEAL Developer Reference. Set the following trigger URLs in webseald.conf:

   1. eai-trigger-url = /<EAIJunction>/eaidemo/Simple*

   2. eai-trigger-url = /<EAIJunction>/eaidemo/Advanced*

8. Configure WebSEAL for local response redirect processing as specified in the WebSEAL Admin Guide. Set the following parameter in [local-response-redirect] :
   

1. local-response-redirect-url = /<EAIJunction>/eaidemo/TAMOperationHandler

9. Using a web browser, access the Demo EAI Server configuration page at [http|s]://<WebSEAL>/<EAI Junction>/eaidemo/eaiconfig.jsp

   1. Ensure that the items in the form that end with “header” match their counterparts in the WebSEAL configuration file. These are the EAI header names that the demo EAI server and WebSEAL use to transmit and consume (respectively) authentication data.

   2. Ensure that jrte-cfg-url is set to the appropriate URL of the PDJRTE configuration file. This is usually a file URL. On most UNIX platforms, the most common URL is:
      file:///opt/IBM/WebSphere/AppServer/java/jre/PdPerm.properties
      On Windows, a common URL is:
      file:///C:\Progra~1\IBM\WebSphere\AppServer\java\jre\PdPerm.properties
      

   3. Set tam-eai-user to the user you’d like all EAI logins to map to. This user must exist in the TAM registry.

   4. Set auth-level-value to the default authentication level. This can be overridden by specifying the authentication level on the demo login form.

   5. Set eai-redir-url to the URL to which clients will be redirected upon logging in. This redirection only occurs when the client has no last accessed URL.

10. Set the configuration options using the Configuration section described later in this document. Be sure to apply the changes by pressing the “Submit” button when complete.

Building the Demo EAI Server

IBM has supplied the source code for the demo EAI server as a reference EAI implementation. The source code shipped with the product is not intended to be deployed in a production environment. Instead, we hope that it will serve as an instructional source in a production EAI server implementation.

To view and build the sources, expand the EAIDemoServer.jar file in a desirable location. Use the Ant build tool and the provided Ant build file to create a new EAR file for deployment in your environment.