Understanding the WebSphere Application Server SAML Trust Association Interceptor

Recent fixpacks to IBM® WebSphere® Application Server versions 7.0, 8.0 and 8.5 include a new SAML Trust Association Interceptor (TAI) that introduces new advanced single sign on capabilities. The TAI includes many properties, and understanding what these options do and when to use them can be a challenge. The purpose of this article is to help you make sense of the SAML TAI. This content is part of the IBM WebSphere Developer Technical Journal.


Martin Lansche, Consulting IT Specialist, IBM

Martin Lansche is a Consulting IT Specialist and is the WebSphere Security Worldwide Lead with IBM Software Services for WebSphere. Mr Lansche worked in development for 14 years in such disparate areas as VM System Programming and C/C++ compiler tools. He has worked the last 13 years in ISSW, initially performing C++ services, and more recently focusing on custom WebSphere security solutions including integration within Active Directory environments using Kerberos and SPNEGO. His other areas of specialization include WebSphere DataPower SOA Appliances. He holds a B.Sc. degree in Mathematics and Computer Science from York University.

developerWorks Contributing author

Paul Glezen (pglezen@us.ibm.com), Consulting IT Specialist, IBM

Paul Glezen is an IT Specialist with IBM Software Services for WebSphere. He has worked as an IBM Software Group consultant in the area of application development and infrastructure for C++ and Java applications servers since the late 90s. Currently he specializes in development and security configurations for WebSphere Application Server and DataPower appliances.

December 2013 (First published 17 July 2013)

Also available in Chinese


IBM WebSphere Application Server — and stack products running on top of a WebSphere Application Server platform — has had a customizable authentication framework since V5.1 based on the Trust Association Interceptor (TAI) interface. There are multiple product implementations of this interface. In 2012, the WebSphere Application Server full profile edition shipped a new Security Assertion Markup Language (SAML) TAI that is available on WebSphere Application Server versions 7.0, 8.0 and 8.5. (At the time of this writing, the IBM WebSphere Application Server Liberty profile does not have SAML support.) This TAI is by far the most comprehensive TAI available so far. This article will explain:

  • How the SAML TAI can be used.
  • When it is appropriate to use the SAML TAI.
  • How the various SAML TAI properties work together.
  • The intricate path that the SAML TAI weaves through the WebSphere Application Server authorization process.

This article assumes a firm understanding of the WebSphere Application Server authentication process (as described in the article Advanced authentication in WebSphere Application Server), as well as an understanding of:

  • Digital signing
  • Encryption
  • Identity assertion
  • TAIs in general.

The basics: The web single sign on use case

Build security into applications by design

Secure workloads against the latest threats, simplify access control, and comply with regulatory requirements efficiently with Security services in IBM Bluemix.

Sign up for a free trial

The SAML TAI introduces support for a new form of web single sign on (SSO). As we say in our WebSphere Application Server security class, the term "SSO" is considerably overused in the industry, so let’s be very precise in our SSO use case.

SAML has evolved over the years. The SAML 2.0 specifications define a number of profiles and bindings:

  • The SAML profiles describe different message exchange sequences between the parties involved in the SSO interaction.
  • The SAML bindings describe how a particular message is bound to a certain protocol. At any step in a profile's message exchange sequence, the profile may reference one or more bindings as choices for how the messages are to be relayed.

The SAML profiles include:

  • SSO profiles
    • Web Browser SSO Profile
    • Enhanced Client or Proxy Profile
    • Identity Provider Discovery Profile
    • Single Logout Profile
    • Name Identity Management Profile
  • Artifact Resolution Profile
  • Assertion Query/Request Profile
  • Name Identifier Mapping Profile
  • SAML Attribute Profiles

The SAML bindings include:

  • SAML SOAP Binding
  • Reverse SOAP Binding
  • HTTP Redirect Binding
  • HTTP Post Binding
  • HTTP Artifact Binding
  • SAML URI Binding

WebSphere Application Server has supported the SAML SOAP Binding in support of SOAP based web services since fixpack The SAML TAI was introduced in fixpacks,, and in the base product in version The SAML TAI supports only the combination of the Web Browser SSO Profile and the HTTP Post Binding.

As you can see, this is just one of many possible use cases. In fact there are really two variants. Before we describe them, let’s introduce some of the actors involved:

  • Identity Provider (IdP)
  • Service Provider (SP) sometime known as the Relying Party, or RP.

The job of the IdP is to authenticate the end user (exactly how the IdP does this is immaterial), and to produce some assertions or claims about the user. These assertions are digitally signed by the IdP. The SAML specification defines the format of these assertions. The SP receives the assertions and, if the SP is satisfied that the assertions came from a trusted IdP, logs the user in based upon some parts of the assertion.

Let’s also consider an example based upon a real world use case. The Unified Assurance Company (UAC) has a number of corporate customers; for example, the Gamma Business Machine (GBM) company, the Omicron Lumber Company, and the Purple Maple Syrup Company. We consider these four (fictitious) companies to be in an SSO Federation. In this example, employees of these three federation members are known at the Unified Assurance Company (there exist user entries in the UAC LDAP for the external federations’ employees). However, no passwords for the federation members exist in the UAC LDAP.

In this case, Unified Assurance wants to make an IBM WebSphere Portal system available to its external and internal users. Users from GBM will authenticate to a system within GBM, Omicron Lumber users to a system in the Omicron Lumber network, and Purple Maple Syrup users to a system hosted by Google. (The use of a WebSphere Portal system in this example is incidental.)

Figure 1. SSO federation example
SSO federation example

