Tivoli Access Manager Trust Association Interceptor (TAI++)

With the release of WebSphere Application Server 5.1.1 and 6.0, there is a new enhanced implementation of the Tivoli Access Manager Trust Association Interceptor. The existing TAI continues to be supported, but many will wish to use the new TAI as it has significant enhancements. This article describes the new functionality provided by the new TAI and provides configuration instructions and trouble shooting tips.

David Winters (davidwin@au1.ibm.com), Advisory Software Engineer, IBM

David Winters holds a B. Eng. (Electrical and Computer Systems) from the University of Queensland. Currently he is working for Tivoli Security product development organization in the Gold Coast, Australia. He has been working with Tivoli Access Manager and its predecessors since 1998.



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

Kerry Gunn holds a B. IT. (honours) 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.



01 September 2004

Introduction

WebSphere Application Server (WAS) supports Single Sign On (SSO) with perimeter authentication services such as reverse proxies through "Trust Associations". When trust associations are enabled WAS 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 WAS
  • Perform user authentication
  • Insert user credential information into HTTP requests

The module in WAS which handles the trust association is the Trust Association Interceptor (TAI). It is a "pluggable" module whose responsibilities are:

  • Validation of trust with the perimeter authentication service
  • Extraction of credential information from the request

Trust associations have been supported since WAS 3.5 but were able to provide only the userid to the WAS runtime. After the TAI was invoked further user registry searches were required to create the various credentials required for authorization (even if this information was already contained in the request). The TAI interface has been extended in WAS 5.1.1 and WAS 6.0 to support the return of complete credential information. This means that no additional user registry searches are required after the TAI invocation. Be aware that if the WAS server participates in a cluster or makes downstream EJB calls, credential propagation must be enabled in WAS.

A Tivoli Access Manager (TAM) implementation of the new TAI interface is being shipped with both WAS 5.1.1 and WAS 6.0. The configuration steps have changed and are described in more detail later in the article.


Usage Scenario

Figure 1 illustrates the various components involved when using the new Tivoli Access Manager Trust Association Interceptor. The WAS web server "plug-in" has been omitted out to simplify the picture. The TAM WebSEAL server could be replaced with a TAM Web Plug-in installation.

Figure 1. TAM trust association flow
TAM trust association flow

The flow can be described as follows:

  1. The user hits WebSEAL (possibly via other proxies) and is prompted to authenticate.
  2. WebSEAL authenticates the user, acquires credentials for the user from the user registry and possibly authorizes the request.
  3. WebSEAL augments the request with an additional HTTP header (iv-creds) that contains the user's credentials. The password contained in the Basic Authentication header is changed so it matches a configured SSO user. This request is sent to WAS.
  4. WAS receives the request and calls a TAI method to determine whether the request is from a perimeter authentication service that has already authenticated the user.
  5. WAS calls a TAI method to establish trust with the perimeter authentication server and retrieve the credentials. This method establishes trust with WebSEAL by checking the BA header contains the correct password for the configured SSO user. The TAM authorization server is contacted to make this decision. The TAI is transport agnostic and processes HTTP and HTTPS requests in an identical manner. Trust between WebSEAL and WAS cannot be established using mutually authenticated SSL sessions and can only be established by verifying the SSO password. No checking of certificates is performed by the TAI. The iv-creds header is then extracted from the request and used to construct a PDPrincipal object. A credential object containing user and group information is constructed from information contained in the PDPrincipal. The Principal and the Credential objects are inserted into a JAAS Subject which is returned from the call. At this point WAS has valid credentials that it can use for making authorization decisions in the usual J2EE manner. In addition, the Subject now contains the PDPrincipal object which application code can access if needed.
  6. If a remote call is made to an EJB on a downstream server. The credential information (that was initially extracted in the TAI) is serialized and sent to the downstream server. In addition, if a cluster is in place, the serialized Subject is also replicated horizontally using the WAS propagation framework. Refer to the InfoCenter for details.

