Configure single sign-on between Tivoli Access Manager v6.1/WebSEAL and Tivoli Integrated Portal v1.1.x
The advantages of integrating Tivoli Access Manager (TAM) version 6.1 and Tivoli Integrated Portal (TIP) version 1.1.x are contained in this article. Detailed instructions show you how to configure single sign-on between Tivoli Access Manager/WebSEAL and Tivoli Integrated Portal using Tivoli Access Manager Extended Trust Association Interceptor (ETai). You can learn how to configure the Tivoli Access Manager/WebSEAL server, a Tivoli Integrated Portal junction, a junction mapping table, and single-sign on. You can also explore trust association and Extended Trust Association Interceptor custom properties. Troubleshooting tips are also included.
To follow along with the example configurations in this article, you need to do the following prerequisite tasks:
- Install Tivoli Access Manager version 6.1, and any prerequisites associated with Tivoli Access Manager, on a server machine.
- Install Tivoli Integrated Portal Version 1.1 fixpack 11 and above for all Tivoli Integrated Portal based products.
- Ensure the necessary ports are opened up for access from WebSEAL servers to Tivoli Integrated Portal Servers. See the Tivoli Access Manager documentation for details.
- Check the status of the Tivoli Access Manager/WebSEAL server by running the
pd_start status command from the command line. The output should look like:
pdmgrd yes yes pdacld yes no (sometimes yes) pdmgrproxyd no no webseald-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 Access Manager 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 should see a basic authentication dialog or a form based login screen. Input the userid and password. You should see the Tivoli Access Manager WebSEAL splash screen.
In typical deployment architecture, a product gets deployed into three zones, as shown in Figure 1. In the untrusted zone, an end user accesses services or applications. In the semi-trusted zone, Tivoli Access Manager/WebSEAL (a reverse proxy server) intercepts any incoming HTTP/HTTPS requests and ensures that end users accessing Tivoli Integrated Portal applications are authenticated and authorized for the request. The request can then continue on to the necessary Tivoli Integrated Portal applications deployed in the trusted zone.
All the Tivoli Integrated Portal based products have to be installed on a single instance of Tivoli Integrated Portal for integration with Tivoli Access Manager.
Figure 1. Deployment architecture
Restrictions of Tivoli Integrated Portal-Tivoli Access Manager deployment architecture
The current deployment architecture for Tivoli Integrated Portal-Tivoli Access Manager has restrictions on deploying one WebSEAL server instance and mapping it to one Tivoli Integrated Portal server. Installing multiple Tivoli Integrated Portal servers and handling requests via one single WebSEAL server is restricted in this design.
Configuring Tivoli Access Manager/WebSEAL server
To secure transport between Tivoli Access Manager and Tivoli Integrated Portal, a Tivoli Integrated Portal signer and default certificate should be in the Tivoli Access Manager keystore. This is a prerequisite for Tivoli Integrated Portal junction configuration.
Import Tivoli Integrated Portal certificate into WebSEAL keystore
To export a Tivoli Integrated Portal certificate:
- Log in to Tivoli Integrated Portal using Firefox. Double-click the lock icon in the lower right of the browser window; the Page Info window's Security section should appear.
Click View Certificate, which brings up the Certificate window.
- Select the Details tab.
- Click Export to export to the local file system. This exports Tivoli Integrated Portal's X.509 certificate.
- Transfer the certificate to the Tivoli Access Manager machine.
- Import the Tivoli Integrated Portal certificate into Tivoli Access Manager:
- Start X server in the Tivoli Access Manager machine, if not already started, using the
startx or gdm command.
- Launch IKeyMan (
./ikeyman.sh).
- Click Open on the toolbar.
- Select Key database type: CMS, click Browse, and go to
/var/pdweb/www-ip1/certs.
- Select pdsrv.kdb, which launches the Password Prompt window. The default password is the same as the filename: pdsrv.
- Select Signer Certificates in the Key database content section.
- Click Add, which launches Add CA's Certificate from a File window.
- Select Data type: Base64-encoded ASCII data.
- Click Browse.
- Select the exported certificate from Tivoli Integrated Portal.
- Enter a label for the certificate, such as
tipmachine.
- 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-end WebSEAL server and a back-end Tivoli Integrated Portal server. Junctions logically combine the web space of the back-end Tivoli Integrated Portal server with the web space of the WebSEAL server, resulting in a unified view of the entire web object space. A junction lets WebSEAL provide protective services on behalf of the back-end server. WebSEAL performs authentication and authorization checks on all requests for resources before passing those requests across a junction to the back-end server. Use the steps below to configure a Tivoli Integrated Portal junction that primarily uses SSL as secured transport between WebSEAL and Tivoli Integrated Portal server communications.
- Create a Tivoli Integrated Portal junction by starting the
pdadmin utility from the command line: pdadmin -a sec_master -p passw0rd where:
sec_master = the root userid
passw0rd = the password for sec_masterFrom the padadmin prompt, run the following command to create a junction:
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 task
ip1-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.
- Display the Tivoli Integrated Portal junction by starting the pdadmin utility from the command line:
pdadmin -a sec_master -p passw0rd
where:
sec_master = the root userid
passw0rd = the password for sec_masterFrom 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 initially lack knowledge of the junction point. WebSEAL cannot filter the URL because it is generated on the client side.
During a client request for a resource using this URL, WebSEAL can attempt to reprocess the server-relative URL using a junction mapping table (JMT). A JMT maps specific target resources to junction names. Junction mapping is an alternative to the cookie-based solution for filtering dynamically generated server-relative URLs.
WebSEAL checks the location information in the server-relative URL with the data contained in the JMT. WebSEAL begins searching at the top of the table and continues downward. If the path information in the URL matches any entry in the table during the top-down search, WebSEAL directs the request to the junction associated with that location.
The table is an ASCII text file called jmt.conf. The location of the file is specified in the [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 a facility already in the codebase to override the WebTop URL using a property. This property 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
To test the junction mappings, launch your browser using https://<TAM_Host Name>/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 Manager credentials: userid and password. The request should be redirected to the Tivoli Integrated Portal login page.
Configuring single sign-off Tivoli Integrated Portal
Logging out from the Tivoli Integrated Portal console also logs out the user session in Tivoli Integrated Portal and in Tivoli Access Manager. To enable this single sign-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 in Tivoli Access Manager that points to the Tivoli Integrated Portal Server.
If the value for the above property is blank, Tivoli Access Manager virtual host junction is assumed. If there is a value specified for the above property, then Tivoli Integrated 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 hosts and servers, letting you control access to the Tivoli Integrated Portal server. This feature 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:
showHostNamesLists the host names that are allowed to access the Tivoli Integrated Portal server.
createHostNamesSpecifies the list of host names, separated by the ; delimiter, to access the Tivoli Integrated Portal server.
resetHostNamesSpecifies the list of host names, separated by the ; delimiter, to remove the host names that is registered to access the Tivoli Integrated Portal server.
To execute the script, enter the following command:
<TIP_HOME>/bin/wsadmin.sh/bat -username tipadmin -password tippass -f includeHostnames.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 authenticated user where the credential is passed from WebSEAL to the downstream WebSphere Application Server servers. The user thus does not need to reauthenticate at any time.
The next section describes a component, called the Tivoli Access Manager Extended Trust Association Interceptor (ETai), that implements the WebSphere Application Server trust association interceptor interface to achieve SSO from WebSEAL to Tivoli Integrated Portal/embedded WebSphere Application Server.
Tivoli Integrated Portal/embedded WebSphere Application Server 6.1 supports SSO with perimeter authentication services, such as reverse proxies through trust associations. When trust associations are enabled, WebSphere Application Server is not required to authenticate a user if a request arrives via a trusted source that has already performed authentication. The perimeter authentication service is expected to:
- 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 Application Server that handles the trust association. It is a "pluggable" module, whose responsibilities include:
- Validation of trust with the perimeter authentication service.
- Extraction of credential information from the request.
Tivoli Integrated Portal will support SSO between Tivoli Access Manager/WebSEAL and the Tivoli Integrated Portal server. End users can login once to Tivoli Access Manager and WebSEAL will redirect the request to the Tivoli Integrated Portal server without having to log into Tivoli Integrated Portal. The Tivoli Access Manager Extended Trust Association Interceptor will be configured in the Tivoli Integrated Portal/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 of Tivoli Access Manager and simplifies the configuration and setup to achieve SSO. One big advantage is that Tivoli Access Manager/Tivoli Integrated Portal can use different user registries and still perform SSO. Tivoli Access Manager/Tivoli Integrated Portal provided the mapping between different registry formats. You can also configure Tivoli Integrated Portal/Tivoli Access Manager to share a single user registry (though that configuration is outside the scope of this article).
WebSEAL and Tivoli Integrated Portal/embedded WebSphere Application Server TAI interaction
Figure 2 shows the flow of an HTTP request to WebSphere Application Server via WebSEAL and the Extended Trust Association Interceptor. This is just the default use 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.
- The user encounters WebSEAL (possibly through other proxies) and is prompted to authenticate.
- WebSEAL authenticates the user, acquires credentials for the user from the user registry, and possibly authorizes the request.
- 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 is changed so it matches a configured SSO user, and the request is sent to WebSphere Application Server.
- Tivoli Integrated Portal/embedded WebSphere Application Server receives the request and calls a TAI method (
isTargetInterceptor) to determine if the request is from a perimeter authentication service that has already authenticated the user.
- Tivoli Integrated Portal/embedded WebSphere Application Server calls a TAI method (
negotiateValidateandEstablishTrust) to:
- Establish trust with the perimeter authentication server.
This method establishes trust with WebSEAL by checking that the BA header contains the correct password for the configured SSO user. Trust between WebSEAL and WebSphere Application Server cannot be established using mutually authenticated SSL sessions; it can only be established by verifying the SSO password. No checking of certificates is performed by the TAI.
- Retrieve the credentials.
The iv-creds header is then extracted from the request and used to retrieve: the short name of the WebSEAL authenticated user, and the credential object containing user and group information.
- Return the authenticated user information.
At this point, WebSphere Application Server has valid credentials that it can 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 the Tivoli Access Manager authorization server or the WebSphere Application Server 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 of the WebSphere Application Server user registry.
- The credential object inserted into the subject by the TAI means WebSphere Application Server does not have to perform any additional user registry searches as part of the authentication process.
This section describes the three related configuration tasks that you must do in Tivoli Integrated Portal/embedded WebSphere Application Server to allow the correct operation 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 Trust Association Interceptor to behave as desired
Enabling trust association
The first step is to traverse to the trust association screen in the console.
- From the Tivoli Integrated Portal console:
- Expand Security, select Secure administration, applications, and infrastructure
- Expand Web security and click Trust association, as shown in Figure 3.
Figure 3. Tivoli Integrated Portal Security page
- Enable trust association must be checked. Check it if it is not already checked, and click Apply.
- Save the configuration changes.
Adding the Extended Trust Association Interceptor as an interceptor
This section sequentially follows the section above. If used in isolation, you should read Enabling trust association to learn how to traverse to the Trust association page in the WebSphere Application Server admin console.
- Start at the Trust association screen.
- Click Interceptors.
Figure 4. Trust association
- If the
com.ibm.sec.authn.tai.TAMETai is not defined, select New.On the following screen, enter com.ibm.sec.authn.tai.TAMETai into the Interceptor class name field and click Apply.
- Save the configuration changes.
Adding custom properties to Tivoli Access Manager Extended Trust Association Interceptor
To add custom properties to Tivoli Access Manager Extended Trust Association Interceptor, start at the Interceptors screen.
- Select the Interceptor class name com.ibm.sec.authn.tai.Tivoli Access ManagerETai, as shown in Figure 5.
- Go to the Custom properties screen.
- From the Tivoli Integrated Portal console click Custom properties.
Figure 5. Define Interceptor class name
- For each required property that is not defined, click New then enter the required 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 Association Interceptor
- If the custom property already exists but does not contain the correct Name, Value, and Description, select that property, make necessary changes, and click Apply.
- Repeat for all required properties as defined in Extended Trust Association Interceptor custom properties.
- When all properties are set, you should see a list similar to Figure 8 (with 10 custom properties).
Figure 8. Custom property list
- Save the configuration changes, and restart the Tivoli Integrated Portal server.
Figure 9. Save configuration
Extended Trust Association Interceptor custom properties
This section describes all of the mandatory and optional configuration properties and any interactions that the properties have with one another.
com.ibm.websphere.security.webseal.useWebSphereUserRegistry
Allowed values:
String true or false
Description:
This property is used to determine whether the Extended Trust Association Interceptor will authenticate the trusted user against the WebSphere Application Server user registry or the Tivoli Access Manager authorization server.If this property is set to true, the resulting Subject will not contain a PDPrincipal, as the Tivoli Access Manager authorization server is required to build the PDPrincipal. Any other value for this property will result in a PDPrincipal being added to the Subject.
Required:
This property is mandatory. It is recommended that you use differing registries.
Default Value:
False
com.ibm.websphere.security.webseal.tamUserDnMapping
Value:
WebSphere Application Server
Description:
The Extended Trust Association Interceptor will add the users credential information into the JAAS Subject. This information includes the users DN. Map this DN to the WebSphere Application Server DN, or (Value = WebSphere Application Server).If a mapping is attempted for a user that does not exist in the WebSphere Application Server user registry, it will be ignored and not added to the JAAS Subject.
Required:
This property should be specified.
Default value:
Tivoli Access Manager
com.ibm.websphere.security.webseal.tamGroupDnMapping
Allowed values:
WebSphere Application ServerRequired. This property should be specified.
Description:
The Extended Trust Association Interceptor will add the user's credential information into the JAAS Subject. This information includes the group DNs. The Extended Trust Association Interceptor can be configured to map these DNs to either the WebSphere Application Server DNs or to (Value = WebSphere Application Server).If a mapping is attempted for a group that does not exist in the WebSphere Application Server user registry, it will be ignored and not added to the JAAS Subject.
Default value:
Tivoli Access Manager
com.ibm.websphere.security.webseal.loginId
Allowed values:
Any string. Create a new user in the Tivoli Integrated Portal registry called websealSSOID. Note that this user can reside in the file based registry that Tivoli Integrated Portal configures out of the box. (You could use the Tivoli Integrated Portal console to create a user from Manage User.)Required. This property should be specified.
Description:
The ETAI must be configured with the username of the WebSEAL trusted user. This is the SSO user that will be authenticated using the password in the BA header inserted by WebSEAL in the request. The format of the username is the short name representation.
Interaction with other properties:
com.ibm.websphere.security.webseal.useWebSphereUserRegistryThe value of this property must exist as a valid user in the user registry. If useWebSphereUserRegistry is set totrue, then the user must exist in the WebSphere Application Server user registry (or in the Tivoli Access Manager user registry).
Default value:
There is no default value for this property. If it does not exist, Extended Trust Association Interceptor initialization will fail.
com.ibm.websphere.security.webseal.checkViaHeader
Values:
String trueRequired. This property should be specified.
Description:
The Extended Trust Association Interceptor can be configured so the Via header can be ignored when validating trust for a request. This property is necessary if Tivoli Access Manager/WebSEAL wants to allow requests into Tivoli Integrated Portal only from certain hosts. TSA has a requirement on this.
Interaction with other properties:
com.ibm.websphere.security.webseal.hostnames
com.ibm.websphere.security.webseal.portsIf the checkViaHeader property is set to false, none of the values of the other properties will have any effect on the operation of the Extended Trust Association Interceptor.
Default value:
false
com.ibm.websphere.security.webseal.id
Allowed values:
iv-credsRequired. This is a mandatory property used for SSO.
Description:
Iv-creds carry end user credentials, which are used by Tivoli Integrated Portal/embedded WebSphere Application Server to make authorization decisions.
Default value:
iv-credsAny other values set with this property will be added to a list along with iv-creds. iv-creds will always be a required header for the Extended Trust Association Interceptor.
com.ibm.websphere.security.webseal.hostnames
Allowed values:
A comma-separated list of any strings
Description:
The Extended Trust Association Interceptor can be configured so the request must arrive via a list of expected hosts. If any of the hosts in the Via header of the HTTP request are not listed in the value of this property, the request will be ignored by the Extended Trust Association Interceptor.
Interaction with other properties:
com.ibm.websphere.security.webseal.ports:All of the values listed in hostnames will be used alongside all of the ports listed in this property to indicate a trusted host. For example:
Hostnames = abc,xyz
Ports = 80,443
The 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 hostnames property will have no effect on the Extended Trust Association Interceptor operation.
Default value:
There is no default value for this property. If checkViaHeader is set to true and this property is not set, then Extended Trust Association Interceptor initialization will fail.
com.ibm.websphere.security.webseal.ports
Allowed values:
443
Description:
This property is used alongside the hostnames property to indicate which hosts in the Via header are trusted sources. If the ports of the hosts in the Via header are not listed in the value of this property, the request will be ignored by the Extended 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 used alongside all of the ports listed in this property to indicate a trusted host. For example:
Hostnames = abc,xyz
Ports = 80,443
The 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 property will have no effect on the Extended Trust Association Interceptor operation.
Default value:
There is no default value for this property. If checkViaHeader is set to true and this property is not set, then Extended Trust Association Interceptor initialization will fail.
com.ibm.websphere.security.webseal.ssoPwdExpiry
Allowed values:
A positive integer
Description:
Once trust has been established for a request, the password for the SSO user is cached for subsequent trust validation of requests. This saves the Extended Trust Association Interceptor from having to reauthenticate the SSO user with the user registry for every request -- thereby increasing performance.The cache timeout period can be modified by setting this property to the required time, in seconds. If the password expiry property is set to 0, 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.groupRealmPrefix
Allowed values:
“group:”Required. This property should be specified.
Description:
This property is needed to map the group realm prefix from Tivoli Access Manager to the group realm prefix in the WebSphere registry.Required. This is a mandatory property.
com.ibm.websphere.security.webseal.userRealmPrefix
Allowed values:
“user:”Required. This property should be specified.
Description:
This property is needed to map the user realm prefix from Tivoli Access Manager to the user realm prefix in the WebSphere registry.This is a mandatory property.
Restart the Tivoli Integrated Portal server after all of the custom properties above are saved.
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 an Extended Trust Association Interceptor targeted HTTP request is sent.
- Create the junction with the required parameters.
- Create a trusted SSO user.
- Set the dummy password in the configuration file.
There are many parameters available when creating a junction in WebSEAL. The two that are required by the Extended Trust Association Interceptor are:
-
–b supply
-
Ensures that WebSEAL passes the BA header in the HTTP request. The Extended Trust Association Interceptor requires the dummy password in the BA header; the username is not used.
-
–c iv-creds
-
Ensures that WebSEAL passes the logged in user's credential in an iv-creds header in the HTTP request. The Extended Trust Association Interceptor requires this header or it will not handle the request. Other headers can also be passed, 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"
The Extended Trust Association Interceptor requires a user to exist in the user registry that will be used to authenticate trust. This user and their password will become the central part of establishing trust between WebSEAL and WebSphere Application Server. The value of the custom property com.ibm.websphere.security.webseal.loginId will be set to this user, and the dummy password in WebSEAL will be set to this user's password.
- If the custom property com.ibm.websphere.security.webseal.useWebSphereUserRegistry is not set to true, this user must be created in the Tivoli Access Manager user registry. You can do so using the pdadmin utility.
For example, to create a user using pdadmin in Tivoli Access Manager 5.1:
user create sso cn=sso,o=ibm,c=au sso sso ssopwd user modify ssouser account-valid yes
- If the custom property com.ibm.websphere.security.webseal.useWebSphereUserRegistry is set to true, this user must be created in the WebSphere Application Server user registry. (See the WebSphere Application Server Info Center for details.)
WebSEAL provides a mechanism for predetermining the password that's passed in the basic authentication header of the HTTP request. Set the dummy password in the WebSEAL instance configuration file using the –b supply parameter described inRequired 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 installed on 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 this property to the password of the trusted SSO user. Save the file and restart your WebSEAL instance so the new property value will take effect.
This section outlines a few of the common problems encountered when using the Extended Trust Association Interceptor.
- Problem: After enabling the Extended Trust Association Interceptor, a restart of WebSphere Application Server shows
ClassNotFoundException 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 been run after placing the JAR in the plug-ins directory of the WebSphere Application Server home directory.
-
Solution
-
Make sure the JAR has been added to the correct location and the osgiCfgInit script has been run.
- Problem: Single sign-on does not work. The user is prompted to login to both WebSEAL and WebSphere Application Server.
-
Common causes
-
The WebSEAL junction has not been set up to pass the iv-creds header. This is a mandatory requirement for the Extended Trust Association Interceptor.
The WebSEAL junction has not been set up to pass the BA header. This is a mandatory 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 WebSEAL configuration.
- The WebSEAL instance has not been restarted after the dummy password was set.
- The password for the trusted user has expired.
The request has come via hosts or ports that are not listed in the hostnames and ports configuration properties.
The Extended Trust Association Interceptor has not initialized correctly because 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 the relevant properties, or set the
viaDepthand checkViaHeader properties as required.
- Check the log files to see why the initialization is failing. Search for Tivoli Access Manager Extended Trust Association Interceptor in the SystemOut.log.
- Problem: How to enable trace for Tivoli Access Manager Extended Trust Association Interceptor. The trace specification required for the Extended Trust 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 IBM Support for review of any problems. It is also useful for IBM Support to have the trace for the WebSphere Application Server security web component. Use the following trace specification to get both.
com.ibm.ws.security.web.*=all:com.ibm.sec.authn.tai.*=all
Learn
- Learn all about the features and benefits of Tivoli Access Manager for enterprise 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 all aspects 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 for download directly from developerWorks.
The advantages of integrating Tivoli Access Manager (TAM) version 6.1 and Tivoli Integrated Portal (TIP) version 1.1.x are contained in this article. Detailed instructions show you how to configure single sign-on between Tivoli Access Manager/WebSEAL and Tivoli Integrated Portal using Tivoli Access Manager Extended Trust Association Interceptor (ETai). You can learn how to configure the Tivoli Access Manager/WebSEAL server, a Tivoli Integrated Portal junction, a junction mapping table, and single-sign on. You can also explore trust association and Extended Trust Association Interceptor custom properties. Troubleshooting tips are also included.
To follow along with the example configurations in this article, you need to do the following prerequisite tasks:
- Install Tivoli Access Manager version 6.1, and any prerequisites associated with Tivoli Access Manager, on a server machine.
- Install Tivoli Integrated Portal Version 1.1 fixpack 11 and above for all Tivoli Integrated Portal based products.
- Ensure the necessary ports are opened up for access from WebSEAL servers to Tivoli Integrated Portal Servers. See the Tivoli Access Manager documentation for details.
- Check the status of the Tivoli Access Manager/WebSEAL server by running the
pd_start statuscommand from the command line. The output should look like:pdmgrd yes yes pdacld yes no (sometimes yes) pdmgrproxyd no no webseald-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 Access Manager 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 should see a basic authentication dialog or a form based login screen. Input the userid and password. You should see the Tivoli Access Manager WebSEAL splash screen.
In typical deployment architecture, a product gets deployed into three zones, as shown in Figure 1. In the untrusted zone, an end user accesses services or applications. In the semi-trusted zone, Tivoli Access Manager/WebSEAL (a reverse proxy server) intercepts any incoming HTTP/HTTPS requests and ensures that end users accessing Tivoli Integrated Portal applications are authenticated and authorized for the request. The request can then continue on to the necessary Tivoli Integrated Portal applications deployed in the trusted zone.
All the Tivoli Integrated Portal based products have to be installed on a single instance of Tivoli Integrated Portal for integration with Tivoli Access Manager.
Figure 1. Deployment architecture
Restrictions of Tivoli Integrated Portal-Tivoli Access Manager deployment architecture
The current deployment architecture for Tivoli Integrated Portal-Tivoli Access Manager has restrictions on deploying one WebSEAL server instance and mapping it to one Tivoli Integrated Portal server. Installing multiple Tivoli Integrated Portal servers and handling requests via one single WebSEAL server is restricted in this design.
Configuring Tivoli Access Manager/WebSEAL server
To secure transport between Tivoli Access Manager and Tivoli Integrated Portal, a Tivoli Integrated Portal signer and default certificate should be in the Tivoli Access Manager keystore. This is a prerequisite for Tivoli Integrated Portal junction configuration.
Import Tivoli Integrated Portal certificate into WebSEAL keystore
To export a Tivoli Integrated Portal certificate:
- Log in to Tivoli Integrated Portal using Firefox. Double-click the lock icon in the lower right of the browser window; the Page Info window's Security section should appear.
Click View Certificate, which brings up the Certificate window.
- Select the Details tab.
- Click Export to export to the local file system. This exports Tivoli Integrated Portal's X.509 certificate.
- Transfer the certificate to the Tivoli Access Manager machine.
- Import the Tivoli Integrated Portal certificate into Tivoli Access Manager:
- Start X server in the Tivoli Access Manager machine, if not already started, using the
startxorgdmcommand. - Launch IKeyMan (
./ikeyman.sh).- Click Open on the toolbar.
- Select Key database type: CMS, click Browse, and go to
/var/pdweb/www-ip1/certs. - Select pdsrv.kdb, which launches the Password Prompt window. The default password is the same as the filename: pdsrv.
- Select Signer Certificates in the Key database content section.
- Click Add, which launches Add CA's Certificate from a File window.
- Select Data type: Base64-encoded ASCII data.
- Click Browse.
- Select the exported certificate from Tivoli Integrated Portal.
- Enter a label for the certificate, such as
tipmachine. - Click Save to save the keystore (use the same file name).
- Start X server in the Tivoli Access Manager machine, if not already started, using the
Configuring a Tivoli Integrated Portal junction
A WebSEAL junction is an HTTP or HTTPS connection between a front-end WebSEAL server and a back-end Tivoli Integrated Portal server. Junctions logically combine the web space of the back-end Tivoli Integrated Portal server with the web space of the WebSEAL server, resulting in a unified view of the entire web object space. A junction lets WebSEAL provide protective services on behalf of the back-end server. WebSEAL performs authentication and authorization checks on all requests for resources before passing those requests across a junction to the back-end server. Use the steps below to configure a Tivoli Integrated Portal junction that primarily uses SSL as secured transport between WebSEAL and Tivoli Integrated Portal server communications.
- Create a Tivoli Integrated Portal junction by starting the
pdadminutility from the command line:pdadmin -a sec_master -p passw0rdwhere:sec_master= the root useridpassw0rd= the password forsec_masterFrom the
padadminprompt, run the following command to create a junction: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. - Display the Tivoli Integrated Portal junction by starting the pdadmin utility from the command line:
pdadmin -a sec_master -p passw0rd
where:sec_master= the root useridpassw0rd= the password forsec_masterFrom 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 initially lack knowledge of the junction point. WebSEAL cannot filter the URL because it is generated on the client side.
During a client request for a resource using this URL, WebSEAL can attempt to reprocess the server-relative URL using a junction mapping table (JMT). A JMT maps specific target resources to junction names. Junction mapping is an alternative to the cookie-based solution for filtering dynamically generated server-relative URLs.
WebSEAL checks the location information in the server-relative URL with the data contained in the JMT. WebSEAL begins searching at the top of the table and continues downward. If the path information in the URL matches any entry in the table during the top-down search, WebSEAL directs the request to the junction associated with that location.
The table is an ASCII text file called jmt.conf. The location of the file is specified in the [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 a facility already in the codebase to override the WebTop URL using a property. This property 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 |
To test the junction mappings, launch your browser using https://<TAM_Host Name>/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 Manager credentials: userid and password. The request should be redirected to the Tivoli Integrated Portal login page.
Configuring single sign-off Tivoli Integrated Portal
Logging out from the Tivoli Integrated Portal console also logs out the user session in Tivoli Integrated Portal and in Tivoli Access Manager. To enable this single sign-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 in Tivoli Access Manager that points to the Tivoli Integrated Portal Server.
If the value for the above property is blank, Tivoli Access Manager virtual host junction is assumed. If there is a value specified for the above property, then Tivoli Integrated 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 hosts and servers, letting you control access to the Tivoli Integrated Portal server. This feature 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 access the Tivoli Integrated Portal server. |
createHostNames |
Specifies the list of host names, separated by the ; delimiter, to access the Tivoli Integrated Portal server. |
resetHostNames |
Specifies the list of host names, separated by the ; delimiter, to remove the host names that is registered to access the Tivoli Integrated Portal server. |
To execute the script, enter the following command:
<TIP_HOME>/bin/wsadmin.sh/bat -username tipadmin -password tippass -f includeHostnames.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 authenticated user where the credential is passed from WebSEAL to the downstream WebSphere Application Server servers. The user thus does not need to reauthenticate at any time.
The next section describes a component, called the Tivoli Access Manager Extended Trust Association Interceptor (ETai), that implements the WebSphere Application Server trust association interceptor interface to achieve SSO from WebSEAL to Tivoli Integrated Portal/embedded WebSphere Application Server.
Tivoli Integrated Portal/embedded WebSphere Application Server 6.1 supports SSO with perimeter authentication services, such as reverse proxies through trust associations. When trust associations are enabled, WebSphere Application Server is not required to authenticate a user if a request arrives via a trusted source that has already performed authentication. The perimeter authentication service is expected to:
- 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 Application Server that handles the trust association. It is a "pluggable" module, whose responsibilities include:
- Validation of trust with the perimeter authentication service.
- Extraction of credential information from the request.
Tivoli Integrated Portal will support SSO between Tivoli Access Manager/WebSEAL and the Tivoli Integrated Portal server. End users can login once to Tivoli Access Manager and WebSEAL will redirect the request to the Tivoli Integrated Portal server without having to log into Tivoli Integrated Portal. The Tivoli Access Manager Extended Trust Association Interceptor will be configured in the Tivoli Integrated Portal/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 of Tivoli Access Manager and simplifies the configuration and setup to achieve SSO. One big advantage is that Tivoli Access Manager/Tivoli Integrated Portal can use different user registries and still perform SSO. Tivoli Access Manager/Tivoli Integrated Portal provided the mapping between different registry formats. You can also configure Tivoli Integrated Portal/Tivoli Access Manager to share a single user registry (though that configuration is outside the scope of this article).
WebSEAL and Tivoli Integrated Portal/embedded WebSphere Application Server TAI interaction
Figure 2 shows the flow of an HTTP request to WebSphere Application Server via WebSEAL and the Extended Trust Association Interceptor. This is just the default use 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.
- The user encounters WebSEAL (possibly through other proxies) and is prompted to authenticate.
- WebSEAL authenticates the user, acquires credentials for the user from the user registry, and possibly authorizes the request.
- 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 is changed so it matches a configured SSO user, and the request is sent to WebSphere Application Server.
- Tivoli Integrated Portal/embedded WebSphere Application Server receives the request and calls a TAI method (
isTargetInterceptor) to determine if the request is from a perimeter authentication service that has already authenticated the user. - Tivoli Integrated Portal/embedded WebSphere Application Server calls a TAI method (
negotiateValidateandEstablishTrust) to:- Establish trust with the perimeter authentication server.
This method establishes trust with WebSEAL by checking that the BA header contains the correct password for the configured SSO user. Trust between WebSEAL and WebSphere Application Server cannot be established using mutually authenticated SSL sessions; it can only be established by verifying the SSO password. No checking of certificates is performed by the TAI.
- Retrieve the credentials.
The iv-creds header is then extracted from the request and used to retrieve: the short name of the WebSEAL authenticated user, and the credential object containing user and group information.
- Establish trust with the perimeter authentication server.
- Return the authenticated user information.
At this point, WebSphere Application Server has valid credentials that it can 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 the Tivoli Access Manager authorization server or the WebSphere Application Server 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 of the WebSphere Application Server user registry.
- The credential object inserted into the subject by the TAI means WebSphere Application Server does not have to perform any additional user registry searches as part of the authentication process.
This section describes the three related configuration tasks that you must do in Tivoli Integrated Portal/embedded WebSphere Application Server to allow the correct operation 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 Trust Association Interceptor to behave as desired
Enabling trust association
The first step is to traverse to the trust association screen in the console.
- From the Tivoli Integrated Portal console:
- Expand Security, select Secure administration, applications, and infrastructure
- Expand Web security and click Trust association, as shown in Figure 3.
Figure 3. Tivoli Integrated Portal Security page - Enable trust association must be checked. Check it if it is not already checked, and click Apply.
- Save the configuration changes.
Adding the Extended Trust Association Interceptor as an interceptor
This section sequentially follows the section above. If used in isolation, you should read Enabling trust association to learn how to traverse to the Trust association page in the WebSphere Application Server admin console.
- Start at the Trust association screen.
- Click Interceptors.
Figure 4. Trust association - If the
com.ibm.sec.authn.tai.TAMETaiis not defined, select New.On the following screen, enter
com.ibm.sec.authn.tai.TAMETaiinto the Interceptor class name field and click Apply. - Save the configuration changes.
Adding custom properties to Tivoli Access Manager Extended Trust Association Interceptor
To add custom properties to Tivoli Access Manager Extended Trust Association Interceptor, start at the Interceptors screen.
- Select the Interceptor class name com.ibm.sec.authn.tai.Tivoli Access ManagerETai, as shown in Figure 5.
- Go to the Custom properties screen.
- From the Tivoli Integrated Portal console click Custom properties.
Figure 5. Define Interceptor class name - For each required property that is not defined, click New then enter the required 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 Association Interceptor - If the custom property already exists but does not contain the correct Name, Value, and Description, select that property, make necessary changes, and click Apply.
- Repeat for all required properties as defined in Extended Trust Association Interceptor custom properties.
- When all properties are set, you should see a list similar to Figure 8 (with 10 custom properties).
Figure 8. Custom property list - Save the configuration changes, and restart the Tivoli Integrated Portal server.
Figure 9. Save configuration
Extended Trust Association Interceptor custom properties
This section describes all of the mandatory and optional configuration properties and any interactions that the properties have with one another.
com.ibm.websphere.security.webseal.useWebSphereUserRegistry
| Allowed values: | String true or false |
| Description: | This property is used to determine whether the Extended Trust Association Interceptor will authenticate the trusted user against the WebSphere Application Server user registry or the Tivoli Access Manager authorization server. If this property is set to true, the resulting Subject will not contain a PDPrincipal, as the Tivoli Access Manager authorization server is required to build the PDPrincipal. Any other value for this property will result in a PDPrincipal being added to the Subject. |
| Required: | This property is mandatory. It is recommended that you use differing registries. |
| Default Value: | False |
com.ibm.websphere.security.webseal.tamUserDnMapping
| Value: | WebSphere Application Server |
| Description: | The Extended Trust Association Interceptor will add the users credential information into the JAAS Subject. This information includes the users DN. Map this DN to the WebSphere Application Server DN, or (Value = WebSphere Application Server). If a mapping is attempted for a user that does not exist in the WebSphere Application Server user registry, it will be ignored and not added to the JAAS Subject. |
| Required: | This property should be specified. |
| Default value: | Tivoli Access Manager |
com.ibm.websphere.security.webseal.tamGroupDnMapping
| Allowed values: | WebSphere Application Server Required. This property should be specified. |
| Description: | The Extended Trust Association Interceptor will add the user's credential information into the JAAS Subject. This information includes the group DNs. The Extended Trust Association Interceptor can be configured to map these DNs to either the WebSphere Application Server DNs or to (Value = WebSphere Application Server). If a mapping is attempted for a group that does not exist in the WebSphere Application Server user registry, it will be ignored and not added to the JAAS Subject. |
| Default value: | Tivoli Access Manager |
com.ibm.websphere.security.webseal.loginId
| Allowed values: | Any string. Create a new user in the Tivoli Integrated Portal registry called websealSSOID. Note that this user can reside in the file based registry that Tivoli Integrated Portal configures out of the box. (You could use the Tivoli Integrated Portal console to create a user from Manage User.)Required. This property should be specified. |
| Description: | The ETAI must be configured with the username of the WebSEAL trusted user. This is the SSO user that will be authenticated using the password in the BA header inserted by WebSEAL in the request. The format of the username is the short name representation. |
| Interaction with other properties: | com.ibm.websphere.security.webseal.useWebSphereUserRegistry The value of this property must exist as a valid user in the user registry. If |
| Default value: | There is no default value for this property. If it does not exist, Extended Trust Association Interceptor initialization will fail. |
com.ibm.websphere.security.webseal.checkViaHeader
| Values: | String true Required. This property should be specified. |
| Description: | The Extended Trust Association Interceptor can be configured so the Via header can be ignored when validating trust for a request. This property is necessary if Tivoli Access Manager/WebSEAL wants to allow requests into Tivoli Integrated Portal only from certain hosts. TSA has a requirement on this. |
| Interaction with other properties: | com.ibm.websphere.security.webseal.hostnames com.ibm.websphere.security.webseal.ports If the |
| Default value: | false |
com.ibm.websphere.security.webseal.id
| Allowed values: | iv-creds Required. This is a mandatory property used for SSO. |
| Description: | Iv-creds carry end user credentials, which are used by Tivoli Integrated Portal/embedded WebSphere Application Server to make authorization decisions. |
| Default value: | iv-creds Any other values set with this property will be added to a list along with iv-creds. iv-creds will always be a required header for the Extended Trust Association Interceptor. |
com.ibm.websphere.security.webseal.hostnames
| Allowed values: | A comma-separated list of any strings |
| Description: | The Extended Trust Association Interceptor can be configured so the request must arrive via a list of expected hosts. If any of the hosts in the Via header of the HTTP request are not listed in the value of this property, the request will be ignored by the Extended Trust Association Interceptor. |
| Interaction with other properties: | com.ibm.websphere.security.webseal.ports: All of the values listed in hostnames will be used alongside all of the ports listed in this property to indicate a trusted host. For example: com.ibm.websphere.security.webseal.checkViaHeader: If this property is false then the hostnames property will have no effect on the Extended Trust Association Interceptor operation. |
| Default value: | There is no default value for this property. If checkViaHeader is set to true and this property is not set, then Extended Trust Association Interceptor initialization will fail. |
com.ibm.websphere.security.webseal.ports
| Allowed values: | 443 |
| Description: | This property is used alongside the hostnames property to indicate which hosts in the Via header are trusted sources. If the ports of the hosts in the Via header are not listed in the value of this property, the request will be ignored by the Extended 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 used alongside all of the ports listed in this property to indicate a trusted host. For example: com.ibm.websphere.security.webseal.checkViaHeader: If this property is |
| Default value: | There is no default value for this property. If checkViaHeader is set to true and this property is not set, then Extended Trust Association Interceptor initialization will fail. |
com.ibm.websphere.security.webseal.ssoPwdExpiry
| Allowed values: | A positive integer |
| Description: | Once trust has been established for a request, the password for the SSO user is cached for subsequent trust validation of requests. This saves the Extended Trust Association Interceptor from having to reauthenticate the SSO user with the user registry for every request -- thereby increasing performance. The cache timeout period can be modified by setting this property to the required time, in seconds. If the password expiry property is set to 0, 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.groupRealmPrefix
| Allowed values: | “group:” Required. This property should be specified. |
| Description: | This property is needed to map the group realm prefix from Tivoli Access Manager to the group realm prefix in the WebSphere registry. Required. This is a mandatory property. |
com.ibm.websphere.security.webseal.userRealmPrefix
| Allowed values: | “user:” Required. This property should be specified. |
| Description: | This property is needed to map the user realm prefix from Tivoli Access Manager to the user realm prefix in the WebSphere registry. This is a mandatory property. |
Restart the Tivoli Integrated Portal server after all of the custom properties above are saved.
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 an Extended Trust Association Interceptor targeted HTTP request is sent.
- Create the junction with the required parameters.
- Create a trusted SSO user.
- Set the dummy password in the configuration file.
There are many parameters available when creating a junction in WebSEAL. The two that are required by the Extended Trust Association Interceptor are:
- –b supply
- Ensures that WebSEAL passes the BA header in the HTTP request. The Extended Trust Association Interceptor requires the dummy password in the BA header; the username is not used.
- –c iv-creds
- Ensures that WebSEAL passes the logged in user's credential in an iv-creds header in the HTTP request. The Extended Trust Association Interceptor requires this header or it will not handle the request. Other headers can also be passed, 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" |
The Extended Trust Association Interceptor requires a user to exist in the user registry that will be used to authenticate trust. This user and their password will become the central part of establishing trust between WebSEAL and WebSphere Application Server. The value of the custom property com.ibm.websphere.security.webseal.loginId will be set to this user, and the dummy password in WebSEAL will be set to this user's password.
- If the custom property com.ibm.websphere.security.webseal.useWebSphereUserRegistry is not set to true, this user must be created in the Tivoli Access Manager user registry. You can do so using the pdadmin utility.
For example, to create a user using pdadmin in Tivoli Access Manager 5.1:
user create sso cn=sso,o=ibm,c=au sso sso ssopwd user modify ssouser account-valid yes
- If the custom property com.ibm.websphere.security.webseal.useWebSphereUserRegistry is set to true, this user must be created in the WebSphere Application Server user registry. (See the WebSphere Application Server Info Center for details.)
WebSEAL provides a mechanism for predetermining the password that's passed in the basic authentication header of the HTTP request. Set the dummy password in the WebSEAL instance configuration file using the –b supply parameter described inRequired 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 installed on 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 this property to the password of the trusted SSO user. Save the file and restart your WebSEAL instance so the new property value will take effect.
This section outlines a few of the common problems encountered when using the Extended Trust Association Interceptor.
- Problem: After enabling the Extended Trust Association Interceptor, a restart of WebSphere Application Server shows
ClassNotFoundExceptionorClassDefNotFoundError.- 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 been run after placing the JAR in the plug-ins directory of the WebSphere Application Server home directory.
- Solution
- Make sure the JAR has been added to the correct location and the osgiCfgInit script has been run.
- Problem: Single sign-on does not work. The user is prompted to login to both WebSEAL and WebSphere Application Server.
- Common causes
-
The WebSEAL junction has not been set up to pass the iv-creds header. This is a mandatory requirement for the Extended Trust Association Interceptor.
The WebSEAL junction has not been set up to pass the BA header. This is a mandatory 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 WebSEAL configuration.
- The WebSEAL instance has not been restarted after the dummy password was set.
- The password for the trusted user has expired.
The request has come via hosts or ports that are not listed in the hostnames and ports configuration properties.
The Extended Trust Association Interceptor has not initialized correctly because 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 the relevant properties, or set the
viaDepthandcheckViaHeaderproperties as required. - Check the log files to see why the initialization is failing. Search for Tivoli Access Manager Extended Trust Association Interceptor in the SystemOut.log.
- Problem: How to enable trace for Tivoli Access Manager Extended Trust Association Interceptor. The trace specification required for the Extended Trust 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 IBM Support for review of any problems. It is also useful for IBM Support to have the trace for the WebSphere Application Server security web component. Use the following trace specification to get both.
com.ibm.ws.security.web.*=all:com.ibm.sec.authn.tai.*=all
Learn
- Learn all about the features and benefits of Tivoli Access Manager for enterprise 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 all aspects 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 for download directly from developerWorks.