configure single sign-on between tivoli access manager v6.1

Configure single sign-on between Tivoli AccessManager v6.1/WebSEAL and Tivoli IntegratedPortal v1.1.xIntegrate Tivoli Access Manager v6.1/WebSEAL and TivoliIntegrated Portal to work for you

Skill Level: Intermediate

Sudhindra Rao ([email protected])Advisory software engineerIBM

Samar Choudhary ([email protected])Senior technical staff memberIBM

07 Dec 2010

This article provides detailed instructions for integrating Tivoli Access Managerversion 6.1 and Tivoli Integrated Portal version 1.1.x. Explore how to configure singlesign-on between Tivoli Access Manager/WebSEAL and Tivoli Integrated Portal usingTivoli Access Manager Extended Trust Association Interceptor (ETai). Step-by-stepinstructions and plenty of code examples walk you through the tasks.

Introduction

The advantages of integrating Tivoli Access Manager (TAM) version 6.1 and TivoliIntegrated Portal (TIP) version 1.1.x are contained in this article. Detailedinstructions show you how to configure single sign-on between Tivoli AccessManager/WebSEAL and Tivoli Integrated Portal using Tivoli Access ManagerExtended Trust Association Interceptor (ETai). You can learn how to configure theTivoli Access Manager/WebSEAL server, a Tivoli Integrated Portal junction, ajunction mapping table, and single-sign on. You can also explore trust association

Configure single sign-on between Tivoli Access Manager v6.1/WebSEAL and Tivoli Integrated Portal v1.1.x Trademarks© Copyright IBM Corporation 2010. All rights reserved. of 28

mailto:[email protected]

mailto:[email protected]

http://www.ibm.com/developerworks/ibm/trademarks/

http://www.ibm.com/legal/copytrade.shtml

and Extended Trust Association Interceptor custom properties. Troubleshooting tipsare also included.

Prerequisites

To follow along with the example configurations in this article, you need to do thefollowing prerequisite tasks:

• Install Tivoli Access Manager version 6.1, and any prerequisitesassociated with Tivoli Access Manager, on a server machine.

• Install Tivoli Integrated Portal Version 1.1 fixpack 11 and above for allTivoli Integrated Portal based products.

• Ensure the necessary ports are opened up for access from WebSEALservers to Tivoli Integrated Portal Servers. See the Tivoli Access Managerdocumentation for details.

• Check the status of the Tivoli Access Manager/WebSEAL server byrunning the pd_start status command from the command line. Theoutput should look like:

pdmgrd yes yespdacld yes no (sometimes yes)pdmgrproxyd no nowebseald-ip1 yes yes

• Verify that the LDAP registry is running with pdadmin -a sec_master-p passw0rd. The output is: pdadmin sec_master>.

• If Tivoli Access Manager processes are not started, start Tivoli AccessManager processes with pd_start start.

• Check if you are able to connect to Tivoli Access Manager.

• From a browser enter http://tam_server_hostname. You shouldsee a basic authentication dialog or a form based login screen. Input theuserid and password. You should see the Tivoli Access ManagerWebSEAL splash screen.

Deployment architecture

In typical deployment architecture, a product gets deployed into three zones, asshown in Figure 1. In the untrusted zone, an end user accesses services orapplications. In the semi-trusted zone, Tivoli Access Manager/WebSEAL (a reverseproxy server) intercepts any incoming HTTP/HTTPS requests and ensures that endusers accessing Tivoli Integrated Portal applications are authenticated and

developerWorks® ibm.com/developerWorks




authorized for the request. The request can then continue on to the necessary TivoliIntegrated Portal applications deployed in the trusted zone.

All the Tivoli Integrated Portal based products have to be installed on a singleinstance of Tivoli Integrated Portal for integration with Tivoli Access Manager.

Figure 1. Deployment architecture

Restrictions of Tivoli Integrated Portal-Tivoli Access Manager deploymentarchitecture

The current deployment architecture for Tivoli Integrated Portal-Tivoli AccessManager has restrictions on deploying one WebSEAL server instance and mappingit to one Tivoli Integrated Portal server. Installing multiple Tivoli Integrated Portalservers and handling requests via one single WebSEAL server is restricted in thisdesign.

Configuring Tivoli Access Manager/WebSEAL server