The important points to note here are:

  • WebSEAL needs to insert the iv-creds header into the request, not the iv-user header
  • The new TAI does not directly contact LDAP unlike the previous TAI. It instead contacts the TAM Authorization Server which validates the SSO password to establish trust with WebSEAL . This means that additional configuration is required on the WAS side to ensure that the TAI can reach the TAM Authorization Server.
  • The Credential object inserted into the Subject by the TAI means WAS does not have to perform any additional user registry searches as part of the authentication process.
  • If the TAM JACC provider is configured in WAS 6.0, the Principal object inserted into the Subject by the TAI can be used to make authorization decisions. Otherwise native WAS authorization will still work.

Configuration

Configuring the new TAM TAI, (which is named com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus in WAS ), includes configuration steps at both TAM WebSEAL/Web Plug-in and WAS. The TAM TAI properties differ slightly between WAS versions.

TAM Configuration

A user needs to be created in TAM that will be the WebSEAL trusted user, or Single sign-on user, used by the TAI as part of trust establishment.

An example of creating a user using pdadmin in TAM 5.1 is:

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

WebSEAL Configuration

A junction needs to be created between the WebSEAL instance and WebSphere Application Server ensuring that the iv-creds and the HTTP Basic Authentication headers are passed in the request. The Basic Authentication header should contain the password for the WebSEAL trusted user (i.e. the Single sign-on user). The username in the Basic Authentication header is incidental and the value does not matter. The TAI will use the login id property value configured in WAS as the user to authenticate with the password in the Basic Authentication header.

An example of creating a junction in WebSEAL 5.1 is:

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

  • The -b supply option ensures that the WebSEAL server passes the HTTP Basic Authentication header in the request
  • The -c iv-creds option ensures that the WebSEAL server passes the iv-creds header in the request

TAM Web Plug-ins Configuration

When configuring the Plug-in for Web Servers, ensure that the iv-creds and the Basic Authentication headers are being passed in the request. Also ensure that the Basic Authentication header contains the password for the Single sign-on user.

An example of configuring TAM Plug-in for Web Servers 5.1 is:

[common-modules]
authentication = BA
session = session-cookie
post-authzn = BA
post-authzn = iv-headers

[iv-headers]
accept = all
generate = iv-creds

[BA]
strip-hdr = always
add-hdr = supply
supply-password = "sso_user_password"

WAS Configuration

The TAI must validate the credential information passed in the iv-creds header with TAM. Therefore it must be ensured that the Tivoli Access Manager Java runtime environment has been configured and that server SSL configuration has been performed. If the configuration is to occur across multiple WAS servers in a ND then it is required that the properties file generated during server SSL configuration is in the same location on all servers. This location need only be the same relative to the WebSphere install directory if the ${WAS_INSTALL_ROOT} variable is used.

  • If AMWAS for WAS 5.11 or the AM JACC provider for WAS 6.0 has not been configured.
    1. Configure AMJrte.

      An example of configuring AMJrte 5.1 is:

      java -Djava.ext.dirs -Dpd.home="%WAS_HOME%\java\jre\PolicyDirector" com.tivoli.pd.jcfg.PDJrteCfg -action config -was -host "policy_server_host"
    2. Run server SSL configuration

      An example of running server SSL configuration with AMJrte 5.1 is:

      java com.tivoli.pd.jcfg.SvrSslCfg -action config -admin_id "TAM_admin_user" -admin_id_pwd "TAM_admin_user_password" -appsvr_id "app_server_name" -port "app_server_port" -mode remote -policysvr "host:port:rank" -authzsvr "host:port:rank" -cfg_file "cfg_prop_file_to_create" -key_file "cert_and_key_file_to_create"