This example shows that the details of how users login to their IdPs are not relevant to United Assurance. For example, GBM users could login via a login form, Omicron Lumber users automatically provide their credentials to their IdP using a SPNEGO authentication, and Purple Syrup users authenticate to their IdP using an SSL client certificate.

Also notice that there are a set of colored private/public key pairs. Each IdP has its own private key, and the SP keeps a copy of all the corresponding public certificates that correspond to these private keys in its IdPTruststore.

The Web Browser SSO Profile describes how SAML assertions can be routed through the users’ browsers via HTTP redirection. The HTTP Post Binding for the Web Browser SSO can have one of two use cases: the browser request goes first to IdP, or the browser request goes first to the SP. Let’s call the former use case the IdP initiated Web SSO (Figure 2).

Figure 2. IdP initiated Web SSO
Figure 2. IdP initiated Web SSO

In the IdP initiated Web SSO use case:

  1. The user starts the process by following a link to a URL at the IdP. As discussed above, the user authenticates to the IdP.
  2. Based on configuration in the IdP and the original URL provided to the IdP, a SAML response is created and sent via an HTTP Post redirect to an Assertion Consumer Service (ACS) in the SP. This SAML response is signed by the IdP.
  3. The SAML TAI consumes the SAML response and logs the user in. In this example, the user identity exists in the UAC LDAP. Know, however, that this is not a requirement for SAML Web SSO. A JAAS subject is created in memory, and various WebSphere Application Server security tokens are created, including an SSOToken, which is also known as the LtpaToken2. From this SSOToken, an LtpaToken2 cookie is created.
  4. With the user logged in, the request is dispatched to the ACS. It is an application whose sole purpose is to redirect the user to the correct landing page after being logged in by the SAML TAI. The ACS has a Java™ EE security constraint defined, in order to cause the WebSphere Application Server container security and the SAML TAI to be called. An ACS application is shipped as part of the support for the SAML TAI. If desired, your business application can be modified to include ACS functionality by adding a new servlet accepting an HTTP POST. The servlet would then just “forward” to the correct “landing” page rather than perform the redirect in the next step.
  5. The ACS redirects the user to the landing page for the application (possibly based upon something in request, or possibly based on configuration). In this example, this URL is: https://benefits-portal.uac.com/wps/myportal. This HTTP redirection includes the new LtpaToken2 cookie. The browser follows the redirection, and resends the LtpaToken2.
  6. The SAML TAI is called again, this time to check if there is a SAML response in the request. There is not, but there is an LtpaToken2 cookie, so the standard Web Inbound login configuration processing occurs (described later).

One limitation of this approach is that the user needs to invoke a GET link to a URL hosted by the IdP. Consider the example: users at GBM would need to know the GBM-specific URL to login to UAC Portal, Omicron employees the (different) Omicron URL, and Purple Maple Syrup employees the (different) Purple Maple Syrup URL. After each of these groups has logged in to the UAC portal, they are all logged in as https://benefits-portal.uac.com/wps/myportal.

Another limitation of this approach is that a single IdP could be used to authenticate users for multiple service providers. The GBM users might also use that same SSO IdP to login to car rental systems with which GBM has relationships. Yet the URLs for the UAC portal and the car rental systems are (to the user’s point of view) hosted on the same GBM IdP server. That can be confusing to users.

To address these limitations, it is common for the service provider to develop brand recognition, regardless which federation partner the user is from. Each user would click on a link that contains https://benefits-portal.uac.com. The user targets his browser to the service provider first, and the service provider starts the SSO process. The WebSphere Application Server SAML TAI supports this second use case; via configuration, the SAML TAI redirects the user to the IdP. We will call this the SP Redirect to IdP Web SSO use case (Figure 3).

Figure 3. SP Redirect to IdP
Figure 3. SP Redirect to IdP

In the SP Redirects to IdP Web SSO use case:

  1. The user starts the process by following a link to the application’s URL at the SP. In this example, this would be https://benefits-portal.uac.com/wps/myportal.
  2. The SAML TAI is called twice. Because this URL is not the ACS, the TAI does not initially intercept the request. The Web Inbound configuration looks for an LtpaToken2 cookie. None is found. The SAML TAI is called a second time. Based on some data in the incoming request and the TAI configuration, the TAI returns an HTTP 302 redirect to the correct IdP (ways of determining which is the correct IdP for any particular request is discussed below). A cookie is set by the TAI. This is set to the value of the original referrer URL, which in this example is https://benefits-portal.uac.com/wps/myportal. As discussed above, the user authenticates to the IdP.

Steps 3 through 7 are the same as steps 2 through 6 in the IdP initiated Web SSO use case.

Section 4.1.2 of the OASIS Standard shows the basic template for SSO using the web POST binding. Steps 1 through 4 are optional. The steps beginning at step 5 in the template is what we have termed the IdP initiated Web SSO use case. WebSphere Application Server allows for a flow that starts at the service provider (WebSphere Application Server), without implementing the SP-initiated SSO standard flow defined in steps 1 through 4.

To support these standard SP-initiated SSO steps, our TAI would need to generate a SAMLRequest, then redirect the user to the IdP. The IdP would then send back a SAMLResponse. This is considered a solicited response. WebSphere Application Server’s SAML TAI does not solicit a response. It simply redirects the user to the IdP's login page. After logging in, the IdP generates a SAMLResponse. Because this SAMLResponse is not a reply based upon a SAMLRequest, it is considered unsolicited. This unsolicited use case is what we have termed in this paper the SP Redirect to IdP Web SSO use case

This behavior is documented in WebSphere Application Server Information Center.

The WebSphere Application Server SAML TAI