To secure transport between Tivoli Access Manager and Tivoli Integrated Portal, aTivoli Integrated Portal signer and default certificate should be in the Tivoli AccessManager keystore. This is a prerequisite for Tivoli Integrated Portal junctionconfiguration.

Import Tivoli Integrated Portal certificate into WebSEAL keystore

To export a Tivoli Integrated Portal certificate:

ibm.com/developerWorks developerWorks®




1. Log in to Tivoli Integrated Portal using Firefox. Double-click the lock iconin the lower right of the browser window; the Page Info window's Securitysection should appear.Click View Certificate, which brings up the Certificate window.

2. Select the Details tab.

3. Click Export to export to the local file system. This exports TivoliIntegrated Portal's X.509 certificate.

4. Transfer the certificate to the Tivoli Access Manager machine.

5. Import the Tivoli Integrated Portal certificate into Tivoli Access Manager:

• Start X server in the Tivoli Access Manager machine, if not alreadystarted, using the startx or gdm command.

• Launch IKeyMan (./ikeyman.sh).

1. Click Open on the toolbar.

2. Select Key database type: CMS, click Browse, and go to/var/pdweb/www-ip1/certs.

3. Select pdsrv.kdb, which launches the Password Promptwindow. The default password is the same as the filename:pdsrv.

4. Select Signer Certificates in the Key database contentsection.

5. Click Add, which launches Add CA's Certificate from a Filewindow.

6. Select Data type: Base64-encoded ASCII data.

7. Click Browse.

8. Select the exported certificate from Tivoli Integrated Portal.

9. Enter a label for the certificate, such as tipmachine.

10. Click Save to save the keystore (use the same file name).

Configuring a Tivoli Integrated Portal junction





A WebSEAL junction is an HTTP or HTTPS connection between a front-endWebSEAL server and a back-end Tivoli Integrated Portal server. Junctions logicallycombine the web space of the back-end Tivoli Integrated Portal server with the webspace of the WebSEAL server, resulting in a unified view of the entire web objectspace. A junction lets WebSEAL provide protective services on behalf of theback-end server. WebSEAL performs authentication and authorization checks on allrequests for resources before passing those requests across a junction to theback-end server. Use the steps below to configure a Tivoli Integrated Portal junctionthat primarily uses SSL as secured transport between WebSEAL and TivoliIntegrated Portal server communications.

1. Create a Tivoli Integrated Portal junction by starting the pdadmin utilityfrom the command line: pdadmin -a sec_master -p passw0rdwhere:sec_master = the root useridpassw0rd = the password for sec_masterFrom the padadmin prompt, run the following command to create ajunction:

s t ip1-webseald-ip1 create -t ssl -c iv-creds -b supply -h <tip_hostname/ip> -p<tip_admin_console_secure_port> /tip

where:s t = server taskip1-webseal-ip1 = WebSEAL instance name-t ssl = transport is SSL-c iv-creds = needed for SSO to work; carries credential of the user-b supply = basic authentication header needed for SSO to work.

2. Display the Tivoli Integrated Portal junction by starting the pdadmin utilityfrom the command line:

pdadmin -a sec_master -p passw0rd

where:sec_master = the root useridpassw0rd = the password for sec_master

From the padadmin prompt, run the command:s t ip1-webseald-ip1 show /tip





Configuring a junction mapping table

Server-relative URLs generated on the client side by Tivoli Integrated Portal initiallylack knowledge of the junction point. WebSEAL cannot filter the URL because it isgenerated on the client side.

During a client request for a resource using this URL, WebSEAL can attempt toreprocess the server-relative URL using a junction mapping table (JMT). A JMTmaps specific target resources to junction names. Junction mapping is an alternativeto the cookie-based solution for filtering dynamically generated server-relative URLs.

WebSEAL checks the location information in the server-relative URL with the datacontained in the JMT. WebSEAL begins searching at the top of the table andcontinues downward. If the path information in the URL matches any entry in thetable during the top-down search, WebSEAL directs the request to the junctionassociated with that location.

The table is an ASCII text file called jmt.conf. The location of the file is specified inthe [junction] stanza of the WebSEAL configuration file: jmt-map =lib/jmt.conf.

According to the property comments, this path is relative to the server-root value.Check the server-root value under the server stanza. For example, server-root= /opt/pdweb/www-ip1.

