Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
132 lines (104 sloc) 6.59 KB
layout title breadcrumb_title relevantTo weight downloads
Trust Association Interceptor
Trust Association Interceptor


{: #overview } {{ }} 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

{: #server-setup }

  1. Download the Security Tools .zip from the {{ }} → 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

{: #webxml-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 {{ }} 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>


{: #serverxml } 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 {{ }} (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

{: #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

{: #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

{: #sample-usage }

  1. Make sure to update the confidential client and secret values in the {{ }}.
  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.
You can’t perform that action at this time.