In order to make SAML web SSO functionality available in WebSphere Application Server V8.5 (and in versions 7.0 and 8.0), the functionality was implemented in a Trust Association Interceptor (TAI). (This article has a full discussion of WebSphere Application Server TAIs.) The full class name of the SAML TAI is com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor. These important points impact the SAML web SSO TAI:

  • Administrative security must be enabled.
  • The SAML TAI can be defined at the global or other security domain.
  • The domain in which the SAML TAI is configured must have application security enabled. It must also have TAIs enabled, and the SAML TAI configured.
  • During login of the user into WebSphere Application Server, the SAML TAI saves a copy of the SAML assertions from the POST request in the private credentials of the user’s Subject (for outbound web service calls, for example).

    Subject Attribute Propagation

    must be enabled in order for this custom (not found in the User Registry) information to propagate from server to server in the cell. Because these SAML assertions are not obtainable from the WebSphere Application Server registry, an appropriate custom cache key is defined for the Subject. (The subtle implications of Subject propagation, custom cache keys, and TAIs are beyond the scope of this paper. See this article for a thorough explanation.)
  • The SAML TAI supports multiple applications; each application can have its own ACS URL.
  • Each application can interact with multiple IdPs. Each IdP can be configured differently.
  • The SAML TAI only supports the Web SSO Profile, and only the HTTP Post Binding.

It is important that you fully understand this last point, the ramification of which is that there is only a single HTTP POST message that flows from the IdP to the WebSphere Application Server SAML TAI that contains the SAML Response object within the POST body. The WebSphere Application Server SAML TAI logs the user in based on that SAML Response object, and returns an LtpaToken2 cookie. The profile and binding are suitable for arriving at an application’s authenticated landing page. Subsequent interactions from the browser maintain the user’s login context based upon the LtpaToken2 cookie returned by the HTTP client, typically the user’s browser.

We bring this up to point out that while the SAML assertions contained in that POST allow for a somewhat “portable” token, that portable token is immediately replaced by a WebSphere-specific LtpaToken2 cookie. This model fits well with users with browsers. It does not fit well with other HTTP application clients that do not have a model of “login to a landing page and maintain login state via a cookie.” For example, a RESTful web service application that expects to use the full array of HTTP methods GET, PUT, POST, and DELETE would have to be architected to:

  1. Determine if the application has an LtpaToken2 cookie.
  2. If none, then get a SAML response and follow the redirected POST to the ACS so the client application can get an LtpaToken2 cookie.
  3. Only after the above is successful, then perform the real web service operation the application was trying to invoke in the first place.

Because of the custom cache key in the Subject and in the LtpaToken2, Subject attribute propagation must be enabled to enable the full user identity to propagate between JVMs in the WebSphere SSO “cell”. This can include JMX call backs to the original server where the user has logged in.

SAML TAI and the web inbound login configuration

The logic flow shown in Figure 20 of this article has been refined in Figure 4 below to support the SAML TAI. If the user has an LtpaToken2 cookie, and the browser POSTs to the ACS with a new SAML assertion, then the original LtpaToken2 cookie must be ignored, and the user identity from the SAML assertion should be used in the creation of a new Subject. This change in behaviour is controlled by the general custom property com.ibm.websphere.security.InvokeTAIbeforeSSO, which is given the value of the SAML TAI class (com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor). If the SAML TAI is defined at the Global level, add this custom property on the Global Security page. If the SAML TAI is defined within a Security domain, add this custom property on the Custom Properties of the Security domain.

The first part of the new logic flow is shown in Figure 4.

Figure 4. The SAML TAI processes SAML Tokens before LtpaToken2
Figure 4. The SAML TAI processes SAML Tokens before LtpaToken2

In other words, with the property InvokeTAIbeforeSSO properly defined, the SAML TAI is called before the SSO Token (the LtpaToken2 cookie) is examined. The checkSubject? steps above will be explained below.

To support the SP Redirects to IdP Web SSO use case, the SAML TAI can potentially be called a number of times – if there is no LtpaToken2, and there is no SAML assertion, the SAML TAI logic can be called when a second special security property, com.ibm.websphere.security.DeferTAItoSSO, which is given the value of the SAML TAI class. This property is also defined as a custom property on the Global security page or on the custom properties of the Security domain in which the SAML TAI is enabled.

When the SP Redirects to IdP Web SSO use case is examined, you can see there are scenarios where the SAML TAI could be called multiple times on the initial login. See Figure 5 to understand the processing of the SAML TAI support for SP Redirects to IdP Web SSO.

Figure 5. SAML TAI support for SP Redirects to IdP Web SSO
Figure 5. SAML TAI support for “SP Redirects to IdP Web SSO”

With the trace specification set to com.ibm.ws.security.web.saml.*=all, examination of trace confirms the logic in these two flowcharts during a SP Redirects to IdP Web SSO.

To help with this experiment, we have two TAIs in this example: a FakeTAI that does not intercept, but does emit a message in the log (Listing 1).

Listing 1.
[3/20/13 16:22:49:635 EDT] 00000024 TrustAssociat A   SECJ0121I: Trust Association Init 
class com.ibm.issw.security.FakeTAI loaded successfully
[3/20/13 16:22:49:640 EDT] 00000024 TrustAssociat A   SECJ0122I: Trust Association Init 
Interceptor signature: 1.2
[3/20/13 16:22:49:642 EDT] 00000024 TrustAssociat A   SECJ0121I: Trust Association Init 
class com.ibm.ws.security.web.saml.ACSTrustAssociationInterceptor loaded successfully
[3/20/13 16:22:49:644 EDT] 00000024 ACSTrustAssoc >  initialize Entry
[3/20/13 16:22:49:670 EDT] 00000024 ACSTrustAssoc <  initialize Exit
[3/20/13 16:22:49:670 EDT] 00000024 TrustAssociat A   SECJ0122I: Trust Association Init 
Interceptor signature: <null>

