Securing IBM App Connect Enterprise(ACE) Integrations with JWT Nodes
We have all heard the expression “You don’t have to reinvent the wheel" multiple times every day; there are millions of libraries available online which can be used to create a JSON Web Token(JWT). However, when we dig deeper we will understand that there is a fair bit of work that needs to be done on top of these magnificent libraries to exploit its powers and use them in a way that we need to in integrations, especially while using integration tools such as IBM Integration Bus(IIB) and IBM App Connect Enterprise(ACE). I’ve already gone through the hurdles and I don’t want you to waste time gliding in the air, again! So I am going to address a couple of JWT Nodes that would make your life smoother if you were to ever come across creating and validating JSON Web tokens.
JSON Web Token(JWT) is the most popular way to do user authorization in most modern Web applications today. Let me just spill the beans here at the beginning - Traditional session-cookie based authorization doesn’t work well with the latest Microservices or load-balancer based Web applications, simply because sessions are usually stored in the server.
Before we go into the nitty-gritty details about how JSON Web Token is used to secure Integration services, let's have a glance over the basics first.
What is JSON Web Token (JWT)?
JSON Web Token(JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.
This information can be verified and trusted because it is digitally signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA.
JWTs can also be encrypted to improve privacy.
A basic JWT token consists of multiple parts:
Figure 1: JWT token structure
Present Situation (Status Quo)
Most single-sign-on web applications use JWTs at present because they are less verbose than XML. The size of an encoded JWT is much smaller than that of Security Assertion Markup Language Tokens(SAML), and size plays a significant role while transferring data through HTTP and HTML environments.
Let’s accept the fact that regardless of this plethora of benefits JWT offers, developing and validating JWT in an integration environment can become a time consuming and complex task.
We went through the same obstacles when we first tried to secure our integration services using JWTs and hence came up with the idea of developing JWT Generate and Validate nodes to simplify these tasks.
Why JWT Generate and Validate Nodes
The inevitable curiosity of human beings is to know Why before we even learn How or What? Here is the answer to why JWT Generate and JWT Validate should be used to secure your integration services.
Depending on security capabilities within your organisation, developing a JWT creation and/or JWT validation capability may be the only option to securely integrate with your business partners' or consumers' API. The custom nodes address that requirement saving time and effort. The custom JWT Generate and JWT Validate Nodes are available for IBM Integration Bus(IIB) and IBM App Connect Enterprise(ACE).
The capabilities of the JWT nodes are as follow:
Options to generate both Signed and Encrypted JWT.
Supports HMAC (Hash-based message authentication code) and RSA public/private key pairs for Signing and Encryption.
Extended support for the following types of RSA key pairs.
a. Java Key Store(JKS) file (.jks file)
b. Public key certificates in .cer and .der formats ( binary DER encoded certificates )
c. Privacy Enhanced Mail(PEM) file (.pem file)
d. JSON Web Key(JWK) file (.json file)
e. Text files for the shared secret used in HMAC (.txt file)
Ability to retrieve private/public keys from Key store & Trust store locations.
Configurability for all basic JWT Claims through Node properties and via Environment Variables in both IIB and ACE.
Configurability for custom claims through Environment Variables in both IIB and ACE.
JWT Generate Node
JWT Generate provides the ability to generate a signed JSON Web Token. Simply install the plugin on the IIB & ACE toolkit, drag and drop the node on the canvas and configure the node properties. The private key files used for digital signatures are configured via node properties.
Figure 2: JWT Generate node
The JWT Generate node supports the basic JWT Claims listed below.
iss (issuer): Issuer of the JWT.
sub (subject): Subject of the JWT.
aud (audience): Recipient for which the JWT is intended.
exp (expiration time): Time after which the JWT expires.
iat (issued at time): Time at which the JWT was issued.
nbf (not before time): Time before which the JWT must not be accepted for processing.
jti (JWT ID): Unique identifier (allows a token to be used only once).
Figure 3: Configuring JWT Claims on JWT Generate node
These JWT Claims can be configured on the JWT Generate node while developing the application (Figure 3) or by dynamically setting the Global Environment variables of the message tree (Figure 4).
The JWT basic claims names must match as shown below, custom claims should be placed under the “CustomClaims“ branch.
Eg: JWT claims configured on the Global Environment message tree as a key-value pair using a Map node (Figure 5).
Figure 4: Configuring JWT Claims on Environment Tree
Figure 5: JWT Generate Environment Tree
Additionally, Developers can opt to generate an encrypted token. Public/Shared key used for encryption is retrieved from the file path location specified on the JWT node as shown in Figure 6.
Figure 6: Configuring Cryptography Details
For example, a JWT Token generated with HMAC SHA256 algorithm would be signed in the following way:
In a stable integration environment, an external feature/node shouldn’t upset the status quo. Hence the JWT Generate Node preserves the original message through its terminals, storing the serialised token in its local environment variables along with the JWT Claims used to generate the token. The user can optionally verify the JWT Claims by comparing the input claim values(Fig 3 or Fig 5) against the ones stored in the local environment(generated claims, Figure 7).
Figure 7: JWT Generate Node Local Environment Tree
JWT Validate Node
Figure 8: JWT Validate node
The JWT Token signature is used to protect the integrity of the message. JWT Validate Node is responsible for verifying the signature of the JWT token.
Public/Private key files used for verifying the digital signature and decrypting the token can also be specified through JWT Validate node properties.
Although JWT Tokens are usually present in the Authorization header of an HTTP message, JWT Validate node enhances the ability to validate a token present anywhere in the header by providing a node property to specify the JWT Token path in the incoming message.
Figure 9: Configuring JWT Base path
Just like the JWT Generate node, the original message is propagated through JWT Validate node terminals irrespective of the signature verification status(True/False). If the signature is verified successfully, the message is propagated through the “Out” terminal. In case of the signature verification fails, it is propagated through the “Error” terminal.
Signature verification status(True/False) is stored in the Local environment variables of the message tree.
Additionally, customers can opt to store the value of the token claims in Local environment variables by selecting a check-box in the JWT Validate node. This enables the downstream nodes to consume the metadata which is otherwise hidden in a Base64 encoded token (Figure 10).
Figure 10: JWT Validate Node Local Environment Tree
Where do we go from here
JWT Generate and Validate nodes can easily secure your integrations with JSON Web Tokens. I’ve tried to address most of the challenges that come with the process and have provided a simple solution; be it using a range of key files for signing and encryption or configuring JWT Claims.
By adhering to the notion that “Two heads are better than one”, we at Syntegrity Solutions have always kept our minds wide open and our eyes and ears peeled for our valuable customer's suggestions. Hence we appreciate your suggestions and would gladly add it to our To-Do list! So don't wait folks, let us know and share this post if you find it useful.
Currently the JWT nodes are available from Syntegrity directly. Please Get in contact to see how Syntegrity can help you.
Sreejith is an Associate Consultant with Syntegrity Solutions with a wide range of experience in Integration, DevOps and Web Services design.