The following steps need to be completed using the WebSphere Application Server administration console. Note that the screen shots are an indication for WAS 6.0 only.

  • Ensure that LTPA is the active authentication mechanism.
    1. open the security tab
    2. choose the Global Security link
    3. ensure that the Active authentication mechanism is set to Lightweight Third Party Authentication (LTPA)
      1. If not LTPA
        1. choose LTPA in the dropdown box
        2. click apply
        3. save the changes
  • Enable trust association
    1. open the security tab
    2. open the authentication mechanisms tab
    3. choose the LTPA link
    4. in the LTPA configuration choose the Trust Association link

      Figure 2. Choose Trust Association
      Choose Trust Association
    5. set the check box in enable trust association
      1. click apply
      2. save the changes
  • Create the WebSEAL trust association interceptor properties
    1. open the security tab
    2. open the authentication mechanisms tab
    3. choose the LTPA link
    4. in the LTPA configuration choose the Trust Association link
    5. choose the interceptors link
    6. choose the com.ibm.ws.security.web.TAMTrustAssociationInterceptorPlus link. Note that both the new TAI and the old TAI, com.ibm.ws.security.web.WebSealTrustAssociationInterceptor, are available for configuration. For information regarding the old TAI refer to the InfoCenter.

      Figure 3. Choose Interceptor Link
      Choose Interceptor Link
    7. choose the Custom properties link
    8. click the new button to create a new custom property
    9. create the configuration properties, ensuring that apply is pressed between properties
    10. save the changes
    11. stop and restart WebSphere to activate changes

WAS 5.1.1 Only Properties

  1. com.ibm.websphere.security.webseal.mutualSSL (true/false)
    The TAI can be configured so that trust with the reverse proxy has already been validated using a mutually authenticated SSL connection. If the mutual SSL property is set to true then verification of the inbound request from WebSEAL will not be performed for the Single sign-on user. Therefore if mutual SSL is true then the login id property and the Single sign-on password expiry property have no influence. The default value for the mutual SSL property is false. This property is not supported in WAS 6.0 because many customers were under the false impression that the TAI was performing verification of the certificate presented by WebSEAL. While it is still important to secure the communications at the transport level this alone should not form the basis of the trust between WebSEAL and the TAI.

WAS 6.0 Only Properties

  1. com.ibm.websphere.security.webseal.checkViaHeader (true/false)
    The TAI can be configured so that the via header can be ignored when validating trust for a request. If the check via header property is set to false then none of the hosts in the via header need to be trusted. This also means that the trusted hostnames and host port properties do not need to be set in WebSphere. Therefore the only mandatory property when check via header is false is
    • com.ibm.websphere.security.webseal.loginId
    The default value of the check via header property is false.