In Listing 2, the SAML TAI is called before SSO processing.

Listing 2.
[3/20/13 16:22:49:673 EDT] 00000024 ACSTrustAssoc >  isFirstPass Entry
[3/20/13 16:22:49:674 EDT] 00000024 ACSTrustAssoc 3   Request does not contain 
SAMLResponse, TAI will be skipped and deferred.
[3/20/13 16:22:49:675 EDT] 00000024 ACSTrustAssoc 3   Request is scoped to this TAI.

Next is the SSO processing. First the Fake TAI is called. It does not intercept. Then the SAML TAI is called (Listing 3).

Listing 3.
[3/20/13 16:22:49:679 EDT] 00000024 SystemOut     O   FakeTAI.isTargetInterceptor() 
returns 'false' 
[3/20/13 16:22:49:680 EDT] 00000024 ACSTrustAssoc >  isFirstPass Entry	
[3/20/13 16:22:49:697 EDT] 00000024 SAMLTaiState  3   SAML TAI challenge login: Referer 
URL cookie set https://oc5067386220.ibm.com:9444/HitCountWeb/HitCountServlet
[3/20/13 16:22:49:697 EDT] 00000024 ACSTrustAssoc <  createTAIErrorResult Exit
[3/20/13 16:22:49:697 EDT] 00000024 ACSTrustAssoc <  invokeTAIafterSSO Exit
[3/20/13 16:22:49:698 EDT] 00000024 ACSTrustAssoc <  negotiateValidateandEstablishTrust 

The trace now processes message #3 from Figure 2 (Listing 4).

Listing 4.
[3/20/13 16:22:56:207 EDT] 00000026 ACSTrustAssoc >  isFirstPass Entry
[3/20/13 16:22:56:212 EDT] 00000026 ACSTrustAssoc 3   Request contains SAMLResponse, 
TAI will be processed.
[3/20/13 16:22:56:484 EDT] 00000026 ACSTrustAssoc <  negotiateValidateandEstablishTrust

The user is logged in. An LtpaToken2 cookie is sent to the browser. Since you are using the built-in ACS application, the ACS redirects the browser to the original referrer URL cookie value, which is https://oc5067386220.ibm.com:9444/HitCountWeb/HitCountServlet (The original referrer URL cookie is set via the SAML TAI.)

Message #6 from Figure 2 occurs and arrives next in trace. Again, the SAML TAI is called before the LtpaToken2 cookie is examined (Listing 5).

Listing 5.
[3/20/13 16:22:56:774 EDT] 00000026 ServerCache   I   DYNA1071I: The cache provider 
"default" is being used.
[3/20/13 16:22:57:627 EDT] 00000025 ACSTrustAssoc >  isFirstPass Entry
[3/20/13 16:22:57:627 EDT] 00000025 ACSTrustAssoc 3   Request does not contain 
SAMLResponse, TAI will be skipped and deferred.
[3/20/13 16:22:57:628 EDT] 00000025 ACSTrustAssoc 3   Request is scoped to this TAI.

Notice that the LtpaToken2 cookie is found, and neither the Fake TAI nor the SAML TAI is called again. The HitCount application is called and reports the identity of the caller – which was obtained from the Subject, which was generated from the SAML Response in message #3 (Listing 6).

Listing 6.
[3/20/13 16:22:57:632 EDT] 00000025 SystemOut     O   J2EE APIs: HitCount received 
request from Alice

SAML TAI properties

While the implementation as a TAI enables back-porting of function into earlier versions of WebSphere Application Server, it does result in a large number of TAI properties that must be defined properly for the TAI to proceed (if you are familiar with the SPNEGO TAI in WebSphere Application Server V6.1, you should contrast the complexity of setting the SPNEGO TAI properties with the integrated equivalent function in the SPNEGO Web Authenticator in WebSphere Application Server V7.0, where the SPNEGO configuration is a first class construct in the administration console.)

The SAML TAI properties are documented in the Information Center. There is a hierarchy of properties. Expanding on the details in the Information Center:

  • Global properties are applicable to all SSO partners (those partners hosting IdPs) that are configured for the SAML TAI. These properties are not prefixed with “sso_<id>” (where <id> is an integer). Most of the Global properties can be overridden by the IdP specific equivalents.
  • Service provider properties are applicable to a service provider and are grouped together for each SSO service provider partner under a unique sso_<id>.
  • IdP properties are applicable to identity providers that are configured for the SAML TAI. To assign unique property names that identify each identity provider partner, an idp_<id> is embedded in the property name and used to group the properties that are associated with each SSO IdP partner. For a given service provider, the configured IdP properties are prefixed with “sso_<id>.idp_<id^>”.

Instead of explaining what all of the properties are for, we will group them together to show how they apply to solve certain problems. (Not all properties will be explained here.)

IdP Initiated SSO: What properties are needed to complete SSO?

After authentication to the IdP, the IdP redirects the browser to the appropriate ACS URL. The SAML TAI determines which (if any) service provider configuration to apply to the request.

To determine which configuration to apply, the SAML TAI matches the URL with the pattern defined in all sso_<n>. sp.acsUrl properties. If it finds a match, it applies all the sso_<n> (service provider) properties, plus any global properties.

During processing of the SAMLResponse to the ACS application, the SAML TAI will enforce that the AudienceRestriction element in the SAMLResponse matches the sso_<n>.sp.EntityID. If not set, this EntityID property takes its value from the sso_<n>.sp.acsURL property.

