Custom TAM TAI++ Interceptor to detect step-up authentication

DetectStepup TAM TAI++ Interceptor

It is a common practice to externalise the authentication from Web application servers like IBM® WebSphere® Application Server (WAS) to dedicated single sign on (SSO) servers like IBM Tivoli® Access Manager for eBusiness (TAMeB). The SSO server, for example, TAMeB, offers enhanced security features like strong authentication and step-up authentication In order to externalise the authentication from WAS to TAMeB, a trust association interceptor (TAI) should be installed and configured on the WebSphere Application Server (WAS). However, the TAI shipped with the default WAS 6.x servers cannot detect the authentication level of the user, that is, whether the user used password or a security token. This additional information about the authentication level might be needed to the applications running on WAS to make authorization decisions. A custom TAM TAI++ interceptor should be developed and installed on the WebSphere Application Server to determine the authentication level of the user. This article explains the procedure to develop and install such a custom TAM TAI++ interceptor.

Share:

Subbu Cherukuwada (scheruku@au1.ibm.com), Senior Technical Specialist, IBM

Subbu Cherukuwada is working as Senior Technical Specialist in IBM Software Lab Services, Australia. He has completed Masters in Information Security from RMIT University, Australia. He is GIAC Security Essentials Certified (GSEC Gold) and has more than 13 years of IT industry experience. He specialises in the design and implementation of Tivoli Security Software products.



Kerry Gunn (kerrygun@au1.ibm.com), Associate Software Engineer, IBM 

Kerry Gunn holds a B. IT. (hons) from James Cook University. Currently he is working for Tivoli Security product development organization in the Gold Coast, Australia. He has been working with Tivoli Access Manager since 2003.



21 November 2007

Pre-requisite skills

We recommend this article for readers with the following skill set:

  • TAMeB administration (including step-up authentication, certificate authentication and TAI++ configuration)
  • WebSphere Application Server administration
  • J2EE™ development

Introduction

The DetectStepup TAM TAI++ Interceptor is a custom TAM TAI++ interceptor that extends the default TAM TAI++ Interceptor to extract the authentication level of the user from the TAM credentials and, then, dynamically assert an additional group membership of the user based on the authentication level. After changing the group membership of the user, the DetectStepup TAM TAI++ Interceptor generates a new subject for the user. By configuring different roles based on the group membership, the new subject can now be granted a role with high privileges. The name of the additional group can be specified as a property of TAI configuration using the WebSphere Application Server (WAS) Administration Console. The assertion is specific to the user session, and it does not alter the actual group in the user registry.


Requirement

To understand the need for DetectStepup TAM TAI++ Interceptor, consider a Web application of an example bank XYZ Bank.

The XYZ Bank wants to host a Web application that allows the customers to access their accounts online. This Web application will be hosted on a WebSphere Application Server (WAS) and the XYZ Bank will use a TAMeB as a Reverse Proxy SSO server in front of the WAS. The default TAM TAI++ interceptor will be installed and configured. To access their accounts, users login to the XYZ bank Web site using their login ID and password. After successful login, users are allowed to see their account balance and their personal details. If a user wants to transfer money from their account to another account, the user must step-up their authentication level to a stronger authentication mechanism using an SSL certificate. This requirement is addressed in the application design by using two different roles, namely authLevel1 and authLevel2. The authLevel2 role has all the privileges of authLevel1 role and the additional privilege to transfer funds. Before implementing this design, we need to identify and address the gaps between the requirements and the infrastructure capabilities. Figure 1 shows the requirements, capabilities, and gaps.

Figure 1. Requirements, capabilities, and gaps
Requirements, Capabilities and Gaps

The Tivoli software TAMeB supports various authentication mechanisms like password, SSL certificate or RSA securID, and so on. The WebSphere Application Server (WAS) supports multiple roles for users and access control based on the role membership of the user. However, WAS has no knowledge about the authentication level of the user. In other words, WAS does not know the authentication mechanism used by TAMeB to authenticate the user. The default TAM TAI++ Interceptor does not provide this functionality. Hence, WAS cannot assign the correct role for the user. So, how can we meet this requirement?


