Tivoli Federated Identity Manager: EAI Authentication with TFIM Security Token Service

Using Tivoli Federated Identity Manager to Acquire a Signed Tivoli Access Manager Credential for the Tivoli Access Manager External Authentication Interface (EAI)

This article and the supporting application provide a demonstration on how to use the WS-Trust to interface with the Tivoli® Federated Identity Manager (TFIM) Security Token Service (STS) to: Acquire a signed Tivoli Access Manager (TAM) credential, use this credential to authenticate with TAM WebSEAL or Web plug-in via External Authentication Interface (EAI), and validate the signed TAM credential. This article is shipped with sample code that also demonstrates a negative test to show what happens if the credential is modified and the signature becomes invalid. An animated walkthrough of the working demonstration application is also provided.

Share:

Shane B. Weeden, Senior Software Engineer, IBM

Shane WeedenShane 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.


developerWorks Professional author
        level

Suriadi Suriadi, Part-time employee, IBM

Suriadi SuriadiSuriadi 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.



06 December 2006

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.


Use case scenario

Figure 1 shows the use case scenario diagram.

Figure 1. Use case scenario
Use case scenarios

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.

Viewlets

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


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:

Figure 2. Creating a WebSEAL junction

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

Figure 3. EAI configuration for WebSEAL

	[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.

Figure 4. Other requirements on WebSEAL configuration

	[session]
	user-session-ids=no

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.


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.

Figure 5. WebSEAL policy attachments

	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

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
    FIM Console screen snapshot of the 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):

    AppliesToIssuer
    urn:itfim:wstrust:tamTokenurrn: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
    Figure 7. FIM console screen snapshot showing the chain lookup configuration for Username token to TAM Token
  • Click Next
  • Add the following modules to the chain in the following order (See Figure 8):

    OrderModule instanceMode
    1itfim-eaidemo-usernamevalidate
    2Mapping modulemap
    3itfim-eaidemo-ivcredexchange


    Figure 8. FIM console - Username to TAM Token module chain
    Figure 8 FIM Console screen snapshot showing 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):

    AppliesToIssuer
    urn:itfim:wstrust:samlTokenurn: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
    Figure 9. FIM Console screen snapshot showing the chain lookup for 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:

    OrderModule instanceMode
    1itfim-eaidemo-ivcredvalidate
    2Mapping Modulemap
    3itfim-eaidemo-saml10exchange


    Figure 10. FIM console - TAM token to SAML 1.0 module chain
    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

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.


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.

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:

Figure 11. Main page of the demonstration application.
Figure 11. Main page of the demonstration application

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


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.


Downloads

DescriptionNameSize
Demonstration application EAR fileitfim_wstrust.ear40KB
Documentationdoc.pdf729KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Tivoli (service management) on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Tivoli, WebSphere
ArticleID=173430
ArticleTitle=Tivoli Federated Identity Manager: EAI Authentication with TFIM Security Token Service
publish-date=12062006