This tutorial series explains how to issue and validate different types of tokens such as JWT(JSON Web Token) , SAML HoK(Holder-of key) using IBM DataPower gateway. In this article, you learn about the issuance and validation of JWT with firmware v 7.2.0.0.
In Part-2, you will learn to issue and validate the JWT with firmware v 7.2.0.1 in much simpler way. In Part-3, I’ll explain about issuance and validation of SAML HoK token used for SOAP based services.
What is JSON Web Token
JSON Web Token (JWT) is a compact claims representation format intended for space constrained environments such as HTTP Authorization headers and URI query parameters. JWTs encode claims to be transmitted as a JavaScript Object Notation (JSON) object that is used as the payload of a JSON Web Signature (JWS) structure or as the plain-text of a JSON Web Encryption (JWE) structure. JWTs are always represented using the JWS Compact Serialization or the JWE Compact Serialization.
Here is an example of signed JWT. It’s comprised of 3 parts(highlighted in different colors) separated by a period (.)
Ist part is base-64 encoded JWS header value which contains information about signing algorithm. You can use any of the following algorithm to sign the Claim-set.
Asymmetric -> RS256, RS384, RS512
Symmetric -> HS256, HS384, HS512
2nd part is base-64 encoded JSON claim-set.
3rd part is base-64 encoded signature value generated after signing the encoded JWS header and payload (claim-set) with algorithm specified in JWS header.
eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJpYm1fZGF0YXBvd2VyIiwic3ViIjoiYWRtaW4iLCJleHAiOjE0NTAxMTUyODAuMTkyLCJuYmYiOjE0NTAxMTE2NzkuMTkyLCJpYXQiOjE0NTAxMTE2ODAuMTkyLCJqdGkiOiI3ZjY2NGYxNi05OGQyLTRlYzEtODlhOS04NjM3ODBkYjFhNjgiLCJhdWQiOiJBQUFNb2JpbGUifQ.G7XRUjxrvRSdFE_RRumrPtTnLvlX36eRqDC0UFZKiO3Jau9iDbPuGPeGc0g0kUrubGQAqXz1TYTAuwcNnF58FWQjm9ovZrFH-fvGEpiYKjSctAsldj_ecQRw4jX5YKOYd1zbdr67-zUJN0n8J1iNJiJeVyGBCvz7jiiwCcZSXGRUkAqy-zwq_jULfZoi7QIS1s4f_K5WeQu4PVEhe30tovffegHdxAPZm0ptQT88l3UuuC5zNW7QxQH-6MywLvI3jYttrJ_jhIXUiNFyWDSkNKbcfUwjV2ez5IlPMfQgVFVoMMecaxJ5qlzRr8-okrpgaSQt5xx6gIL-gEZtV7Cd5g
Standard/Registered Claim names
None of the claims defined below are intended to be mandatory to use or implement in all cases, but rather, provide a starting point for a set of useful, interoperable claims. Applications using JWTs should define which specific claims they use and when they are required or optional. All the names are short because a core goal of JWTs is for the representation to be compact.
- iss (Issuer)
- sub (Subject)
- aud (Audience)
- exp (Expiration Time)
- nbf (Not before)
- iat (Issued At)
- jti (JWT ID)
Take a look at following link to get more details around these claim names. We can even define the custom claims based on the requirement.
Using Firmware 7.2.0.0
As most of you will be aware of that Data Power firmware v 7.2 provide enhanced message-level security for mobile, API, and web workloads by using JSON Web Encryption for message confidentiality, JSON Signature for message integrity and JSON Web Token to assert security assertions for Single Sign On (SSO).
Though Firmware 7.2 does provide actions to Sign, Verify, and Encrypt and Decrypt the JSON payload but there are no such actions available to generate and validate JSON Web Tokens. You have to write the Gateway Script to perform these functionalities.
Here are the sample Gateway scripts that I developed to generate and validate JWT.
Post successful Authentication/Authorization, configure the following gateway script in GatewayScript action in Request processing rule to issue the token.
createJWT.js
// Import Required packages
var jose=require(‘jose’);
var jwt=require(‘jwt’);
var sm=require(‘service-metadata’);
sm.mpgw.skipBackside=true;
session.INPUT.readAsJSON(function(error,json)
{
if(error)
{
session.output.write(‘Error reading JSON’ + error);
}
else
{
var claims={
“iss”:”ibm_datapower”,
“aud”:”Audience_name”, // Replace ‘Audience Name’ with actual value.
“iat”: new Date().getTime(),
“exp”:(new Date().getTime()) + 10000, //Token will get expire in 10 sec.
};
//Sign the token with RS256 algorithm. Replace ‘Crypto Key Object Name’ with actual object name created on box.
var jwsHeader=jose.createJWSHeader(‘Crypto Key Object Name’,’RS256′);
var encoder=new jwt.Encoder(claims);
encoder.addOperation(‘sign’,jwsHeader)
.encode(function(error,token) {
if (error) {
session.output.write(‘Error creating JWT’ + error);
}
else {
session.output.write(token);
}
}
);
}
}
)
For validation, pass the JWT in HTTP header as shown below.
Authorization : Bearer “JWT string”
validateJWT.js
//Import Required Packages
var jwt=require(‘jwt’);
var hm=require(‘header-metadata’);
var sm=require(‘service-metadata’);
sm.mpgw.skipBackside=true;
//Retrieve Authorization HTTP Header value.
var bearertoken=hm.current.get(‘Authorization’);
// Retrieve the JWT token.
var buff=bearertoken.substring(7);
var jwttoken=buff.toString();
var decoder=new jwt.Decoder(jwttoken);
decoder.addOperation(‘verify’,’Crypto Cert Object Name’)
.addOperation(‘validate’,{‘aud’:’Audience_Name’})
.decode(function(error,claims) {
if(error)
{
session.output.write(‘Error validating JWT’ + error);
}
else
{
session.output.write(claims);
}
})