Solution

To meet this requirement, a customized solution should be designed and implemented to integrate TAMeB and WAS. The main steps involved in this process are:

  • Design
  • Development
  • Installation and configuration
  • Testing

Design

Some of the possible ways of meeting this requirement are:

  • External authentication HTTP interface
  • Custom TAI++ Interceptor

External authentication HTTP interface

An external authentication service can be integrated with TAMeB using external authentication HTTP interface. The external authentication service can authenticate the user via the required strong authentication mechanism and send the authentication response to TAMeB. TAMeB will use the authentication response and generate TAM credentials that contain new group membership for the user. To use this option, an external authentication service should be developed; the TAMeB server should be configured to use the external authentication service, and the default TAM TAI++ Interceptor should be configured on the WebSphere Application Server.

Custom TAI++ Interceptor

A custom TAI++ Interceptor that is capable of detecting the authentication level of the user can be developed and used. The custom TAI++ Interceptor can change the group membership of the user depending on the authentication level supplied by TAMeB. To use this option, a custom TAI++ Interceptor should be developed and the WebSphere Application Server should be configured to use the custom TAI++ Interceptor.

Let us analyse the advantages and disadvantages of using the custom TAI++ Interceptor.Advantages:

  • The standard TAMeB authentication mechanisms like password, SSL certificate or RSA securID can still be used while using the custom TAI++ Interceptor. The ability to use the standard authentication mechanisms is very important for existing TAMeB installations. In the existing installations, TAMeB might have been configured to use the standard authentication mechanisms for providing SSO to different applications hosted on various types of backend servers. The custom TAI++ Interceptor can add value to the existing TAMeB installations without affecting the current functionality.
  • The TAM credentials are not required to be modified. Implementing a custom TAI++ Interceptor does not require TAMeB to supply any additional data to WAS. There is no need to install any additional authentication modules on the TAMeB server.
  • It is relatively easier to install and configure the custom TAI++ Interceptor on a WebSphere Application Server and use it for all the applications installed on that server.

Disadvantages:

  • The custom TAI++ Interceptor should be installed and configured on the WebSphere Application Servers that require this functionality. If there are multiple WebSphere Application Servers behind the TAMeB server, then the effort required to implement the custom TAI++ Interceptor can be high.

Considering the potential advantages and the disadvantages, we have chosen to address the problem by developing and using a custom TAI++ Interceptor called DetectStepup TAM TAI++ Interceptor.


Development

The default TAM TAI++ interceptor is implemented by the Java class com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus. The DetectStepup TAM TAI++ Interceptor extends the TAMTrustAssociationInterceptorPlus class to perform the following tasks:

  • Validating the trust
  • Detecting the user authentication level
  • Updating the security subject
  • Returning the result

Validating the trust

The trust relationship between TAMeB and WAS should be validated for every authentication request to WAS. This is to ensure that the user session is established through the TAMeB server that is configured in the TAM TAI++ Interceptor configuration of WAS. The code to validate is shown below in Listing1:

Listing 1. Validating trust
TAIResult result = super.negotiateValidateandEstablishTrust(req, res);

Detecting the user authentication level

After every successful authentication, the default TAM TAI++ interceptor stores the user-specific information called TAM credentials in the authenticated security Subject as a Principal. The TAM credentials contain the details like distinguished name (DN) of the user in the TAM User Registry, the DNs of the user groups, the authentication level and authentication mechanism, and so on. The authentication level in the TAM credentials is a number starting from zero to the number of authentication levels configured in TAMeB. Let us consider an example TAMeB server.

Example:
A TAMeB server is configured:

  • To use the two authentication mechanisms password and SSL certificate
  • And the authentication level of SSL certificate is set to be more than that of password



The value of the authentication level in the TAM credentials can be 0, 1 or 2.

  • If the user is not authenticated, then the authentication level will be 0.
  • If the user is authenticated using password, then the authentication level will be 1.
  • If the user is authenticated using SSL certificate, then the authentication level will be 2.



The Java Class type for the TAM credentials Principal in the security subject is PDPrincipal. The security subject can be extracted from the TAIResult object returned by the default TAM TAI++ interceptor. The code to extract the PDPrincipal from the security subject is shown below in Listing 2:

Listing 2. Extracting the PDPrincipal
TAIResult result = super.negotiateValidateandEstablishTrust(req, res);
Subject subj = result.getSubject();
Set prins = subj.getPrincipals(PDPrincipal.class);
Iterator iter = prins.iterator();
if (iter.hasNext())
{
		PDPrincipal prin = (PDPrincipal)iter.next();

After obtaining the PDPrincipal, the authentication level can be extracted using the code shown below in Listing 3:

Listing 3. Extracting the authentication level
try {
  PDAttrValue authLevel = 
              (PDAttrValue) prin.getAttributeValue(_pdctx,"AUTHENTICATION_LEVEL");
  String alStr = authLevel.getValue().toString();
  Integer alVal = new Integer(alStr);
  if(alVal.intValue() > 1)
    {
      System.out.println("INFO: CUSTOM TAI - Detected Auth Level2 User");

For more details on extracting and displaying the attributes in the TAM credentials, please see the tutorial Practical TAM Authorization API - Creating a JSP to display the TAM Credential .

Updating the security subject

If the authentication level is greater than one, then a new group membership can be asserted to the security subject. The group name can be defined using the WAS Administration Console as a property in the DetectStepup TAM TAI++ Interceptor Configuration. The format of the property name is custom.tam.tai.authLevelAUTHENTICATION_LEVEL.group. For example, the group name for authentication level of 2 is custom.tam.tai.authLevel2.group. The code to determine the group name from the WAS properties is shown below in Listing 4:

Listing 4. Determining the group name
String grpProp = "custom.tam.tai.authLevel" + alStr + ".group";
String stepupGroup = _wasProps.getProperty(grpProp);

After determining the group name, a new PDPrincipal can be created using the context of the existing PDPrincipal, and the new group can be added to it. The code for doing this task is shown below in Listing 5:

Listing 5. Creating a new PDPrincipal
PDPrincipal newPrin;
newPrin = prin.addGroupMemberships(_pdctx, null, new String[] {stepupGroup});

Adding the group to the PDPrincipal does not alter the group in the TAM User Registry, for example the TAM LDAP Server. This assertion of group membership is specific to this user session only. After creating the new PDPrincipal, the subject can be updated to remove the old PDPrincipal and add the new PDPrincipal using the code shown below in Listing 6:

Listing 6. Updating the subject
subj.getPrincipals().remove(prin);
subj.getPrincipals().add(newPrin);

As the last step in updating the subject, the references to the old groups of the PDPrincipal should be removed from the subject public credentials and the information about the groups of the new PDPrincipal should be add to the subject public credentials. This task is implemented by the private method updateAttributes, and it can be seen in the complete source code that is provided with this article.

The DetectStepup TAM TAI++ Interceptor should return the result object of the class com.ibm.wsspi.security.tai.TAIResult. This is the same object that was extracted from the default TAM TAI++ interceptor.


Installation and configuration

The following tasks have been performed to install and configure the DetectStepup TAM TAI++ Interceptor:

  1. Enabled LTPA in WAS.
  2. Configured a single IBM Tivoli Directory Server (ITDS) as user registry for both TAMeB and WAS.
  3. Created two LDAP groups, password-users and cert-users.
  4. Granded all users group membership of password-users. None of the users are granted group membership of cert-users.
  5. Enabled forms authentication and SSL certificate authentication in TAMeB.
  6. Configured step-up authentication and authentication levels in TAMeB. The authentication levels in sequence are unauthenticated, password, and ssl. The sample TAMeB configuration file is shown below in Listing 7:
Listing 7. Sample TAMeB authentication level configuration
[authentication-levels]
#----------------------
# STEP UP
#----------------------

# authentication levels
#
# Syntax:
# level = <method-name>
#
# Valid method names are:
#   unauthenticated
#   password
#   token-card
#   ssl
#   ext-auth-interface
#
level = unauthenticated
level = password
level = ssl
  1. Updated the TAMeB Step-up login page to delete the LTPA token cookies. This is required to force the DetectStepup TAM TAI++ Interceptor to detect the step-up. The sample Javascript code is shown below in Listing 8:
Listing 8. JavaScript code to delete LTPA token
<script language="javascript">
document.cookie = "LtpaToken2=; path=/junc1/;";
document.cookie = "LtpaToken=; path=/junc1/; ";
</script>
  1. Created a user account in TAM for configuring trust between TAMeB and WAS. The basicauth-dummy-passwd property of the TAMeB configuration file has been updated with the password of this user account.
  2. Compiled the DetectStepup Custom TAM TAI++ using Rational® Application Developer (RAD) and exported as jar file customTAI.jar.
  3. Copied the customTAI.jar file into <WebSphere App Server>/lib/ext.
  4. Using the WAS Administration Console, added the TAI interceptor custom.tam.tai.DetectStepup. Please refer to Table 1 shown below for the custom properties that have been defined and their sample values.
  5. Restarted WAS.
  6. Deployed the sample Web application tai.war . This application is used for testing only. Any similar Web application can be used instead of this sample application. The context root is set to /tai. The sample Web application uses two roles, authLevel1 and authLevel2. Role authLevel1 is mapped to group password-users. Role authLevel2 is mapped to group cert-users.
  7. Regenerated and updated the Web server plug-in.
  8. Created an SSL junction junc1 with the options -t ssl -b supply -c iv_creds in TAMeB to point to the SSL port of the IBM HTTP Server.
  9. Created a POP called pop-cert in TAMeB to force step-up authentication.
  10. Attached the POP to l2.jsp of the sample web application. The TAM commands to display the POP pop-cert are shown below in Listing 9:
Listing 9. TAM commands to display POP pop-cert
pdadmin sec_master> pop show pop-cert
    Protected object policy:  pop-cert
    Description:
    Warning:  No
    Audit level:  none
    Quality of protection:  none
    Time of day access:  sun, mon, tue, wed, thu, fri, sat, :anytime:local
    IP Endpoint Authentication Method Policy
        Auth Level: 2          Network: Any Other Network

pdadmin sec_master> pop find pop-cert
/WebSEAL/iptam1-default/junc1/tai/l2.jsp
  1. Used dhe default TAMeB ACL default-webseal to restrict access to the sample Web application.
  2. Created a self-signed SSL certificate for an active TAM user, that is, the Distinguished Name (DN) of the SSL certificate matches the DN of an active TAM user.
  3. Installed the SSL certificate in Internet Explorer. Imported the public key of the SSL certificate into TAMeB key database.
Table 1. TAI++ Interceptor configuration in WAS
Custom property nameSample value
com.ibm.websphere.security.webseal.checkViaHeader false
com.ibm.websphere.security.webseal.configURLfile:/c:/apps/IBM/WebSphere/AppServer/profiles/AppSrv01/config/itfim/ipfim1-server1/nodes/ipfim1Node01Cell/ipfim1Node01/server1/amconfig.conf
com.ibm.websphere.security.webseal.id iv-creds
com.ibm.websphere.security.webseal.loginIdipuser3
com.ibm.websphere.security.webseal.ssoPwdExpiry 0
custom.tam.tai.authLevel2.groupcert-users

Testing

The DetectStepup TAM TAI++ Interceptor has been tested in the environment comprised of:

  • IBM WebSphere Application Server Network Deployment 6.0.2.7
  • IBM HTTP Server 6.0
  • IBM Tivoli Access Manager for eBusiness (TAMeB) version 6.0.0.3
  • IBM Tivoli Directory Server (ITDS) version 6.0



A sample Web application tai.war has been installed on the WAS to perform the testing. The tai.war is included in the zip file that is provided with this article. The following scenarios have been tested:

  • Scenario 1: User performs a login to an application using password, that is, authentication level 1. After successful login, user performs a step-up authentication using SSL certificate, that is, authentication level 2. The application can detect the change in the authentication level using the role membership of the user.
  • Scenario 2: After successful step-up authentication, the same user performs another login using password and opens a new session. The application can detect that the authentication level of the user in the new session is 1.
  • Scenario 3: User performs a login to the application using an SSL certificate, that is, authentication level 2. The application can detect that the authentication level of the user is 2 using the role membership.

Scenario 1

  1. User ipuser10 opens a Web browser and tries to access the URL https://<TAMeB Server>/<Junction>/l1.jsp
  2. TAMeB prompts the user to login. User ipuser10 performs the login using password, that is,. authentication level 1. The application will display the user details. Please refer to Figure 2-1 to see the details of the subject as displayed by the application. Please note the role membership of the user.
    Figure 2-2 shows the subject credential details as displayed by the application. Please note the group membership of the user.
    Figure 2-3 shows the TAM credential attributes as displayed by the application. Please note the authentication level (AUTHENTICATION_LEVEL) and the group membership (AZN_CRED_GROUP_REGISTRY_IDS) attributes.
  3. User clicks on the Stepup Link (Figure 2-1) to perform step-up authentication. TAMeB prompts for SSL certificate. User provides the SSL certificate. TAMeB authenticates the user and generates new credentials. Please refer to Figure 3-1 to see the details of the new Subject as displayed by the application. Please note the change in the role membership of the user.
    Figure 3-2 shows the new subject credential details as displayed by the application. Please note the change in the group membership of the user.
    Figure 3-3 shows the TAM credential attributes as displayed by the application. Please note that only the authentication level (AUTHENTICATION_LEVEL) of the user is changed. The group membership (AZN_CRED_GROUP_REGISTRY_IDS) of the user is not changed in the TAM credentials.
Figure 2-1. Subject details - after login using password
Subject details - after login using password
Figure 2-2. Subject credential details - after login using password
Subject credential details - after login using password
Figure 2-3. TAM credential details - after login using password
TAM credential details - after login using password
Figure 3-1. Subject details - after step-up using certificate
Subject details - after step-up using certificate
Figure 3-2. Subject credential details - after step-up using certificate
Subject credential details - after step-up using certificate
Figure 3-3. TAM credential details - after step-up using certificate
TAM credential details - after step-up using certificate

Scenario 2

  1. After completing all the steps in Scenario 1, user ipuser10 opens a new browser session and tries to access the URL https://<TAMeB Server>/<Junction>/l1.jsp.
  2. User repeats Step 2 of Scenario 1. The user details displayed by the application will be exactly as shown above in Figure 2-1, Figure 2-2 and Figure 2-3, that is, the application considers the user authentication level as 1 only.

Scenario 3

  1. User ipuser10 opens a new browser and tries to access the URL https://<TAMeB Server>/<Junction>/l1.jsp.
  2. TAMeB prompts the user to login. User performs a login using SSL certificate. The user details displayed by the application will be exactly as shown above in Figure 3-1, Figure 3-2 and Figure 3-3 i.e. the application considers the user authentication level as 2.

Summary

Strong authentication mechanisms provide enhanced security to the data and the applications. Step-up authentication enforces the users to use an authentication mechanism of higher strength to gain more access privileges. IBM Tivoli Access Manager for eBusiness (TAMeB) supports strong authentication mechanisms and step-up authentication and provides single sign on (SSO) to Web applications. In this article, we have explained how to leverage the authentication level of the user supplied by TAMeB to control access in a Web application hosted on a WebSphere Application Server. We have described the procedure to develop a Custom TAM TAI++ Interceptor called DetectStepup TAM TAI++ Interceptor that can assert the group membership of the users based on their authentication level. The article also includes the steps to install and configure the DetectStepup TAM TAI++ Interceptor. The test scenarios and the test results have also been explained in the article. A sample Web application developed and used for testing is also provided with this article.


Acknowledgements

The authors would like to thank Keys Botzum (IBM) and Shane Weeden (IBM) for their valuable comments and reviews.


Download

DescriptionNameSize
Source Code for this articleCode-DetectStepupInTAI.zip20KB

Resources

Learn

Get products and technologies

  • Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational, Tivoli, and WebSphere.

Discuss

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 Security on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Security, Tivoli
ArticleID=260783
ArticleTitle=Custom TAM TAI++ Interceptor to detect step-up authentication
publish-date=11212007