Common Configuration Properties

  1. com.ibm.websphere.security.webseal.loginId (string)
    The TAI needs to be configured with the username of the WebSEAL trusted user. This is the Single sign-on user that will be authenticated using the password in the Basic Authentication header inserted by WebSEAL in the request. The format of the username is the short name representation.
    This is a mandatory property. If it is not set in WAS then TAI initialization will fail.
  2. com.ibm.websphere.security.webseal.id (comma separated list of strings)
    The TAI can be configured to ensure that specified headers exist in the request. If not all of the configured headers exist in the request then trust can not be established.

    WAS 5.11
    This is a mandatory property in WAS 511 and there is no default value. If this property is not set the TAI initialization will fail.

    WAS 6.0
    The default value for the id property is iv-creds. Any other values set in WebSphere are added to the list along with iv-creds.
  3. com.ibm.websphere.security.webseal.hostnames (comma separated list of strings)
    Any hosts that are trusted need to be listed in this property. If a host is not listed in this property then requests arriving via that host may not be trusted. This depends upon the value of the via depth and the ignore proxy properties.

    WAS 5.1.1
    If the hostnames property is not set in WAS then it is assumed that all requests have come from a trusted host.

    WAS 6.0
    If the checkViaHeader property is not set or is set to false then the trusted hostnames property has no influence.
    If the checkViaHeader property is set to true and the trusted hostnames property is not set in WAS then TAI initialization will fail.
  4. com.ibm.websphere.security.webseal.ports (comma separated list of integers)
    Any hosts that are trusted need to have their ports listed in this property. If a port is not listed in this property then requests arriving from that port may not be trusted. This depends upon the value of the via depth and the ignore proxy properties.

    WAS 6.0
    If the checkViaHeader property is not set or is set to false then the trusted host ports property has no influence.
    If the checkViaHeader property is set to true and the trusted host ports property is not set in WebSphere then TAI initialization will fail.
  5. com.ibm.websphere.security.webseal.viaDepth (positive integer)
    The TAI can be configured to check only a specified number of source hosts in the via header to ensure that those hosts are trusted sources. By default every host in the via header is checked for trust and if any of the hosts are not trusted then trust cannot be established. If not all hosts in the via header are required to be trusted then the via depth property can be set to indicate the number of hosts that are required to be trusted.

    Example

    Via: HTTP/1.1 webseal1:7002, 1.1 webseal2:7001

    If the via depth property is not set, is set to 2 or is set to 0, and a request with the above via header is received then both webseal1:7002 and webseal2:7001 need to be trusted.
    • com.ibm.websphere.security.webseal.hostnames = webseal1,webseal2
    • com.ibm.websphere.security.webseal.ports = 7002,7001

    If the via depth property is set to 1 and the above request is received then only the last host in the via header needs to be trusted.
    • com.ibm.websphere.security.webseal.hostnames = webseal2
    • com.ibm.websphere.security.webseal.ports = 7001

    If the via depth property is set to 0 then all hosts in the via header will be checked for trust.
    If the via depth property is set to a negative value and the check via header property is set to true then the TAI initialization will fail.
    The default value for the via depth property is 0.
  6. com.ibm.websphere.security.webseal.ssoPwdExpiry (positive integer)
    Once trust has been established for a request the password for the Single sign-on user is cached for subsequent trust validation of requests. This saves the TAI from having to re-authenticate the Single sign-on user with Tivoli Access Manager for every request therefore increasing performance. The cache timeout period can be modified by setting the Single sign-on password expiry 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 then the TAI initialization will fail.
    The default value for the password expiry property is 600.
  7. com.ibm.websphere.security.webseal.ignoreProxy (true/false)
    The TAI can be configured so that any hosts in the via header that are proxies do not need to be trusted hosts. It works by checking the comments field of the hosts entry in the via header to see if that host is a proxy. This is not a fail safe method because not all proxies insert comments in the via header indicating that they are proxies.
    The default value of the ignore proxy property is false.

    WAS 6.0
    If the check via header property is set to false then the ignore proxy property has no influence in establishing trust.
  8. com.ibm.websphere.security.webseal.configURL (URL)
    For the TAI to be able to establish trust for a request it requires that SvrSslCfg has been run for the WebSphere Java Virtual Machine resulting in a properties file being created. This properties file is used by the TAI to create a context so that the SSO password can be validated by TAM.
    If the configuration is to occur across multiple WAS servers in a ND then it is required that the properties file generated during server SSL configuration is in the same location on all servers. This location need only be the same relative to the WebSphere install directory if the ${WAS_INSTALL_ROOT} variable is used.

    Example

    com.ibm.websphere.security.webseal.configURL = ${WAS_INSTALL_ROOT}/java/jre/PdPerm.properties

    Using the above property in a ND environment the properties file generated during server SSL configuration must be located in the java\jre location relative to the WebSphere installation directory on all servers.

    WAS 5.1.1
    This is a mandatory property in WAS 5.1.1 and there is no default value. If this property is not set the TAI initialization will fail.

    WAS 6.0
    If this properties file is not at the default url file://java.home/PdPerm.properties
    • where java.home is the fully qualified location of the WebSphere Java Virtual Machine

    then the correct url of the properties file must be set in the config URL property. If this property is not set and the SvrSslCfg generated properties file is not in the default location, the TAI initialization will fail.
    The default value for the config URL property is file://java.home/PdPerm.properties

Trouble Shooting

Turning on Trace

Most problems with the TAI can be diagnosed by looking at the trace generated by WAS. To turn on the TAI tracing ensure that in the WebSphere diagnostic trace service the following is set

  • com.ibm.ws.security.*=all=enabled

Trouble Shooting Checks