Create a JMT using the jmt.conf file, as follows:

• Create a new file, jmt.conf, under the <server-root>/ directory.Add the following entries to this file and save it.

/tip /ibm/console/*/tip /ibm/sla/*/tip /TCR/reports/*

Load the JMT in WebSEAL using the command:

s t ip1-webseald-ip1 jmt load. The output is:DPWWM1462I JMT Table successfully loaded

• Restart the WebSEAL server using the command: pdweb restart.The output is:

Stopping the: webseald-ip1





Starting the: webseald-ip1

Changes to IBM Tivoli Network Manager (ITNM)

With Tivoli Network Manager you need to specify the WebTop URL. There is afacility already in the codebase to override the WebTop URL using a property. Thisproperty will aid in displaying WebTop Applets.

• Directory: {ITNM_INSTALL_DIR}/tip/profiles/TIPProfile/etc/tnm/

• Property file: tnm.properties

• Property: tnm.webtop.url

This should be set as:

https://{TAM WebSEAL server}/{WebSEAL junction name}/ibm/webtop

For example, for the test environment above, the following property is added.

tnm.webtop.url=https://9.196.131.76/tip/ibm/webtop

Testing junction mappings

To test the junction mappings, launch your browser using https://<TAM_HostName>/tip/ibm/console where /tip is the junction name.

The output in the browser should be:

https://<TAM_Host Name>/tip/ibm/console/logon.jsp

An Authentication Required window is displayed. Input the Tivoli Access Managercredentials: userid and password. The request should be redirected to the TivoliIntegrated Portal login page.

Configuring single sign-off Tivoli Integrated Portal

Logging out from the Tivoli Integrated Portal console also logs out the user sessionin Tivoli Integrated Portal and in Tivoli Access Manager. To enable this singlesign-off, use the following configuration.





Edit customizationProperties.xml, which is at<TIP_HOME>/profiles/TIPProfile/config\cells\TIPCell\applications\isclite.ear\deployments\isclite\isclite.war\WEB-INF . Enter<consoleproperties:console-property id="TAMJunctionName"value="tip"/> where TAMJunctionName is the junction name configured inTivoli Access Manager that points to the Tivoli Integrated Portal Server.

If the value for the above property is blank, Tivoli Access Manager virtual hostjunction is assumed. If there is a value specified for the above property, then TivoliIntegrated Portal assumes it's a Tivoli Access Manager traditional junction.

The output message Successful Logout will be displayed in the browser.

Managing requests into the Tivoli Integrated Portal server

You can configure Tivoli Integrated Portal to allow requests only from certain hostsand servers, letting you control access to the Tivoli Integrated Portal server. Thisfeature is useful for servers that are installed in trusted or non-trusted zones.

A script is shipped in:

<TIP_HOME>/bin directory called includeHostNames.py < options>

The script options include:

showHostNames Lists the host names that are allowed to accessthe Tivoli Integrated Portal server.

createHostNames Specifies the list of host names, separated by the; delimiter, to access the Tivoli Integrated Portalserver.

resetHostNames Specifies the list of host names, separated by the; delimiter, to remove the host names that isregistered to access the Tivoli Integrated Portalserver.

To execute the script, enter the following command:

<TIP_HOME>/bin/wsadmin.sh/bat -username tipadmin -password tippass -fincludeHostnames.py <options> hostnames (separated by ;)

where:

options = a list of options specified above.TIP_HOME = the Tivoli Integrated Portal installation directory.





Tivoli Integrated Portal/Tivoli Access Manager single sign-on

In a deployed Tivoli Integrated Portal/embedded WebSphere Application Server,there are various methods that allow for single sign-on (SSO) of the authenticateduser where the credential is passed from WebSEAL to the downstream WebSphereApplication Server servers. The user thus does not need to reauthenticate at anytime.

The next section describes a component, called the Tivoli Access ManagerExtended Trust Association Interceptor (ETai), that implements the WebSphereApplication Server trust association interceptor interface to achieve SSO fromWebSEAL to Tivoli Integrated Portal/embedded WebSphere Application Server.

Trust association

Tivoli Integrated Portal/embedded WebSphere Application Server 6.1 supports SSOwith perimeter authentication services, such as reverse proxies through trustassociations. When trust associations are enabled, WebSphere Application Server isnot required to authenticate a user if a request arrives via a trusted source that hasalready performed authentication. The perimeter authentication service is expectedto:

• Establish trust with WebSphere Application Server.

• Perform user authentication.

• Insert user credential information into HTTP requests.

The Trust Association Interceptor (TAI) is the module in WebSphere ApplicationServer that handles the trust association. It is a "pluggable" module, whoseresponsibilities include:

• Validation of trust with the perimeter authentication service.

• Extraction of credential information from the request.

Tivoli Access Manager Extended Trust Association Interceptor and TivoliIntegrated Portal/Tivoli Access Manager WebSEAL integration

Tivoli Integrated Portal will support SSO between Tivoli Access Manager/WebSEALand the Tivoli Integrated Portal server. End users can login once to Tivoli AccessManager and WebSEAL will redirect the request to the Tivoli Integrated Portal serverwithout having to log into Tivoli Integrated Portal. The Tivoli Access ManagerExtended Trust Association Interceptor will be configured in the Tivoli IntegratedPortal/embedded WebSphere Application Server and will be responsible for





establishing trust against the Tivoli Access Manager/WebSEAL server.

Tivoli Access Manager Extended Trust Association Interceptor simplifies use ofTivoli Access Manager and simplifies the configuration and setup to achieve SSO.One big advantage is that Tivoli Access Manager/Tivoli Integrated Portal can usedifferent user registries and still perform SSO. Tivoli Access Manager/TivoliIntegrated Portal provided the mapping between different registry formats. You canalso configure Tivoli Integrated Portal/Tivoli Access Manager to share a single userregistry (though that configuration is outside the scope of this article).

WebSEAL and Tivoli Integrated Portal/embedded WebSphere ApplicationServer TAI interaction

Figure 2 shows the flow of an HTTP request to WebSphere Application Server viaWebSEAL and the Extended Trust Association Interceptor. This is just the defaultuse of the Extended Trust Association Interceptor.

Figure 2. Tivoli Access Manager trust association flow

The numbers in the figure above correspond to the flow described below.

1. The user encounters WebSEAL (possibly through other proxies) and isprompted to authenticate.





2. WebSEAL authenticates the user, acquires credentials for the user fromthe user registry, and possibly authorizes the request.

3. WebSEAL augments the request with an additional HTTP header(iv-creds) that contains the user's credentials.The password contained in the basic authentication (BA) header ischanged so it matches a configured SSO user, and the request is sent toWebSphere Application Server.

4. Tivoli Integrated Portal/embedded WebSphere Application Serverreceives the request and calls a TAI method (isTargetInterceptor)to determine if the request is from a perimeter authentication service thathas already authenticated the user.

5. Tivoli Integrated Portal/embedded WebSphere Application Server calls aTAI method (negotiateValidateandEstablishTrust) to:

• Establish trust with the perimeter authentication server.This method establishes trust with WebSEAL by checking that the BAheader contains the correct password for the configured SSO user.Trust between WebSEAL and WebSphere Application Server cannotbe established using mutually authenticated SSL sessions; it can onlybe established by verifying the SSO password. No checking ofcertificates is performed by the TAI.

• Retrieve the credentials.The iv-creds header is then extracted from the request and used toretrieve: the short name of the WebSEAL authenticated user, and thecredential object containing user and group information.

6. Return the authenticated user information.At this point, WebSphere Application Server has valid credentials that itcan use for making authorization decisions in the usual J2EE manner.

Some important points to note:

• WebSEAL must insert the iv-creds header into the request.

• In step 5, the new TAI is configurable to authenticate trust using either theTivoli Access Manager authorization server or the WebSphere ApplicationServer user registry directly.The user information that is extracted from the iv-creds header can have





the DN format mapped from the initial format into the required format ofthe WebSphere Application Server user registry.

• The credential object inserted into the subject by the TAI meansWebSphere Application Server does not have to perform any additionaluser registry searches as part of the authentication process.

SSO configuration in Tivoli Integrated Portal: Configuring Tivoli IntegratedPortal/embedded WebSphere Application Server

This section describes the three related configuration tasks that you must do in TivoliIntegrated Portal/embedded WebSphere Application Server to allow the correctoperation of the Extended Trust Association Interceptor.

• Enable trust association

• Add the Extended Trust Association Interceptor as a known interceptor

• Add the required configuration properties for the Extended TrustAssociation Interceptor to behave as desired

Enabling trust associationThe first step is to traverse to the trust association screen in the console.

1. From the Tivoli Integrated Portal console:

• Expand Security, select Secure administration, applications, andinfrastructure

• Expand Web security and click Trust association, as shown inFigure 3.

Figure 3. Tivoli Integrated Portal Security page





2. Enable trust association must be checked. Check it if it is not alreadychecked, and click Apply.

3. Save the configuration changes.

Adding the Extended Trust Association Interceptor as an interceptorThis section sequentially follows the section above. If used in isolation, you shouldread Enabling trust association to learn how to traverse to the Trust associationpage in the WebSphere Application Server admin console.

1. Start at the Trust association screen.

2. Click Interceptors.Figure 4. Trust association





3. If the com.ibm.sec.authn.tai.TAMETai is not defined, select New.On the following screen, enter com.ibm.sec.authn.tai.TAMETaiinto the Interceptor class name field and click Apply.

4. Save the configuration changes.

Adding custom properties to Tivoli Access Manager Extended TrustAssociation InterceptorTo add custom properties to Tivoli Access Manager Extended Trust AssociationInterceptor, start at the Interceptors screen.

1. Select the Interceptor class name com.ibm.sec.authn.tai.Tivoli AccessManagerETai, as shown in Figure 5.

2. Go to the Custom properties screen.

3. From the Tivoli Integrated Portal console click Custom properties.Figure 5. Define Interceptor class name





4. For each required property that is not defined, click New then enter therequired Name and Value. Click Apply. Figure 6 shows an example.Figure 6. Define custom property

The result should be the Custom property definition, as shown below.

Figure 7. Custom property for Extended Trust AssociationInterceptor





5. If the custom property already exists but does not contain the correctName, Value, and Description, select that property, make necessarychanges, and click Apply.

6. Repeat for all required properties as defined in Extended TrustAssociation Interceptor custom properties.

7. When all properties are set, you should see a list similar to Figure 8 (with10 custom properties).Figure 8. Custom property list





8. Save the configuration changes, and restart the Tivoli Integrated Portalserver.Figure 9. Save configuration





Extended Trust Association Interceptor custom properties

This section describes all of the mandatory and optional configuration properties andany interactions that the properties have with one another.

com.ibm.websphere.security.webseal.useWebSphereUserRegistryAllowed values: String true or false

Description: This property is used to determine whether theExtended Trust Association Interceptor willauthenticate the trusted user against theWebSphere Application Server user registry orthe Tivoli Access Manager authorization server.If this property is set to true, the resulting Subjectwill not contain a PDPrincipal, as the TivoliAccess Manager authorization server is requiredto build the PDPrincipal. Any other value for thisproperty will result in a PDPrincipal being addedto the Subject.

Required: This property is mandatory. It is recommendedthat you use differing registries.

Default Value: False

com.ibm.websphere.security.webseal.tamUserDnMappingValue: WebSphere Application Server

Description: The Extended Trust Association Interceptor willadd the users credential information into theJAAS Subject. This information includes theusers DN. Map this DN to the WebSphereApplication Server DN, or (Value = WebSphereApplication Server).If a mapping is attempted for a user that does notexist in the WebSphere Application Server userregistry, it will be ignored and not added to theJAAS Subject.

Required: This property should be specified.

Default value: Tivoli Access Manager

com.ibm.websphere.security.webseal.tamGroupDnMappingAllowed values: WebSphere Application Server

Required. This property should be specified.

Description: The Extended Trust Association Interceptor willadd the user's credential information into theJAAS Subject. This information includes the





group DNs. The Extended Trust AssociationInterceptor can be configured to map these DNsto either the WebSphere Application Server DNsor to (Value = WebSphere Application Server).If a mapping is attempted for a group that doesnot exist in the WebSphere Application Serveruser registry, it will be ignored and not added tothe JAAS Subject.

Default value: Tivoli Access Manager

com.ibm.websphere.security.webseal.loginIdAllowed values: Any string. Create a new user in the Tivoli

Integrated Portal registry called websealSSOID.Note that this user can reside in the file basedregistry that Tivoli Integrated Portal configuresout of the box. (You could use the TivoliIntegrated Portal console to create a user fromManage User.)Required. This property should be specified.

Description: The ETAI must be configured with the usernameof the WebSEAL trusted user. This is the SSOuser that will be authenticated using thepassword in the BA header inserted byWebSEAL in the request. The format of theusername is the short name representation.

Interaction with other properties: com.ibm.websphere.security.webseal.useWebSphereUserRegistryThe value of this property must exist as a validuser in the user registry. IfuseWebSphereUserRegistry is set to true,then the user must exist in the WebSphereApplication Server user registry (or in the TivoliAccess Manager user registry).

Default value: There is no default value for this property. If itdoes not exist, Extended Trust AssociationInterceptor initialization will fail.

com.ibm.websphere.security.webseal.checkViaHeaderValues: String true


Description: The Extended Trust Association Interceptor canbe configured so the Via header can be ignoredwhen validating trust for a request. This propertyis necessary if Tivoli Access Manager/WebSEALwants to allow requests into Tivoli IntegratedPortal only from certain hosts. TSA has a





requirement on this.

Interaction with other properties: com.ibm.websphere.security.webseal.hostnamescom.ibm.websphere.security.webseal.portsIf the checkViaHeader property is set tofalse, none of the values of the other propertieswill have any effect on the operation of theExtended Trust Association Interceptor.

Default value: false

com.ibm.websphere.security.webseal.idAllowed values: iv-creds

Required. This is a mandatory property used forSSO.

Description: Iv-creds carry end user credentials, which areused by Tivoli Integrated Portal/embeddedWebSphere Application Server to makeauthorization decisions.

Default value: iv-credsAny other values set with this property will beadded to a list along with iv-creds. iv-creds willalways be a required header for the ExtendedTrust Association Interceptor.

com.ibm.websphere.security.webseal.hostnamesAllowed values: A comma-separated list of any strings

Description: The Extended Trust Association Interceptor canbe configured so the request must arrive via a listof expected hosts. If any of the hosts in the Viaheader of the HTTP request are not listed in thevalue of this property, the request will be ignoredby the Extended Trust Association Interceptor.

Interaction with other properties: com.ibm.websphere.security.webseal.ports:All of the values listed in hostnames will be usedalongside all of the ports listed in this property toindicate a trusted host. For example:Hostnames = abc,xyzPorts = 80,443The Via header will be checked for abc:80,abc:443, xyz:80 or xyz:443.

com.ibm.websphere.security.webseal.checkViaHeader:

If this property is false then the hostnamesproperty will have no effect on the ExtendedTrust Association Interceptor operation.





Default value: There is no default value for this property. IfcheckViaHeader is set to true and thisproperty is not set, then Extended TrustAssociation Interceptor initialization will fail.

com.ibm.websphere.security.webseal.portsAllowed values: 443

Description: This property is used alongside the hostnamesproperty to indicate which hosts in the Via headerare trusted sources. If the ports of the hosts inthe Via header are not listed in the value of thisproperty, the request will be ignored by theExtended Trust Association Interceptor.

Required: This is a mandatory property.

Interaction with other properties: com.ibm.websphere.security.webseal.hostnames:All of the values listed in hostnames will be usedalongside all of the ports listed in this property toindicate a trusted host. For example:Hostnames = abc,xyzPorts = 80,443The Via header will be checked for abc:80,abc:443, xyz:80 or xyz:443.

com.ibm.websphere.security.webseal.checkViaHeader:

If this property is false then the ports propertywill have no effect on the Extended TrustAssociation Interceptor operation.

Default value: There is no default value for this property. IfcheckViaHeader is set to true and thisproperty is not set, then Extended TrustAssociation Interceptor initialization will fail.

com.ibm.websphere.security.webseal.ssoPwdExpiryAllowed values: A positive integer

Description: Once trust has been established for a request,the password for the SSO user is cached forsubsequent trust validation of requests. Thissaves the Extended Trust Association Interceptorfrom having to reauthenticate the SSO user withthe user registry for every request -- therebyincreasing performance.The cache timeout period can be modified bysetting this property to the required time, inseconds. If the password expiry property is set to0, the cached password will never expire.

If the password expiry is set to a negative value,





the TAI initialization will fail.

Interaction with other properties: None

Default value: 600

com.ibm.websphere.security.webseal.groupRealmPrefixAllowed values: “group:”


Description: This property is needed to map the group realmprefix from Tivoli Access Manager to the grouprealm prefix in the WebSphere registry.Required. This is a mandatory property.

com.ibm.websphere.security.webseal.userRealmPrefixAllowed values: “user:”


Description: This property is needed to map the user realmprefix from Tivoli Access Manager to the userrealm prefix in the WebSphere registry.This is a mandatory property.

Restart the Tivoli Integrated Portal server after all of the custom properties aboveare saved.

Tivoli Access Manager WebSEAL

For the Extended Trust Association Interceptor to accept requests from WebSEAL,you need to do the following tasks on the WebSEAL server to ensure that anExtended Trust Association Interceptor targeted HTTP request is sent.

1. Create the junction with the required parameters.

2. Create a trusted SSO user.

3. Set the dummy password in the configuration file.

Required junction parameters

There are many parameters available when creating a junction in WebSEAL. The





two that are required by the Extended Trust Association Interceptor are:

–b supplyEnsures that WebSEAL passes the BA header in the HTTP request. TheExtended Trust Association Interceptor requires the dummy password in theBA header; the username is not used.

–c iv-credsEnsures that WebSEAL passes the logged in user's credential in an iv-credsheader in the HTTP request. The Extended Trust Association Interceptorrequires this header or it will not handle the request. Other headers can also bepassed, such as iv-user, but the iv-creds header must also be passed.

The following example shows how to create a junction in WebSEAL 6.1.

server task "webseal_instance_name" create -b supply -c iv-creds -t tcp -h "websphere_hostname" -p"websphere_app_port_number" "junction_name"

Create a trusted SSO user

The Extended Trust Association Interceptor requires a user to exist in the userregistry that will be used to authenticate trust. This user and their password willbecome the central part of establishing trust between WebSEAL and WebSphereApplication Server. The value of the custom propertycom.ibm.websphere.security.webseal.loginId will be set to this user, and the dummypassword in WebSEAL will be set to this user's password.

• If the custom propertycom.ibm.websphere.security.webseal.useWebSphereUserRegistry is notset to true, this user must be created in the Tivoli Access Manager userregistry. You can do so using the pdadmin utility.For example, to create a user using pdadmin in Tivoli Access Manager5.1:

user create sso cn=sso,o=ibm,c=au sso sso ssopwduser modify ssouser account-valid yes

• If the custom propertycom.ibm.websphere.security.webseal.useWebSphereUserRegistry is setto true, this user must be created in the WebSphere Application Serveruser registry. (See the WebSphere Application Server Info Center fordetails.)

Set the dummy password





WebSEAL provides a mechanism for predetermining the password that's passed inthe basic authentication header of the HTTP request. Set the dummy password inthe WebSEAL instance configuration file using the –b supply parameter describedin Required junction parameters. The configuration file to update,webseald-instancename.conf, is in your webseal_home/etc directory.

For example, if your WebSEAL instance is named default and WebSEAL is installedon Windows, the file will be:

C:\program files\tivoli\pdweb\wetc\webseald-default.conf

Open this file, search for basicauth-dummy-passwd, and change the value of thisproperty to the password of the trusted SSO user. Save the file and restart yourWebSEAL instance so the new property value will take effect.

Troubleshooting

This section outlines a few of the common problems encountered when using theExtended Trust Association Interceptor.

• Problem: After enabling the Extended Trust Association Interceptor, arestart of WebSphere Application Server showsClassNotFoundException or ClassDefNotFoundError.Common causes

The com.ibm.sec.authn.tai.etai_6.0.jar has not been placed in the classpath.Or, on WebSphere Application Server 6.1, the osgiCfgInit script has not beenrun after placing the JAR in the plug-ins directory of the WebSphere ApplicationServer home directory.

SolutionMake sure the JAR has been added to the correct location and the osgiCfgInitscript has been run.

• Problem: Single sign-on does not work. The user is prompted to login toboth WebSEAL and WebSphere Application Server.Common causes

The WebSEAL junction has not been set up to pass the iv-creds header. Thisis a mandatory requirement for the Extended Trust Association Interceptor.The WebSEAL junction has not been set up to pass the BA header. This is amandatory requirement for the Extended Trust Association Interceptor.

The authentication of the trusted user specified in the





com.ibm.websphere.security.webseal.loginId property fails, possibly because:

• The dummy password has not been set correctly in the WebSEALconfiguration.

• The WebSEAL instance has not been restarted after the dummypassword was set.

• The password for the trusted user has expired.The request has come via hosts or ports that are not listed in the hostnamesand ports configuration properties.

The Extended Trust Association Interceptor has not initialized correctlybecause a mandatory property was not set correctly.

Solutions

• Make sure the junction passes both the iv-creds and BA header.

• Ensure that the trusted user and dummy password are valid.

• Ensure that the WebSEAL instance has been restarted.

• Ensure that all hosts and ports in the Via header are set in therelevant properties, or set the viaDepth and checkViaHeaderproperties as required.

• Check the log files to see why the initialization is failing. Search forTivoli Access Manager Extended Trust Association Interceptor in theSystemOut.log.

• Problem: How to enable trace for Tivoli Access Manager Extended TrustAssociation Interceptor. The trace specification required for the ExtendedTrust Association Interceptor is:

com.ibm.sec.authn.tai.*=all

Once this is set, you can inspect the trace.log for errors or send it to IBMSupport for review of any problems. It is also useful for IBM Support tohave the trace for the WebSphere Application Server security webcomponent. Use the following trace specification to get both.

com.ibm.ws.security.web.*=all:com.ibm.sec.authn.tai.*=all





Resources

Learn

• Learn all about the features and benefits of Tivoli Access Manager forenterprise single sign-on.

• Tivoli Integrated Portal: Read about this converged platform for Tivoli products.

• Read more about WebSEAL authentication and WebSEAL junctions.

• Configuring custom properties for ETai: Get step-by-step instructions.

• AIX and UNIX developerWorks zone: Find a wealth of information relating to allaspects of AIX systems administration and expanding your UNIX skills.

• Browse the technology bookstore for books on these and other technical topics.

Get products and technologies

• IBM trial software: Build your next development project with software fordownload directly from developerWorks.

Discuss

• Participate in the discussion forum for this content.

• Create your My developerWorks profile today and setup a watchlist on TivoliAccess Manager, Tivoli Integrated Portal, or WebSEAL. Get connected andstay connected with My developerWorks.

• Participate in the developerWorks blogs and get involved in the developerWorkscommunity.

• Follow developerWorks on Twitter.

About the authors

Sudhindra RaoSudhindra Rao is a software development engineer with 13 yearsexperience producing successful commercial software with a focus onmiddleware (application server and systems management), security,and web based visualization. His specialities include J2EE, applicationsecurity, event processing, business service management, webtechnology, technical leadership, and working with users to developprototypes and architecture. Sudhindra is currently a security architectfor the Tivoli Integrated Portal, where he's designing security integrationand deployment architecture.



http://www-01.ibm.com/software/tivoli/products/access-mgr-esso/

http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp?topic=/com.ibm.tip.doc/ttip_config_etai_configure.html

http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?topic=%2Fcom.ibm.itame2.doc_5.1%2Fam51_webseal_guide15.htm

http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/index.jsp?topic=/com.ibm.tip.doc/ttip_config_etai_configure.html

http://www.ibm.com/developerworks/aix/

http://www.ibm.com/developerworks/apps/SendTo?bookstore=safari

http://www.ibm.com/developerworks/downloads/?S_TACT=105AGY06&S_CMP=art

http://www.ibm.com/developerworks/forums/dw_forum.jsp?forum=375&cat=5

https://www.ibm.com/developerworks/mydeveloperworks/profiles/home.do?lang=en

https://www.ibm.com/developerworks/mydeveloperworks/homepage/help/doc/en/homepage_watchlistuse.html

http://www.ibm.com/developerworks/mydeveloperworks/#community

https://www.ibm.com/developerworks/mydeveloperworks/blogs/?lang=en

http://twitter.com/developerworks



Samar ChoudharyDr. Samar Choudhary has been involved with several softwaretechnologies over the years, including 3D graphics, WebsphereApplication Server, and WebSphere Portal. His specialties include userinterfaces, security, and other run-time aspects. Dr. Choudhary hasmore than 10 publications, and has more than 20 patents issued orfiled. Most recently he is an architect for cloud computing on aspects ofthe user interface and provisioning.





configure single sign-on between tivoli access manager v6.1

Documents