Trust Association Interceptor

improve this page | report issue


IBM Mobile Foundation provides a Java library to facilitate the authentication of external resources through IBM WebSphere’s Trust Association Interceptors.

The Java library is provided as a JAR file (

This tutorial shows how to protect a simple Java Servlet, TAI/GetBalance, by using a scope (accessRestricted).



Server setup

  1. Download the Security Tools .zip from the MobileFirst Operations Console → Download Center → Tools tab. In it you will find a archive. Unpack this zip.
  2. Add the file to the WebSphere Application Server instance inside usr/extension/lib.
  3. Add the file to the WebSphere Application Server instance inside usr/extension/lib/features.

web.xml setup

Add a security constraint and a security role to the web.xml file of the WebSphere Application Server instance:


<security-role id="SecurityRole_TAIUserRole">
   <description>This is the role that Mobile Foundation OAuthTAI uses to protect the resource, and it is mandatory to map it to 'All Authenticated in Application' in WebSphere Application Server full profile and to 'ALL_AUTHENTICATED_USERS' in WebSphere Application Server Liberty.</description>


Modify the WebSphere Application Server server.xml file to your external resource.

  • Configure the feature manager to include the following features:

  • Add a security role as a class annotation in your Java servlet :

@ServletSecurity(@HttpConstraint(rolesAllowed = "TAIUserRole"))

If you are using servlet-2.x , you need to define the security role in your web.xml file:

<application contextRoot="TAI" id="TrustAssociationInterceptor" location="TAI.war" name="TrustAssociationInterceptor"/>
      <security-role name="TAIUserRole">
         <special-subject type="ALL_AUTHENTICATED_USERS"/>
  • Configure OAuthTAI. This is where URLs are set to be protected:

    <usr_OAuthTAI id="myOAuthTAI" authorizationURL="http://localhost:9080/mfp/api" clientId="ExternalResourceId" clientSecret="ExternalResourcePass" cacheSize="500">
              <securityConstraint httpMethods="GET POST" scope="accessRestricted" securedURLs="/GetBalance"></securityConstraint>
    • authorizationURL: Either your MobileFirst Server (http(s):/your-hostname:port/runtime-name/api), or an external AZ Server such as IBM DataPower.

    • clientID: The Resource server must be a registered confidential client. To learn how to register a confidential client, read the Confidential Clients tutorial. *The confidential-client MUST have the allowed scope authorization.introspect so that it can validate tokens.

    • clientSecret: The Resource server must be a registered confidential client. To learn how to register a confidential client, read the Confidential Clients tutorial.
    • cacheSize (optional): TAI uses the Java-Token-Validator cache to cache tokens and introspection data as values, so that a token that comes in the request from the client won’t need to be introspected again in a short time interval.

      The default size is 50,000 tokens.

      If you want to guarantee that the tokens are introspected on each request, set the cache value to 0.

    • scope: The resource server authenticates against one or more scopes. A scope can be a security check or a scope element mapped to security checks.

Using the Token Introspection Data From the TAI

From your resource, you may want to access the token information that was intercepted and validated by the TAI. You can find the list of data found on the token in the API Reference. To obtain this data, use the WSSubject API:

Map<String, String> credentials = WSSubject.getCallerSubject().getPublicCredentials(Hashtable.class).iterator().next();
JSONObject securityContext = new JSONObject(credentials.get("securityContext"));

Sample application

You can deploy the project on supported application servers (WebSphere Application Server full profile and WebSphere Application Server Liberty profile).
Download the simple Java servlet.

Sample usage

  1. Make sure to update the confidential client and secret values in the MobileFirst Operations Console.
  2. Deploy either of the security checks: UserLogin or PinCodeAttempts.
  3. Register the matching application.
  4. Map the accessRestricted scope to the security check.
  5. Update the client application to make the WLResourceRequest to your servlet URL.
  6. Set the scope of your securityConstraint scope to be the security check that your client needs to authenticate against.
Inclusive terminology note: The Mobile First Platform team is making changes to support the IBM® initiative to replace racially biased and other discriminatory language in our code and content with more inclusive language. While IBM values the use of inclusive language, terms that are outside of IBM's direct influence are sometimes required for the sake of maintaining user understanding. As other industry leaders join IBM in embracing the use of inclusive language, IBM will continue to update the documentation to reflect those changes.
Last modified on January 24, 2017