Introduction

This article begins with a use case scenario describing the technical solution. For further understanding of the application, viewlets are available that show an animated walkthrough of the working demonstration application. Next, the article describes the tasks and configuration needed to set up the environment to make the sample application work.
Note: If Web plug-in is used instead of WebSEAL, the configuration information for Web plug-in is available in the PDF documentation here. The remainder of this article assumes that WebSEAL is used.

Back to top

Use case scenario

Figure 1 shows the use case scenario diagram.

The use case flow is as follows:

1. The browser requests the unprotected main.jsp page from the demonstration application
2. The main.jsp page is returned.
3. The brower requests the process.jsp page, passed along with the request are the username, password, trust server endpoint, and other ws-trust related parameters.
4. The demonstration application formats the user name and password into a Username token. In the demonstration code, presenting a password is optional. If it is provided, it will be included in the Username token and the TFIM STS validates the password against the LDAP. In a real deployment, the EAI might be handling the authentication by using a completely different technique. In that case, it is possible to just present a username to the STS in a Username token without a password. The demonstration application will do this if no password is provided. In that case, the TFIM STS is configured to treat the token as an identity assertion without validation.
5. STS returns a signed TAM credential if the username token validation and exchange were successful, or else, an error message is returned.
6. The EAI application returns the signed TAM credential to WebSEAL/Web plug-in via HTTP headers (hereafter just the term WebSEAL will be used although this solution is equally valid for TAM Web plug-in).

   6a. If token validation/exchange failed, processPage.jsp is returned to the browser, displaying the error message

7. If EAI authentication was successful, then the browser is redirected to the protected tamPage.jsp page. The signed TAM credential is also passed in the iv-creds HTTP header. In our demonstration code the, EAI application redirects the user to this page via the EAI URL redirection header.
   The tamPage.jsp page displays the TAM credential, and offers the user the opportunity to:

   7a. Modify it (thereby invalidating the signature). If selected, the tamPage.jsp page will be redisplayed with the modified credential.

   7b. Exchange the credential for a Security Assertion Markup Language (SAML) assertion. If selected, the current credential (perhaps modified via step 7a) will be sent to the TFIM STS via WS-Trust to be exchanged for a SAML assertion.

8. EAI application requests the TAM credential be exchanged for a SAML assertion at the STS. This will cause the signature of the TAM credential to be validated.
9. STS returns either a SAML assertion, which proves that the signature was valid, or, if token validation or exchange failed, an error message will be returned.
10. samlPage.jsp is returned to the browser, containing either the SAML assertion, or the error message.

Back to top

Viewlets

This article includes viewlets that show an animation of the demonstration application. Both affirmative and negative test cases are shown.

• Successful login and validation
• Invalid password
• Invalid signature

Back to top

WebSEAL configuration

This section shows the configuration needed for WebSEAL, including the junction configuration, EAI configuration, and other required configuration. This information is relevant for Tivoli AccessManager 5.1, and Tivoli Access Manager 6.0.

Junction configuration for WebSEAL

Configuration of the junction for this demonstration application is relatively standard. The iv-creds header should be included, and the example in Figure 2 shows a suitable command:

pdadmin>server task <your_webseal_server> create -t tcp
-h <your_websphere_hostname> -p 9080 -c all /eai

EAI configuration for WebSEAL

