Introducing the LocalSTSClient

Share this post:

 Introducing the LocalSTSClient

In IBM Security Access Manager 9.0, the Security Token Service (STS) from Federated Identity Manager (TFIM) was made available. The STS is essential when needing to transform a security token from one type to another. As usage of the STS has grown, we have seen adoption of simple security tokens such as JWT. The need to call the STS to decode such tokens from within other ISAM contexts has also increased. Tokens are consumed in a variety of places in ISAM, from the authentication service, OAuth/OIDC mapping rules and from the STS itself. All JavaScript contexts potentially need to invoke STS chains.

There has been an STS Client available in ISAM since version 9.0, known as the STSClientHelper. This client uses HTTP as transport to the WS-Trust interface of the STS, this can be useful in some situations where the STS you wish to invoke is not on the same appliance as the mapping rule performing the callout. However this has some overhead, establishing a TLS connection and the overhead of the HTTP wrapper itself. In high performance environments, where the STS you wish to invoke is on the same appliance as the mapping rule, calling the STS directly over a native interface rather than over HTTP would be ideal.

New in IBM Security Access Manager in is the LocalSTSClient, a simple interface which allows calling local STS chains using a native interface, which is simpler and offers better performance in most usecases.

LocalSTSClient Usage

The LocalSTSClient exposes two methods:

doRequest(String requestType, String tokenType, Element base, Element claims)
doRequest(String requestType, String appliesTo, String issuer, Element base, Element claims)

Both return a LocalSTSClientResult object which contains one of two things, an error message, or the response token. Only one of these fields will be set, so the following pattern can be used:

var stsResult = doRequest(...);
if(stsResult.errorMessage != null) {
    // Return error...

// token is a java Element object
var token = stsResult.token;

Both the request and the response interface make use of  the Element object class. The IDMappingExtUtils class contains some methods which are useful for working with this type:

public static Document newXMLDocument()
public static String xmlElementToString(Element element)
public static Element stringToXMLElement(String string)
public static String extractBinarySecurityToken(Node node)

The on-box JavaDoc can be consulted for a complete reference for these classes.


There are several scenarios where it is strongly recommended to make use of the LocalSTSClient as an alternative to the STSClientHelper:


The following is a simple example of the LocalSTSClientHelper usage. It is intended to be invoked from an oauth-pretoken mapping rule. In this instance it is intended to be calling a JWT Validate -> STSUU Issue chain.

// Necessary imports
 // Parse a base token. In this case a BinarySecurityToken containing a JWT.
 // Line wraps for readability
 var base_token = IDMappingExtUtils.stringToXMLElement('<wss:BinarySecurityToken
 System.out.println("INITIAL TOKEN: " + base_token);
 // Validate the token using the chain with issuer and appliesTo value of 'jwt:validate', do not pass any claims.
 var res = LocalSTSClient.doRequest("", "jwt:validate","jwt:validate", base_token, null)
 if (res.errorMessage == null) {
     var result_element_string = IDMappingExtUtils.xmlElementToString(res.token);
     // Alternatively use IDMappingExtUtils.traceString(msg)
     System.out.println("RESULT: " + result_element_string);
 } else {
     System.out.println("ERROR: " + res.errorMessage);


The messages.log trace of this example is:

[7/10/18 3:10:41:890 EDT] 000012a6 SystemOut O INITIAL TOKEN: [wss:BinarySecurityToken: null]
[7/10/18 3:10:41:894 EDT] 000012a6 SystemOut O RESULT: <stsuuser:STSUniversalUser xmlns:stsuuser="urn:ibm:names:ITFIM:1.0:stsuuser">...</stsuuser:STSUniversalUser>

For existing deployments which are using the STSClientHelper after upgrading to version consider moving over to the LocalSTSClient for the performance and scalibility gains.

Click here to rate this article

Rate this article :

Software Engineer - IBM Security Access Manager

More Articles stories
By Carsten Hagemann on June 20, 2022

Getting started with the IBM Verify SDK

The IBM Verify SDK is a library available for Android and iOS and provide classes to create rich native client mobile applications that interact with IBM Security Verify and IBM Security Verify Access, so that enterprises can easily integrate flexible and intelligent multi-factor authentication into their applications. Multi-factor authentiation (MFA) verifies an indiviual’s identity by […]

Continue reading

By Martin Schmidt on July 11, 2019

Modernizing your B2C Portal Security – LDAP Proxy Deep Dive

In this part of our series we are taking a deeper look on how the LDAP reverse proxy works and what is needed to be done to make it work. Enable CI In this part we look at what needs to be done on the CI side and what information needs to be collected. We […]

Continue reading

By Martin Schmidt on May 4, 2019

Modernizing your B2C Portal Security – Desired End State

Proposition: As we have seen in part one of this series, managing customer identities for a portal can be a challenge and distraction for the business.  In this part of the series we will outline how a modernized solution for a portal security can simplify operations and free your team up to focus on the […]

Continue reading