In the event that the user POSTs to the ACS URL with an invalid SAML Response (perhaps issued by another IdP), then the URL specified by the sso_<n>.acsErrorPage is returned via a redirect.

Before looking at how to extract user identity from the SAML response, how to create the user identity, where to redirect to after login is successful, how to trust the request from a trusted IdP, and how to secure the request from prying eyes, let’s first consider the additional properties for the SP Redirects to IdP Web SSO use case.

SP Redirects to IdP Web SSO: What properties are needed to complete SSO?

Consider the case shown in Figure 3. A GBM user opens his browser to https://benefits-portal.uac.com/wps/myportal. As described above, the TAI does not immediately intercept; this is not an ACS URL. Because this is the first request, there is no LtpaToken2 cookie. As mentioned earlier, based on some data in the incoming request, the SAML TAI returns an HTTP 302 redirect to the correct IdP. How can the SAML TAI know to redirect this request to (in this example) the GBM IdP and not one of the other IdPs?

The SAML TAI filter property, sso_<n>.sp.filter, controls how the SAML TAI determines if a particular URL should initiate a service provider redirection to the IdP. The filter functions the same as the filter for the SPNEGO TAI. In the absence of a filter setting, all requests to Java EE protected URLs are intercepted.

APAR PM84513 addresses an issue with multiple SP configurations, each with a unique “filter” definition; the first request to the SAML TAI finds the “filter” that matches to determine which SP configuration to apply for that first request. Without this APAR all subsequent calls to the SAML TAI will continue to use the same SP configuration; subsequent requests will not check for a matching filter condition. It is strongly recommended that you apply this fix.

If the request is intercepted based on the filter, the page specified by the sso_<n>.sp.login.error.page property is returned. If there is only a single IdP, this can be a URL that is usable by that single IdP.

If there are multiple IdPs, then each IdP for the SP configuration will have its own sso_<n>.idp_<m>.SingleSignOnUrl value, specifying the URL that the SAML TAI will redirect to, in order to initiate the SAML SSO. Yet the problem remains: how to determine which “idp_<m>” to choose? If there are multiple IdPs, the login.error.page property can point to an HTML page with multiple IdP links; a more refined solution is where the property refers to a class that implements the interface shown in Listing 7.