WebSEAL configuration of the EAI interface is summarized with the configuration options shown in Figure 3. Complete details of configuring EAI for WebSEAL can be found in the WebSEAL Administration Guide here

	[authentication-mechanisms]
	ext-auth-interface = /opt/pdwebrte/lib/libeaiauthn.so
	
	[acnt-mgt]
	eai-auth-error = eaiautherror.html
	
	[eai]
	eai-auth = both
	eai-pac-header = am-fim-eai-pac
	eai-pac-svc-header = am-fim-eai-pac-svc
	eai-user-id-header = am-fim-eai-user-id
	eai-auth-level-header = am-fim-eai-auth-level
	eai-qop-header = am-fim-eai-qop
	eai-xattrs-header = am-fim-eai-xattrs
	eai-redir-url-header = am-fim-eai-redir-url
	
	[eai-trigger-urls]
	trigger = /eai/*

Other requirements on WebSEAL configuration

At the time of writing, it is a requirement for this application that the "user session IDs" setting shown in Figure 4 is not enabled. The reason for this is because with "user session ids" enabled, WebSEAL will modify the credential returned via EAI authentication to include the user session ID as an extended attribute in the credential. This will invalidate the signature that was created on the credential by the trust service.

	[session]
	user-session-ids=no

Back to top

Web plug-in configuration

For the details of the Web plug-in configuration, please refer to the PDF document that is available for download here.

Back to top

Configuring TAM policy templates for EAI

When a user presents authentication information to the EAI application, they are clearly not yet authenticated to the TAM WebSEAL or Web plug-in. Therefore it is necessary to allow unauthenticated access to the application URLs that receive and process this authentication information. To make this clear, in the demonstration application we have divided the URL namespace into "protected" and "unprotected" URLs using application sub-directories. This also makes it easy for us to attach TAM policy templates (ACLs, POPs and authorization rules) to this part of the name space.

There are two policy templates recommended for this configuration:

1. An ACL, which permits unauthenticated access for those URLs requiring that access.
2. A POP which requires protected transport. This ensures that authentication information (for example, passwords) cannot be sent in the clear from the browser. This policy applies to all URLs in the demonstration application.

Configuration of the policy templates (and demonstration commands for attaching them to a WebSEAL namespace) is shown in Figure 5.

	pdadmin> acl create unauthenticated-allowed
	pdadmin> acl modify unauthenticated-allowed set group iv-admin TcmdbsvaBRrxl
	pdadmin> acl modify unauthenticated-allowed set group webseal-servers Tgmdbsrxl
	pdadmin> acl modify unauthenticated-allowed set user sec_master TcmdbsvaBRrxl
	pdadmin> acl modify unauthenticated-allowed set any-other Trx
	pdadmin> acl modify unauthenticated-allowed set unauthenticated Trx
	pdadmin> acl attach /WebSEAL/fimtest-sp/eai/app/unprotected unauthenticated-allowed
	
	pdadmin> pop create ssl-required
	pdadmin> pop modify ssl-required set qop privacy
	pdadmin> pop attach /WebSEAL/fimtest-sp/eai/app ssl-required

Back to top

TFIM STS configuration

This section provides instructions on how to set up the TFIM STS to allow token exchange from a Username token to a signed TAM Token and from a signed TAM Token to a SAML 1.0 Token. The information presented here is relevant to TFIM 6.1.

Configuring TFIM Trust Server to exchange username token for signed TAM token

• Logon to the FIM Console (for example, http://host:8421/ibm/console)
• Go to: Tivoli Federated Identity Manager --> Configure Trust Service --> Module Instances. We are going to create several module instances (Figure 6)
• Click Create
• Choose Username Token STS Module and name the module instance 'itfim-eaidemo-username'. Click Finish.
• Create another module instance of type XSL Transformation Module, and name the module instance 'Mapping Module'
• Create another module instance, of type IVCred Module, and name the module instance 'itfim-eaidemo-ivcred'.
  Note: When you receive the promte, check the box to allow the issue of Access Manager credentials. Also complete the TAM configuration file value (which should be the TAM configuration file name generated after you create the FIM domain, typically 'amconfig.conf').
  
  
  
  Figure 6. FIM console - created module instances
  
  
  
  
• Go to: Tivoli Federated Identity Manager --> Configure Trust Service --> Trust Service Chains. Create a module chain to exchange the incoming Username token for a signed TAM Token.
• Click Create and then Next
• Name the module chain 'username-to-ivcred-chain'. Click Next
• Choose 'Validate' as the Request Type, and choose 'Use Traditional WS-Trust Elements (Applies To, Issuer and Token Type)' as the Lookup Type.
• The following values are the default values for the 'AppliesTo' and 'Issuer' (Figure 7):
  
  
  
  

  AppliesTo	Issuer
  urn:itfim:wstrust:tamToken	urrn:itfim:wstrust:issuer

  
  
  
  
  You can choose other values for the AppliesTo and Issuer, however, during the use of the demonstration application, you will need to fill in the corresponding values in the main.jsp page.
  
  
  Figure 7. FIM console - chain lookup Username to TAM token
  
  
  
  
• Click Next
• Add the following modules to the chain in the following order (See Figure 8):
  
  
  
  

  Order	Module instance	Mode
  1	itfim-eaidemo-username	validate
  2	Mapping module	map
  3	itfim-eaidemo-ivcred	exchange

  
  
  
  
  
  
  Figure 8. FIM console - Username to TAM Token module chain
  
  
  
  
  
• Click Next;
• On the Username Token module configuration, set the username token valid time to '-1', meaning "never expire". Optionally, you can check the 'Skip password validation' if you decide not to do password validation for Username token. Otherwise, leave it unchecked. Click Next.
• On the Mapping module configuration, browse to the 'wstrust_tam.xsl' file, located under the itfim_wstrust.ear/itfim_wstrustWeb.war/mapping_rule folder of the application installation directory. We have bundled the mapping rule with the demonstration application EAR for convenience. Click Next.
• On the IVCred module configuration, check 'Enable Signature'. Choose 'DefaultKeyStore' as the keystore, and 'testonly' as the password. Choose 'testkey' as the signing key. Click Next.
• On the summary page, verify that all the information is correct and click Finish.
• Restart WebSphere®

Configuring TFIM Trust Server to exchange signed TAM token for SAML 1.0 token

• Log on to FIM Console (for example, http://host:8421/ibm/console)
• Go to: Tivoli Federated Identity Manager --> Configure Trust Service --> Module Instances.
• Click Create
• Choose SAML 1.0 STS Module and, name it 'itfim-eaidemo-saml10'
• Go to: Tivoli Federated Identity Manager --> Configure Trust Service --> Trust Service Chains. Create the module chain to exchange the incoming signed TAM token for a SAML 1.0 token.
• Click Create then Next.
• Name the module chain 'tam-to-saml10-chain'. Click 'Next'
• Choose 'Validate' as the Request Type, and choose 'Use Traditional WS-Trust Elements (Applies To, Issuer and Token Type)' as the Lookup Type.
• The following values are the default values for the 'AppliesTo' and 'Issuer' (Figure 9):
  
  
  
  

  AppliesTo	Issuer
  urn:itfim:wstrust:samlToken	urn:itfim:wstrust:issuer

  
  
  
  
  You can choose other value for the AppliesTo and Issuer, however, during the use of the demonstration application, you will need to fill in the corresponding values in the samlPage.jsp page.
  
  
  Figure 9. FIM console - Chain lookup TAM token to SAML 1.0 token
  
  
  
  
• Click Next
• Add the following module to the chain in the following order (Figure 10). Note that we are re-using the TAM credential module instance from the previous chain here for validation. This is not a requirement, but reduces configuration tasks:
  
  
  
  

  Order	Module instance	Mode
  1	itfim-eaidemo-ivcred	validate
  2	Mapping Module	map
  3	itfim-eaidemo-saml10	exchange

  
  
  
  
  
  
  Figure 10. FIM console - TAM token to SAML 1.0 module chain
  
  
  
  
  
• Click Next
• On the IVCred module configuration, check 'Enable signature validation' and choose the DefaultKeyStore as the keystore, and 'testonly' as the password. Choose testkey as the signature validation key. Click Next.
• On the Mapping module configuration, browse to the 'wstrust_saml10.xsl' file, located under the itfim_wstrust.ear/itfim_wstrustWeb.war/mapping_rule folder of the installation directory. We have bundled the mapping rule with the demonstration application EAR for convenience. Click Next.
• On the SAML 1.0 module, leave the defaults, and leave the 'Enable the Signing of Assertions' unchecked. Make sure that the name of the organization that issues the assertion is not empty (you can fill in any value you want). Click Next.
• On the summary page, verify that all the information is correct and click Finish.
• Restart WebSphere

Back to top

Environment configuration

The demonstration application uses functionality from the TAM Java™ API to display credential attributes. In order to use these classes, TAM configuration for the application is required. In particular, the WebSphere PDJRTE must be configured and a TAM server identity created for the application with SvrSslCfg.

From the command line where TAM is installed:

• Perform 'pdjrteconfig' :
  for example, /opt/PolicyDirectory/sbin/pdjrtecfg -action config -host <TAM_HOST> -java_home <WebSphere JRE directory>
• Perform SvrSslCfg :
  e.g. /opt/IBM/WebSphere/AppServer/java/bin/java com.tivoli.pd.jcfg.SvrSslCfg -action config -admin_id sec_master -admin_pwd passw0rd -appsvr_id wstrust -appsvr_pwd passw0rd -port 999 -mode remote -policysvr rhel30-pdmgr.test.gc.au.ibm.com:7135:1 -authzsvr rhel30-pdmgr.test.gc.au.ibm.com:7136:1 -cfg_file /root/wstrust.config -key_file /root/wstrust.ks

Note:
You will not need to do these configurations if the WebSphere server in which the demonstration application runs is the same server as the one where the FIM Runtime was installed and you have configured a FIM domain. In this case, the server would already have been configured, and the configuration file would be the one generated automatically after configuring the FIM domain.

Back to top

Property file update

The wstrustdemo.properties file needs to be updated to reflect the environment in which the demonstration application runs. This file is located under the installation directory 'itfim_wstrust.ear/itfim_wstrustWeb.war' under the WebSphere installedApps directory for the WebSphere profile.

The properties to configure are:

• PDJRTE_CONFIG_FILE_URL : The PDJRTE configuration file.
• TAM_ADMIN_ID : TAM administrator ID (for example, sec_master)
• TAM_ADMIN_PWD : TAM administrator password
• JUNCTION_NAME : The WebSEAL junction name, including the forward slash ('/') before the junction name. This is needed for the EAI application to generate a redirect URL at the time of EAI authentication. The slash is ignored for a configuration with Web plug-ins.

Back to top

Application installation and execution

The demonstration application EAR file should be installed into the target WebSphere server, and the wstrustdemo.properties file updated, then the application can be started. This can be done with the WebSphere administration console (or wsadmin command). For further information about installing Enterprise Application into WebSphere with the console or the 'wsadmin' command, please refer to WebSphere documentation here.

When using the application, check the WebSphere log files (SystemOut.log, SystemErr.log) for exceptions if you notice any problems.

The main launch page for the application (when using WebSEAL with a junction called /eai) is:

https://webseal/eai/itfim_wstrustWeb/unprotected/main.jsp

You should see the page displayed in Figure 11:

If you are prompted to login, check that you have correctly applied the "unauthenticated-allowed" TAM access control list.

Back to top

Additional information

In addition to what has been presented in this article, the downloadable PDF documentation here provides detailed information about the demonstration application, including the Web plug-in configuration information, the development tools and techniques that were employed to build the sample application, further information about the JSP pages, and finally, some explanation about the supporting Java classes that are used in the application.

Back to top

Downloads

Information about download methods          Get Adobe® Reader®

Resources

• Some viewlets showing the user experience with the demonstration application for several scenarios:
  • Successful login and validation
  • Invalid password
  • Invalid signature
  
  
• For further information about WebSEAL EAI configuration, consult the WebSEAL Administration Guide
  
  
• For further information about Web plug-in EAI configuration, consult the Web plug-in Administration Guide
  
  

About the authors

Shane Weeden is a senior software engineer with the IBM Federated Identity Manager development team. He has worked in IT security for 13 years, and has spent the last seven years working with Tivoli Security products. Shane has been with the Federated Identity Manager development team since its conception, and now divides his time between customer-focused engagements and core product development activities. He holds a Bachelor of Information Technology from the University of Queensland in Australia.

Suriadi is a trainee with IBM Federated Identity Manager team and has been with the team for several months. He holds a Bachelor of Information Technology (Honours) from Queensland University of Technology in Australia.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Use case scenario
• Viewlets
• WebSEAL configuration
• Web plug-in configuration
• Configuring TAM policy templates for EAI
• TFIM STS configuration
• Environment configuration
• Property file update
• Application installation and execution
• Additional information
• Downloads
• Resources
• About the authors
• Comments

Next steps from IBM

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

My developerWorks community

Dig deeper into Tivoli on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers