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 9.0.5.0 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 use cases.

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.

Scenarios

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

• OAuth JWT Access Tokens
• including a request parameter in the OIDC Relying party using advanced configuration
• Consuming a JWT from the Authentication Service (InfoMap)
• Calling the LDAP Attribute Mapper from Infomap for access to a non-ISAM registry

Example

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
 importClass(Packages.java.lang.System);
 importClass(Packages.com.tivoli.am.fim.fedmgr2.trust.util.LocalSTSClient);
 importClass(Packages.com.tivoli.am.fim.trustserver.sts.utilities.IDMappingExtUtils);

 // Parse a base token. In this case a BinarySecurityToken containing a JWT.
 // Line wraps for readability
 var base_token = IDMappingExtUtils.stringToXMLElement('<wss:BinarySecurityToken
         xmlns:wss="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" 
         wss:EncodingType="http://ibm.com/2004/01/itfim/base64encode"
         wss:ValueType="urn:com:ibm:JWT">ey...W8s</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("http://schemas.xmlsoap.org/ws/2005/02/trust/Validate", "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 9.0.5.0 consider moving over to the LocalSTSClient for the performance and scalibility gains.

#ISAM