If authentication fails for valid users then:

  1. Ensure that the TAI initialization is successful. This can be verified in the trace by checking that the TAMTrustAssociationInterceptorPlus initialization has no errors and that it is added to the list of interceptors. If initialization has failed then check that all mandatory properties exist. In particular ensure that the SvrSslCfg generated properties file exists and the config URL property has the correct value.
  2. Ensure that Tivoli Access Manager Java runtime environment (AMJrte) has been installed and configured and that the SvrSslCfg configuration action has been performed.
  3. If Plug-in for Web Servers is involved in the source of the request. Ensure that the check via header property is not set or is set to false for WebSphere 6 or that the trusted hostnames and ports properties are not set for WebSphere 5.1.1. It cannot be guaranteed what host information, if any, is put into the VIA header by the Plug-in for Web Servers so the via header should be ignored.
  4. If only WebSEAL hosts are involved in the source of the request. Ensure that all trusted WebSEAL hostnames and ports are set correctly in the respective properties.
  5. Ensure that the trusted hostnames are of the correct form. The fully qualified hostname may be required rather than the short name. This can be checked by looking at the Http header names and values for the VIA header in the trace. If unsure then both fully qualified and short hostnames can be added to the trusted hostnames property.
  6. Ensure that the dummy password in the relevant webseald.conf file for the WebSEAL instance or the supply-password configured in Plug-in for Web Servers is the correct password for the user specified in the login id property.
  7. Ensure that the user specified in the login id property has a valid account.
  8. Ensure that the correct headers are being supplied. WebSphere should get the iv-creds and Basic Authentication headers. This can be checked by looking at the Http header names and values in the trace.
  9. Ensure that WebSphere has been restarted if any changes were made to the configuration.
  10. Ensure that the cached password for the single sign-on user has not been set to never expire and that the single sign-on user password has changed. WebSphere may need to be restarted.

Performance problems

The caching of the single sign-on user password is the only available method of effecting performance. Ensure that the cache timeout property is set to a value that will decrease the number of user registry authentications performed by the TAI. The default cache timeout is 600 seconds.


Security Issues

The TAM Trust Association Interceptor is an extremely powerful SSO mechanism, so care must be taken to ensure that every installation is secure.
If an attacker discovers the SSO password then any user can be impersonated. To prevent this password from being discovered the following precautions should be taken:

  • Ensure that all traffic between WebSEAL, IHS and WAS is over SSL. This will help ensure that no one eavesdrops on the requests.
  • Use some form of transport level filtering so that HTTP/S connections from non-WebSEAL hosts are rejected. This will help prevent spoofing of WebSEAL SSO requests if the password is discovered.

It is also worth noting that while the TAI can verify headers in the requests, understand that headers can be easily forged by attackers if you do not control access to the web server and WAS. The key linchpin of the TAI security is the verification of the SSO password. Therefore, applications should examine only the PDPrincipal object (which can be trusted) and should avoid accessing the WebSEAL provided HTTP headers directly which might have been forged if an attacker is able to bypass WebSEAL and connect directly to WAS.

WebSEAL and WAS authentication sessions (as distinct from HTTP sessions) are not synchronized. This can become a problem if LTPA SSO is enabled. In this case the LTPA cookie will be used to determine the user's session information after the initial TAI invocation. This means the following scenario is possible:

  1. User A logs into WebSEAL and the TAI signs them onto WAS
  2. WAS returns an LTPA cookie to the browser
  3. User A logs out of WebSEAL
  4. User B logs into WebSEAL and the LTPA cookie erroneously signs them onto WAS as user A

This can be prevented by turning off LTPA SSO or embedding some Javascript in the WebSEAL logout page and login page that empties and expires all of the backend authentication cookies. The downside of turning off LTPA SSO is that the TAI will be invoked for each request likely negatively impacting performance.

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


  • Bluemix Developers Community

    Get samples, articles, product docs, and community resources to help build, deploy, and manage your cloud apps.

  • Security

    Pragmatic, intelligent, risk-based IT Security practices.

  • DevOps Services

    Software development in the cloud. Register today to create a project.

  • IBM evaluation software

    Evaluate IBM software and solutions, and transform challenges into opportunities.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Security, Tivoli (service management), Tivoli, WebSphere
ArticleID=82849
ArticleTitle=Tivoli Access Manager Trust Association Interceptor (TAI++)
publish-date=09012004