Listing 7. IdentityProviderMapping Interface
import javax.servlet.http.HttpServletRequest;
import java.util.String ;
import java.util.ArrayList ;
import com.ibm.websphere.security.NotImplementedException;
import com.ibm.wsspi.security.web.saml.IdentityProviderMapping;
public abstract interface IdentityProviderMapping {
   public abstract String getIdentityProviderOrErrorURL(
      HttpServletRequest req,
      String errMsg, 
      String acs, 
      ArrayList<String> ssoUrls) throws NotImplementedException;

Implement this class, and place the JAR file into <WAS>/lib/ext. You can perform whatever logic you can imagine in your implementation. In the sample source code SampleIDPMapping.java shown in Listing 8, you search for either an ?idp=<URL> parameter, or (on the assumption that the user has visited the site before) a persistent cookie called SAMLIDP.

Listing 8. Extracts from SampleIDPMappingImpl.java class
private static final String COOKIE = "SAMLIDP";
// Assumes that 
//   idp_1 is configured as GBM IdP
//   idp_2 is configured as Omicron Lumber IdP
//   idp_3 is configured as Purple Maple Syrup IdP
// Prefer URL parameter over cookies. So only look for cookies 
// if URL parameter not set.
String idpValue = req.getParameter("idp");
if (idpValue==null) {
   log.finer("URL Parameter was not found, so looking for IDP cookie");
   Cookie[] cookies = req.getCookies();
   if (cookies != null) {
      for (Cookie cookie : cookies) {
         if (cookie.getName().equals(COOKIE)) {
           String cookieValue = cookie.getValue();
if (idpValue.equalsIgnoreCase("omicron")) { 
   // We know that ssoUrls.size() < 1 here
   log.finer("Omicron IDP requested. Returning (ssoUrls.get(1))");
   idpUrl = ssoUrls.get(1);
} else if (idpValue.equalsIgnoreCase("purple")) { 
   // We know that ssoUrls.size() < 1 here
   log.finer("Purple IDP requested. Returning (ssoUrls.get(2))");
   idpUrl = ssoUrls.get(2);
} else { 
   // otherwise return ssoURL[0] - default "gbm"
   log.fine("IDP requested " + idpValue + 
            ". Default to gbm IDP (ssoUrls.get(0))");
   idpUrl = ssoUrls.get(0);

In this example, if neither a cookie nor an “idp=” parameter is provided, the default is the GBM IdP. Another realistic example would be to determine which IdP to use, based on the client IP address (which may, in some situations, be a meaningful datum) of the incoming HttpServletRequest. We do not provide code for this second example.

How does SAML TAI know where to redirect to after WebSphere Application Server login?

After the SAML TAI has processed the SAML Response when POSTed to the ACS, and the WebSphere Application Server security runtime logs the user in and generates a JAAS Subject, the ACS application will either:

  • HTTP 302 redirect the browser to the logged-in landing page.
  • Perform an internal forward to an address in the application. To be able to use this option, the ACS URL must be part of the same web application as the forwarded-to URL. The generic ACS application is unable to perform a forward operation.
  • The SAML Response sent by the IdP can optionally include the URL the SP should redirect to via a SAML attribute called the RelayState.

To support the first of the above options, the generic ACS application uses the sso_<n>.sp.targetURL property. If the IdP sends RelayState, the third option will be used by default. To override the RelayState sent, you can use the sso_<n>.sp.useRelayStateForTarget property. The most common SP-initiated way to specify where to redirect is through the original referrer URL cookie, called the WasSamlSpReqURL cookie.

Why does SAML TAI believe the SAML assertions?

You might be asking the above question. Otherwise, an attacker could craft a properly formed SAML Response, POST to the ACS, and become logged in as anyone he wants. The SAML TAI must confirm that the request came from a trusted IdP. In other words, the SAML TAI must authenticate the IdP. This is performed by confirming the digital signature of the SAML Response.

The SAML Response includes a digital signature of the data. The signature includes a hash of the data using the advertised algorithm in the SAML Response. The output of this hash is then encrypted with the private key held by the IdP. To validate that signature, the SP (the SAML TAI), calculates the hash of the same content, and then decrypts the IdP supplied hash value (the SAML Response includes the public certificate). If they match, then the SP knows that the content has not been changed (this is known as data integrity), and that the content was generated by the holder of that private key corresponding to the public certificate. The issuer of that public certificate must be trusted.

The following properties control the signature confirmation behavior of the SAML TAI:

  • sso_<n>.sp.wantAssertionsSigned
  • sso_<n>.sp.trustAnySigner — Of course, use this one with caution.
  • sso_<n>.sp.trustStore — This is the name of a WebSphere Application Server trust store object containing the signer certificates for your IdPs. It is not the filename of the file, but the object name as seen in the admin console. The default is to use the server’s default SSL configuration, which typically refers to the CellDefaultTrustStore. This is not a good choice, as adding signers to the CellDefaultTrustStore pollutes the trust space of the cell. Instead, you should define a separate IdpTrustStore object containing the necessary certificates.
  • sso_<n>.sp.X509PATH — As an alternative to using a WebSphere trust store object, you can supply the path to a file containing the signing certificates’ intermediary certificates.
  • sso_<n>.sp.CRLPATH — The name of a certificate store containing a certificate revocation list (CRL).
  • sso_<n>.sp.trustedAlias — If your trust store contains multiple certificates, and you want to restrict which certificate from the trust store can be used to validate the signature, specify it with this property.

Once it has determined to intercept the request, the SAML TAI needs to ensure that the identity of the IdP is one of a set of trusted IdPs. There are two options. The IdP can be identified by either:

  • A distinguished name: sso_<n>.idp_<m>.allowedIssuerDN
  • A simple name: sso_<n>.idp_<m>.allowedIssuerName.

By setting one or the other of these properties, you avoid the common trap of accepting SAML assertions that were signed by any certificate issued by a signer in the trustStore. These properties ensure that the assertions were signed by the IdP. This also avoids the certificate management problem inherent in PKI-based solutions; that is, if you save the IdP’s certificate in the truststore, then when that certificate is renewed prior to expiration, you must remember to update all truststores in which it was stored.

Getting these properties set correctly and getting the signing certificates into the truststore can be tricky. There exists a wsadmin AdminTask called importSAMLIdpMetadata to assist you in this effort.

SAML TAI and subsequent requests

After the user logs in, the user’s login session is maintained by an LtpaToken2 cookie. This needs to be examined closely. Consider an example where /app1 is protected by the SAML TAI, and /app0 is not. What is the expected behaviour when the user logs in first to /app0, without SAML, then accesses /app1? There are three possible modes of operation based upon the SAML TAI property sso_<n>.sp.enforceTaiCookie:

  • The default mode of operation occurs when the property has a value of true. In this case, not all LtpaToken2 cookies are equal. When a user whose Subject does not contain a SAMLResponse (because he logged into /app0 first) tries to access /app1, the WebSphere Application Server security runtime detects that this Subject does not contain a SAMLResponse. The request is rejected, and the user is redirected to the IdP to login.
  • If sso_<n>.sp.enforceTaiCookie=false, then all LtpaTokens are “equal,” meaning that a user who logs into another application in the WebSphere Application Server cell without a SAML-based login can re-use that LtpaToken2 cookie for SAML TAI protected applications. In this case, the Subject’s contents are not checked for a SAMLResponse, and the user is authenticated for /app1. This might be your use case, but probably is not.
  • The third mode of operation strictly applies the SAML concept of AudienceRestriction to subsequent authentications. Consider now if /app1 and /app2 are both protected by the SAML TAI, but are configured to use different SSO partners, each with different AudienceRestrictions. The intention of this configuration is for the SAMLResponses to not be considered “equal.” With the default SAML TAI properties, the Subject is checked to contain any SAMLResponse. The sso_<n>.sp.cookieGroup property, if defined, will override this permissive acceptance of any SAMLResponse. The cookieGroup property can be assigned a string that will be added to the WebSphere Application Server Subject; for simplicity, let’s call that string the Saml20TaiSsoPartners.

Consider an example. Assume the sso_1.sp.cookieGroup=app1 and sso_2.sp.cookieGroup=app2. The user logs into /app1. On all interaction with /app1, the runtime ensures that the Subject contains a SAMLResponse and the Saml20TaiSsoPartners contains “app1.” Next, the user tries to access /app2 – and sends the LtpaToken2 cookie. The WebSphere Application Server security runtime ensures that the associated Subject contains a SAMLResponse and checks that the Saml20TaiSsoPartners contains ”app2.” Since is does not, the user is redirected to the IdP configured for sso_2.

The logic to implement the above is represented by the calls to checkSubject? checks in Figure 4 above.

Securing the SAML assertions

ADFS 2.0 specific issue discovered

By default, ADFS expects all certificates used for encryption to include a certificate revocation list (CRL) endpoint. If your certificate does not include a CRL endpoint, you must configure ADFS to not require the CRL. Use the EncryptionCertificateRevocationCheck parameter of the Set-ADFSRelyingPartyTrust cmdlet.

ADFS identifies the Issuer via the Distinguished Name; this is a string. Problems occur if that DN includes a StateOrProvinceName field. Microsoft® uses the unconventional form of “S=” while Java, under WebSphere Application Server, expects that field to be represented by a “ST=”. Because of this difference, you cannot use issuer certificates that include a StateOfProvinceName field.

The HTTP POST to the ACS application should normally occur over an https connection. In fact, many IdPs require the connection to be over SSL. In addition to the encryption provided by the SSL connection, there might be a reason for you to encrypt the payload of the SAML Response object. Remember that the IdP redirects the request through the user’s browser. Through the use of a browser plugin, the user can view the SAML Response as it passes through the browser (the user cannot change the content, as this was cause a failure of the digital signature check, but he could still see the content). If your use case does not require this secondary encryption, then you do not need to encrypt the SAML Response.

To achieve the encryption, the SP (the SAML TAI) uses its own private/public key pair. The IdP is provided with a copy of the public key, via a public certificate, and uses that public certificate to encrypt the content. Only a holder of the private key (the TAI) can decrypt the content. The properties to support the SAML Response encryption are:

  • sso_<n>.sp.keyStore — This is the name of a WebSphere Application Server keystore object containing the personal certificate for your SP. It is not the filename of the file, but the managed object name as seen in the admin console.
  • sso_<n>.sp.keyAlias — The alias of the key in the keystore.
  • sso_<n>.sp.keyPassword — The password needed to access the key.
  • sso_<n>.sp.keyName — Instead of using the key alias, you can optionally specify the full DN of the key to be used.

The IdP needs to receive the public certificate (and any signers). Again, you can use the wsadmin AdminTask exportSAMLSpMetadata to create an XML file that can be imported by the IdP application (depending on your IdP system, you might need to edit the resulting XML to only reference the encryption certificate information).

How to customize the user identity

The IdP asserts a user to the SAML TAI. This user may or may not exist within the WebSphere Application Server user registry, depending on your use case. We say the user is either a local user or an ephemeral user (some WebSphere products, such as IBM Business Process Manager (BPM), require all logged in users to exist in the user registry, so they must be local users).

To assert a local user, specify the SAML TAI property sso_<n>.sp.idMap = localRealm. For local users, the NameID field in the SAML Response is set as the userid in the JAAS Subject (mapping the userid via the userMapImpl property is discussed below). WebSphere Application Server will complete the Subject by querying the user registry.

An ephemeral user is one who is asserted to exist, but is not actually backed by any entries in the underlying user store, such as the LDAP. For ephemeral users, the principalName is obtained from the attribute named in the property sso_<n>.sp.principalName.

To assert an ephemeral user, set the property sso_<n>.sp.idMap = idAssertion. When this is set (and is the default value), there are a number of SAML TAI properties that control exactly what user identity is logged in. The first two identify the element in the SAML Response that is used to populate the principalName and uniqueID, respectively:

  • sso_<n>.sp.principalName
  • sso_<n>.sp.uniqueId

What realm to assign to the userid is determined by the properties:

  • sso_<n>>.sp.realmName
  • sso_<n>.sp.realmNameRange
  • sso_<n>.sp.defaultRealm
  • sso_<n>.sp.useRealm

If using idAssertion, and none of these realm-related properties are set, then the IssuerName defined in the SAML Response is the realm name used.

In addition to the above, there exists two hybrid approaches for establishing user identity. The first hybrid approach uses the idMap value = localRealmThenAssertion. In this mode, the user identity is extracted from the SAML Response and the user registry is searched. If the user is found in the user registry, then the login proceeds as a localRealm user. If the user is not found, then the login proceeds as an idAssertion user.

The second hybrid approach uses the idMap value = idAssertionUsingGroups. This second approach augments the group membership information returned from the user registry for a localRealm user with group information asserted in the SAML Response. (It is meaningless to consider augmenting an ephemeral user’s group membership with data from the user registry as, by definition, the ephemeral user does not exist in the user registry and there would be no additional groups to add.

When group membership is considered from the SAML Response, the name of the group element in the SAML Response is specified by the sso_<n>.sp.groupName property.

Group memberships obtained from the SAML Response can be mapped to user registry groups by setting the sso_<n>.sp.groupMap=localRealm property. Alternatively, group memberships can be asserted in the user’s Subject even when the groups do not exist in the user registry by setting sso_<n>.sp.groupMap= AddGroupsFromLocalRealm.

Consider the example in Figure 6. Instead of the users being asserted existing in the UAC LDAP (localRealm), the Purple users are ephemeral. Their group membership is also asserted via the SAML Response. In particular, their membership in UACGroup is of interest. The other groups are asserted, but are unimportant to the UAC application. The UAC web application that the users access has a security role bound explicitly to the Group UACGroup from an external trusted realm idp.purple.com/adfs/services/trust. You must configure your IdP to generate the appropriate group membership claims in the SAML Response.

Figure 6. Asserting ephemeral identity
Figure 6. Asserting ephemeral identity

Lastly, it is common that the userid/principalName/NameID asserted in SAML Response needs to be converted somewhat before asserting the identity to WebSphere Application Server. Or, perhaps, there is a different element in the SAML Response XML document containing the identity that should be used. The sso_<n>.sp.userMapImpl provides a second plug-point, an interface, for the SAML TAI where you can implement a customized user mapping class that returns the asserted user identity. The interface for the userMapImpl is shown in Listing 9.

Listing 9. UserMapping interface
import java.util.String ;
import com.ibm.websphere.security.NotImplementedException;
import com.ibm.websphere.security.UserMappingException;
import com.ibm.websphere.wssecurity.wssapi.token.SAMLToken;
import com.ibm.wsspi.security.web.saml.UserMapping;

public abstract interface UserMapping {
 public abstract String mapSAMLAssertionToName(SAMLToken samlToken)
			throws UserMappingException, NotImplementedException;

In the second example custom implementation, you want to ignore the NameID element in the SAML Response, and instead establish the user identity from the distinguished name element in the Response (Listing 10).

Listing 10. Extracts from SampleUserMapping.java class
/** Standard ADFS name for a SAML attribute containing the DN. */
public static final String SAML_ATTR_DN = 
public static final String FRIENDLYNAME = "Custom User Mapping";

public String mapSAMLAssertionToName(SAMLToken samlToken)
			throws UserMappingException, NotImplementedException {
   log.entering(CLASSNAME, "mapSAMLAssertionToName");
   String result = null;
   result = getDN(samlToken);
   log.fine(FRIENDLYNAME + " mapped to user " + result);
   log.exiting(CLASSNAME, "mapSAMLAssertionToName");
   return result;

public static String getDN(SAMLToken token) throws UserMappingException {
   String dn = null;
   if (token != null) {
      List<SAMLAttribute< attrList =  token.getSAMLAttributes();
      if (attrList != null  && attrList.size() < 0) {
         for (SAMLAttribute attr : attrList) {
            if (attr.getName().equals(SAML_ATTR_DN)) {
               if (attr.getStringAttributeValue().length > 0) {
                  dn = attr.getStringAttributeValue()[0];
                  log.fine("User Mapping found DN: " + dn);
	…// Error checking code removed.
   return dn;

Setting up the SAML TAI

Here is a crib sheet to help you with the overall steps of setting up the SAML TAI, in the form of some high level architecture-type questions:

  1. What URLs are to be protected by SAML TAI? – You need to determine what URLs (applications), if any, will cause a SP Redirects to IdP Web SSO case. This will be the input to the filter property.
  2. For the SP, what is the ACS URL to which the IdP will redirect?
  3. Will users be logging in as localRealm or idAssertion userids?
  4. Will the SAML Response be encrypted?

For each of your IdPs, you will need to know:

  • What is the IdP vendor?
  • Does that vendor support RelayState?
  • What format does the IdP accept SP metadata?
  • What is the IdP entity ID?
  • Do you have the signing certificate used by the IdP, including full issuer chain?

At a very high level, the WebSphere Application Server administration steps are:

  1. If encrypting SAML Response, use the WebSphere Application Server admin tools to create a new keystore, called (for example) SPKeyStore:
    • Generate private/public key, and public certificate.
    • Export public certificate, possibly as SAML metadata.
  2. Using the admin tools, create a new truststore called (for example) IdPTrustStore. Install signing IdP signing certificate and chains.
  3. Add the SAML TAI (ACSTrustAssociationInterceptor) – do not enable TAIs yet.
  4. Add the TAI to the com.ibm.websphere.security.DeferTAItoSSO custom property (to enable SP Redirects to IdP Web SSO).
  5. Add the TAI to the com.ibm.websphere.security.InvokeTAIbeforeSSO custom property (to prefer SAML token over LtpaToken).
  6. Configure SAML TAI properties.
  7. Install ACS application: <was>/installableApps/WebSphereSamlSP.ear.
  8. Enable TAIs.

Some useful wsadmin AdminTasks related to the SAML TAI are:

  • AdminTask.showSAMLTAISSO()
  • AdminTask.showSAMLIdpPartner()
  • AdminTask.importSAMLIdpMetadata()
  • AdminTask.exportSAMLSpMetadata()

Useful trace specifications:

  • com.ibm.ws.security.web.saml.*
  • com.ibm.ws.security.*

Hints and tips

Don’t point browser directly at the ACS URL unless you are posting a SAML Response for it to process. Otherwise, you will see the authentication challenge for that application. For the shipped ACS, this is a Basic Auth challenge. If you implement your own custom ACS application, this could be a form-based login.

If you write your own UserMapping or IdPMapping class, as shown in the code samples above, use Java logging to integrate this code with the WebSphere Application Server tracing infrastructure. This will let you to dynamically enable or disable tracing in your code.

You should consider what are appropriate validity periods for your LtpaToken2 and SAML tokens. The default validity period for Ltpa is 120 minutes. Consider what happens when the SAML token is only 60 minutes. While outside of the scope of this article, WebSphere Application Server web services can propagate the SAML token outbound via SOAP web services containing WS-Security SAML tokens. We have encountered cases where this outbound web services call fails because the SOAP service provider receiving that SAML token after it has expired rightly rejects it. If your architecture includes this SAML token propagation use case, you should ensure that the validity time lengths for Ltpa and SAML match (in fact, make the SAML lifetime slightly longer than the Ltpa lifetime).


This article provided some guidance to help administrators of systems running on IBM WebSphere Application Server understand the new SAML Web TAI, how it works within the existing web security runtime within WebSphere Application Server, how it subtly changes that security, how the large number of custom TAI properties interact with each, and when to use these custom TAI properties (and when they are not needed). A couple of sample implementations of classes showing how to customize the login process were also provided.


The authors thank colleagues Jens Engelke, Michael Whale, Simon Kapadia, Bill O’Donnell, and Chunlong Liang for their valuable input and assistance.



Get products and technologies



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

Zone=WebSphere, Security
ArticleTitle=Understanding the WebSphere Application Server SAML Trust Association Interceptor