DCM (DataPower Configuration Manager) is an open source tool published by IBM for automating and simplifying the configuration and management of IBM DataPower appliances (with the exception of the XC10).  It can be used standalone OR within IBM UrbanCode Deploy platform.  Business partners, clients or anyone else for that matter can contribute enhancement or fixes to the tool.

DCM uses DataPower’s XML Management Interface (XMI) to interact and manipulate appliance’s management tasks in automated fashion. DCM uses ANT scripting to fully automate the build, deployment and release process of DataPower configuration and management.

One does need to be familiar with ANT to effectively use DCM. A simple ANT build file, deploy.ant.xml, included with the DCM distribution serves several simple purposes:

• Common deployment tasks at domain level and some at device level.
• DCM provided ANT based task and targets for custom deployment builds.

Some of the common deployment tasks provided in deploy.ant.xml include create, delete, backup (export), restore (import), reset, restart, quiesce, unquiesce, and save domains. Additional task are delete/restore/save checkpoints, Upload files or directories, valcred creation, create/delete/modify objects, and create/remove host aliases.

Deploy.ant.xml build file relies on certain ANT properties such as host, domain, uid, pwd, port, and some of the file location for backup, import, export, and upload files in addition to upload-to and upload-from directory locations. One very important property is the dcm.dir that points to the directory where DCM is installed. These properties could be provided in a <filename>.properties file and included within the custom build script or provided within an ANT call, such as following:

Ant –f deploy.ant.xml –propertyfile <filename>.properties check-access

Where check-access is a target defined within ANT script to checks access to DataPower device using the provided host, user id, and password.

Once installed and properly functioning, Using DCM effectively requires a little planning such as how to structure property files and the DCM definition files to best fit your needs. Thus little exploration of DCM directory and included files would be beneficial.

Step by step instructions and files :

Download the DCM zip file here.

Prerequisites:

1)    JDK 1.6 or later

2)    Apache Ant 1.8.1 or later (DCM is packaged with 1.9.4 and UCD plugin)

3)    Xalan-J for Oracle/SUN JDK version (comes included with IBM JDK)

I have downloaded xalan-j 2.7.1-src-2jars for stability.

Installation:

1. Ensure JDK is installed and is included in the PATH
2. Ensure Ant 1.8.1 is installed and is included in the PATH
3. Include following five Xalan JAR files in the CLASSPATH
   1. xalan.jar
   2. serializer.jar
   3. xml-apis.jar
   4. xercesImpl.jar
   5. xsltc.jar
4. Ensure DataPower device’s XML Management Interface (XMI) is enabled
5. Test if DCM is properly working using the following command

ant -f deploy.ant.xml -Ddcm.dir=<path of dcm directory> -Dhost=<IP/hostname of the DP device> -Duid=<user ID> -Dpwd=<user Password> check-access

*use -Dport=<port #> if XML Management Interface is enabled on a port other than the default (5550)

*if -Dpwd=<user Password> is omitted in the above command then user will be prompted for password

Further test with other tasks:

Create or delete a domain by introducing the following in the above command instead of check-access

-Ddomain=<domain name> domain-create save

-Ddomain=<domain name> domain-delete save

Create a <fileName>.properties file that contains these ANT variables.

# DP credentials 

dcm.dir=<path of dcm directory>

host=<IP/hostName of the DP device>

uid=<user ID>

pwd=<user Password> (this could be omitted for security reason. Omitting it will prompt the user for password)

Use the following command to create a domain and save the configurations.

ant -f deploy.ant.xml -propertyfile <fileName>.properties domain-create save

While domain-create is a target within deploy.ant.xml, it utilizes the task of createDomain to serve the purpose.

DCM provides a number of tasks that can be utilized in customized build files. These tasks are defined in dcm\dcm-distros\dcm_1.0.1\src\dcm-taskdefs.ant file

DCM – Part II: We will delve further into DCM, some examples, and shell/batch scripting.

In the IBM DataPower world, JSON is the representational format used by the RESTful façade exposed by the appliance. Starting with firmware version 3.8, there has been a gradual increase in the number of ways that JSON payload is handled.

DataPower services that will handle and process JSON messages include:

• Multi-Protocol Gateway (MPGW)
• XML Firewall
• Web Token Services (Firmware v7.0 & up)

These services offer additional options to a developer on what type of request or response to expect. Selection of type of payload results in sort of treatment the payload is to receive. Our main concern in this article is JSON payload and its processing and manipulation. So, let’s dive in:

Non-XML as the request/response type

The original JSON message is available as the INPUT context.

JSON as the Request / Response Type

1. Incoming JSON payload is validated as a well-formed JSON document.
   • Simultaneously JSON parser enforces limits on the incoming JSON document

2. Message is converted to JSONx (an IBM standard to represent JSON as XML)._­
   • Simultaneously XML parser enforces limits on JSONx document as it is being created.

3. The JSON message is now available in two context forms:

• INPUT context (original message) 

• _JSONASJSONX context (the converted JSONx message that can be manipulated with XSLT, just as any other XML)

Before firmware version 6.0, DataPower offered the following process of dealing with JSON payloads thru converted JSONx:

 Source: for further examples visit here.

JSONx data, _JSONASJSONX context, now can be validated using jsonx.xsd schema file in the store:// directory.

Using an explicit Transform action with a custom XSLT style sheet, JSONx message will now need to be transformed to desired data format that is expected by the back end.

Response from the backend will need to be converted to JSONx using a customer XSLT in a transform action, if client expects a JSON response.

The appliance provides jsonx2json.xsl style sheet in the store:// directory that can be used to convert JSONx to JSON by applying an explicit transformation action to the desired context.

Starting with firmware v6.0 & later, in addition to the above capability, now available INPUT context, the original JSON payload could be processed in 3 different ways:

     1.   Validate JSON schema

         Source: JSON schema validation explained here.

     2.   Manipulated with a transform action that uses a processing control file such as:

XQuery transformation with JSONiq to:

• Text
• XML
• another JSON
• etc.

  Source: see JSON transformation to different data types here.

     3.   Manipulated using a GatewayScript (firmware v7.0 & up)

Source: More about GatewayScript here.

Considering Parser limitations for JSON payloads

JSON parser settings and XML parser settings work together to provide configurable settings for message size, nesting depth, and other limits.

• JSON parser settings apply to the JSON message
• XML parser settings apply to XML and converted JSONx messages

The parser limits helps protect against a denial-of-service (DoS) attack when a single maliciously huge message is sent to the service to keep it busy.

Default limits are applied unless Setting Configurations are specified. The maximum message size limit applies to JSON, SOAP, XML, and non-XML message types.

• Limits are not enforced for pass-through message type.

More restrictive limits of both the JSON and XML parser are enforced. Exceeding either parser limit results in an HTTP 500 response code being returned to the client.

Source: See the parser limits Here: JSON 

Implementing Scatter/Gather – Data Aggregation pattern (Fan-out/Fan-in) in Datapower

This article covers one of the very important patterns in SOA – Data aggregation. The data aggregation can be implemented in Datapower in many different ways.

Data aggregation in Datapower can be categorized mainly in three segments:

• Scatter n Gather Pattern
• Fan-out/Fan-in Pattern
• Data/Content Aggregation

Fundamental principle of all 3 patterns remains the same i.e. securing and displaying aggregated information from a single or multiple sources on web interface.

In Scatter and Gather pattern, a single request in the flow can be fanned out (scattered) to multiple backend services or to the same service with different resource URIs or multiple SOAP operations and the results from backend service(s) can be aggregated (gather) into a single response to service consumers.

The perfect example for such pattern could be taken into account of securing insurance or stock quotes, inventory status or booking appointments (doctors’, restaurants’ etc.) or providing 360 degree view of a customer by aggregating data from multiple systems or vendors. This pattern can also be used sometimes when backend exposes single operation for an interaction point e.g. a legacy system might provide available appointments per service provider and you may have to build the service which needs to show appointment for 10-20 service providers. In my experience, we have observed latency and performance issues in building such services. However, after enabling asynchronously option in Results and using event sink action, the latency of Datapower service decreased significantly. Therefore, it is imperative that backend services should be invoked asynchronously from Datapower to results action to achieve better performance in terms of response time.

As depicted in the aforementioned graphic, after receiving response from a backend service provider A, a call was generated for two other backend service providers (B & C) to get data from the response of service provider A. XSLT (transform action) can be used to parse the response from service provider A and build request URLs based on the response from the service A. Aforementioned diagram is specifically used to highlight that have specifically used term in the diagram above to emphasis that the multiple requests can go to the same service provider or multiple service providers. There is a significant performance improvement by using Results Action with asynchronous option than without asynchronous option as the number of URLs for the Backend service providers (B & C) increases because of parallel invocation. One will need to add Event Sink Action after Conditional Action or Results Action or both based upon the requirements and design of the service.  The results from service A, B and C etc. can be aggregated using an XSLT action in the processing rule flow.

To demonstrate process flow better in this blog, results action is used, however a XSLT transform action can be used to call multiple backend services (Fan- out) and aggregate (Fan-in) the data in the same action.

Systems Used:

DataPower – XML Gateway Appliance to Authenticate and Validate the requests.
MQ – Queuing Mechanism used for Guaranteed Delivery.
Cast Iron – To develop integration’s using the In-built connectors available for Salesforce and SAP.

1.   Salesforce places transaction on Outbound Message Queue.  This transaction contains only the following:

• The ID of the record

• The Integration Operation (e.g. “Insert”)

• The Integration Status (always “Submit”)

       The Outbound Message queue performs retries at a specified time interval until the message is delivered.

2.  Salesforce Outbound Message Queue invokes service on the External DataPower XML gateway.

•     External DataPower gateway verifies the Salesforce generic SSL certificate and passes service request to the       Internal DataPower XML gateway

3.  Internal DataPower XML gateway places the transaction on MQ processing queue for that
transaction. The processing queue is identified by a generic web service proxy which will use the unique Object            name and Integration Operation field value combination from the incoming SFDC Outbound Message Request.

•     Each transaction type has its own Processing and Error queues in MQ.
•     All queues are First In – First Out (FIFO)

4.  Internal DataPower acknowledges request to Salesforce. Salesforce clears request from the Outbound Message            Queue.

5.  Cast Iron polls messages from MQ processing queue.

6.  Cast Iron initiates new synchronous call back to Salesforce with Transaction Record ID specified in Outbound               Message request.  This service call obtains the transaction payload from Salesforce to be provided to the back end       system.  This call back can be either SOAP for standard Salesforce services or REST for custom Salesforce                     Services.

7.  Cast Iron initiates a new synchronous transaction to DataPower Internal Web Service Proxy which will                          authenticate and validate the transaction request and routes it to the corresponding SAP Service.

8.  SAP executes the transaction and returns status and any return data.

9.  Cast Iron initiates new synchronous transaction to Salesforce to provide updated status message and any return           data and any application error message.

10.  Salesforce posts any data from the return message.

•   Salesforce provides the return acknowledgement to Cast Iron.
•   Cast Iron closes the session with Salesforce and closes the transaction.

When an error happens at anytime during the transaction, the Salesforce Outbound message is placed onto the corresponding error queue. Once the error is fixed, the message is transferred from the error queue to the processing queue. Cast Iron picks up the message again and completes the transaction successfully.

I have seen at most of the places that while configuring the objects on Data Power, we just configure the standard properties and leave others as is with default values without knowing their significance.

But sometimes this ignorance might lead us to face some critical issues that might be very hard to troubleshoot. I suggest trying to understand each property behavior and configure the values accordingly based on the use-case.

Here is the use-case I wanted to cover:

Problem

Most of you have encountered following issue while establishing SSL session with Back-end servers using Data Power.

3:43:38 PM ssl error 23577521   0x8120001a sslproxy (): Server negotiated an unknown SSL protocol version

• Upgrade the legacy SSL servers to use highest security protocol version available. E.q. TLS v1.2
• If Option # 1 is not possible then you will need to just ENABLE only the SSL/TLS version that server supports and disable rest in Crypto profile object.

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.

Claims Description

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);

}

})

In my previous article, I covered JSON Web Token and how to issue and validate it on data power firmware v 7.2.0.0 using custom gateway scripts. In this article, I will cover the issuance and validation of JWT with AAA action on data power firmware v 7.2.0.1.

No need to write the code. Leverage the built-in feature of AAA action to issue and validate JWT.

Here is the step-by-step guide to generate the JWT: 

Step – 1: Configure the AAA action on Request rule in processing policy.

Step – 2: Select the Identification method. Mostly in case of REST services, Identification method is HTTP Authentication Header as shown in below screenshot.

Step – 3: Authenticate the user with LDAP or locally with AAAInfo.xml file.

Step – 4: Extract the resource and authorize the user. Again, either you can make a call to LDAP, retrieve the groups associated with user and authorize or locally with AAAInfo.xml file.

Step – 5: Post successful Authentication and Authorization, its turn now to generate the JSON Web Token.

• Turn ON the Generate a JSON Web Token Property in Post processing step of AAA action as shown below.

• Create and configure a new JWT Generator.

• Configure Issuer Name, Validity period as per your requirement.
• Select JWT generation method. Mostly, it’s sign.
• Once you select Sign, configure the Signature algorithm and Key.
• Configure additional claims such as iat (Issued at), nbf (Not before), aud (Audience), jti (JWT ID) in Advanced tab of JWT Generator.

Step -6: Commit and apply AAA policy changes.

Here is the step by step guide to validate the JWT.

Step – 1: Configure the AAA action on Request rule in processing policy.

Step – 2: Select the Identification method as JWT as shown below.

Step -3: Create a new JWT Validator object.

Step – 4:  Configure the JWT Validator object.

• Configure the exactly same values for Issuer and Audience fields which were used to generate the token. If there is any mis-match then validation will fail.
• Configure the Verify method. Mostly, it would be PKIX. Once you select that, configure the cert also to verify the signature.

Step – 5: In User Authentication step, select the option shown in below screenshot.

Step -6 : Commit and apply AAA policy changes.

This issue mainly occurs when DataPower MQ client tries to establish a SSL(2-way) connection with MQ server.

Here is the solution to fix this issue.

Step – 1 :  Ensure that correct certs have been configured in keystore of MQ queue manager object on MQ server.

Step – 2 :  Ensure that correct certs have been configured in CryptoIdentificationCredentials and CryptoValidationCredentials objects on DataPower.

Step – 3 : Get the Cipher details configured at Channel level and compare it with Cipher field in SSLProxyProfile object configured in MQ queue manager object on DataPower. In most of the cases, its value is DES-CBC3-SHA.

Step – 4 : Refresh the SSL Settings at Queue Manager level on MQ server and restart the channel.

This post focuses on upgrading the Crypto profile objects configuration (keep TLS and disable rest) on DataPower. If you face any issues in establishing the TLS connectivity from Soap UI, follow these steps to fix the issue:

Step – 1:  Navigate to C:\Program Files\SmartBear\SoapUI-5.2.1\bin folder.

Step – 2 : Edit SoapUI-5.2.1.vmoptions file with any text editor.

Step – 3 : Add following entry and save the file. It will only enable TLS 1.2 protocol.

 -Dsoapui.https.protocols=TLSv1.2

If you have a requirement to enable other TLS version too, then use comma separated values as shown below.

 -Dsoapui.https.protocols=TLSv1.0,TLSv1.1,TLSv1.2

Step – 4 : Close and Re-launch the Soap UI.

XSLT is not the ONLY transformation language supported by DataPower. Starting with the firmware version 7.0.0.0, DataPower supports a new transformation technology – Gateway Script, to handle all sorts (API, B2B, Web, Mobile, SOA) of traffic effectively. For more information, please review the documentation.

IBM provides an interactive website that lets you write Gateway Script code and execute on a cloud hosted DataPower Gateway for learning purposes. The website provides many examples that you can test as it is or edit based on your requirements. It also provides separate tabs to modify the sample code, provide request, view Response and logs.

I tested the following use-case in just a few seconds. There was no need to configure services, or policies to test the transformation piece through Gateway Script.

Use-case : Modify incoming JSON request payload (Add new object in Books array)

Step – 1 : Clicked on 1st sample in Code tab, tweaked the request as shown below.

Step-2 : Provided the request in Request tab as shown below. Didn’t modify anything in HTTP headers field.

Step – 3 : View the response using Response tab.

Step – 4 : View the datapower system logs using Logs tab.

Exposing patient health information as Application Program Interfaces (APIs) is one of the most critical components in Stage 3 of the EHR Incentive Programs and all providers will be required to comply with MU3 requirements by 2018. The APIs will ensure improved patient engagement by providing data access in application of patient’s choice instead of current patient portal channel only.

In compliance with HIPAA privacy and security rules, the implementation of APIs that expose sensitive PII/PHI data must be properly protected in terms of Authentication, Authorization, Audit, Message and Transport Level Security, Encryption etc.

Some of the key requirements for the API interface are:

1. Uniquely identify a patient and return an ID or other token that can be used by an application to subsequently execute requests for that patient’s data.
2. Allow a request for “all” the patient data, or specific “by specific data category” i.e. demographics, labs, procedure, medications etc.
3. Must include accompanying documentation that contains API syntax, function names, mandatory and optional parameters, methods and their returns, and terms of use.
4. Documentation must be available via publicly accessible hyperlink
5. Authentication, Access Control, Authorization , Auditable Events and Tamper-Resistance — Trusted connection — Auditing actions on health information

Solution using IBM APIC:

1. APIC security policies jwt-validate or validate-usernametoken can uniquely identify a patient and use of JWT/OAuth token management system through DataPower can return token to requesting client for subsequent requests.  
2. APIC is an integrated creation, runtime, management and security foundation for enterprise grade API’s, and Microservices to power modern digital applications. Fine-grained services based on data category demographics, lab results etc. can be quickly built with standards-based visual API spec creation in Swagger 2.0.
3. APIC provides customizable, self-service developer portal for publishing APIs. Through the portal, application developers can access APIs directly and can take sample code snippet from the portal to implement APIs in their applications.
4. APIC self-service developer portal can be accessed publicly for API subscription and documentation.
5. IBM APIC provides access control over API’s, API Plans and API Products. API runtime environment – API gateway (Micro gateway or Datapower) acts as Policy Enforcement Point, and maintains security and control to APIs. Datapower’s AAA policy can support variety of Authentication/Authorization formats JWT, LTPA, SAML,WS-Security, OAuth etc. Datapower should also be used to provide message level security by encrypt/sign and transport through the use of SSL/TLS.

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.

Claims Description

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);

}

})

In my previous article, I covered JSON Web Token and how to issue and validate it on data power firmware v 7.2.0.0 using custom gateway scripts. In this article, I will cover the issuance and validation of JWT with AAA action on data power firmware v 7.2.0.1.

No need to write the code. Leverage the built-in feature of AAA action to issue and validate JWT.

Here is the step-by-step guide to generate the JWT: 

Step – 1: Configure the AAA action on Request rule in processing policy.

Step – 2: Select the Identification method. Mostly in case of REST services, Identification method is HTTP Authentication Header as shown in below screenshot.

Step – 3: Authenticate the user with LDAP or locally with AAAInfo.xml file.

Step – 4: Extract the resource and authorize the user. Again, either you can make a call to LDAP, retrieve the groups associated with user and authorize or locally with AAAInfo.xml file.

Step – 5: Post successful Authentication and Authorization, its turn now to generate the JSON Web Token.

• Turn ON the Generate a JSON Web Token Property in Post processing step of AAA action as shown below.

• Create and configure a new JWT Generator.

• Configure Issuer Name, Validity period as per your requirement.
• Select JWT generation method. Mostly, it’s sign.
• Once you select Sign, configure the Signature algorithm and Key.
• Configure additional claims such as iat (Issued at), nbf (Not before), aud (Audience), jti (JWT ID) in Advanced tab of JWT Generator.

Step -6: Commit and apply AAA policy changes.

Here is the step by step guide to validate the JWT.

Step – 1: Configure the AAA action on Request rule in processing policy.

Step – 2: Select the Identification method as JWT as shown below.

Step -3: Create a new JWT Validator object.

Step – 4:  Configure the JWT Validator object.

• Configure the exactly same values for Issuer and Audience fields which were used to generate the token. If there is any mis-match then validation will fail.
• Configure the Verify method. Mostly, it would be PKIX. Once you select that, configure the cert also to verify the signature.

Step – 5: In User Authentication step, select the option shown in below screenshot.

Step -6 : Commit and apply AAA policy changes.

This issue mainly occurs when DataPower MQ client tries to establish a SSL(2-way) connection with MQ server.

Here is the solution to fix this issue.

Step – 1 :  Ensure that correct certs have been configured in keystore of MQ queue manager object on MQ server.

Step – 2 :  Ensure that correct certs have been configured in CryptoIdentificationCredentials and CryptoValidationCredentials objects on DataPower.

Step – 3 : Get the Cipher details configured at Channel level and compare it with Cipher field in SSLProxyProfile object configured in MQ queue manager object on DataPower. In most of the cases, its value is DES-CBC3-SHA.

Step – 4 : Refresh the SSL Settings at Queue Manager level on MQ server and restart the channel.

This post focuses on upgrading the Crypto profile objects configuration (keep TLS and disable rest) on DataPower. If you face any issues in establishing the TLS connectivity from Soap UI, follow these steps to fix the issue:

Step – 1:  Navigate to C:\Program Files\SmartBear\SoapUI-5.2.1\bin folder.

Step – 2 : Edit SoapUI-5.2.1.vmoptions file with any text editor.

Step – 3 : Add following entry and save the file. It will only enable TLS 1.2 protocol.

 -Dsoapui.https.protocols=TLSv1.2

If you have a requirement to enable other TLS version too, then use comma separated values as shown below.

 -Dsoapui.https.protocols=TLSv1,TLSv1.1,TLSv1.2

Step – 4 : Close and Re-launch the Soap UI.

One of the nation’s largest marketer of tires for auto replacements, required a secure, scalable and flexible user friendly point-of-sale application.

Perficient partnered with them to implement a new system for sales associates, which provides a faster way to access enterprise data and ultimately provide better customer service.

In order to accommodate increasing workloads, the SOA-based solution was built using WebSphere Message Broker, MQ, eXtreme Scale and DataPower. After the implementation, our client saw a 15% increase in retail sales due to an enhanced customer experience. The development of a smarter supply network also improves interactions with supplier and manufacturers.

Learn more about SOA and WebSphere.

XSLT is not the ONLY transformation language supported by DataPower. Starting with the firmware version 7.0.0.0, DataPower supports a new transformation technology – Gateway Script, to handle all sorts (API, B2B, Web, Mobile, SOA) of traffic effectively. For more information, please review the documentation.

IBM provides an interactive website that lets you write Gateway Script code and execute on a cloud hosted DataPower Gateway for learning purposes. The website provides many examples that you can test as it is or edit based on your requirements. It also provides separate tabs to modify the sample code, provide request, view Response and logs.

I tested the following use-case in just a few seconds. There was no need to configure services, or policies to test the transformation piece through Gateway Script.

Use-case : Modify incoming JSON request payload (Add new object in Books array)

Step – 1 : Clicked on 1st sample in Code tab, tweaked the request as shown below.

Step-2 : Provided the request in Request tab as shown below. Didn’t modify anything in HTTP headers field.

Step – 3 : View the response using Response tab.

Step – 4 : View the datapower system logs using Logs tab.

Exposing patient health information as Application Program Interfaces (APIs) is one of the most critical components in Stage 3 of the EHR Incentive Programs and all providers will be required to comply with MU3 requirements by 2018. The APIs will ensure improved patient engagement by providing data access in application of patient’s choice instead of current patient portal channel only.

In compliance with HIPAA privacy and security rules, the implementation of APIs that expose sensitive PII/PHI data must be properly protected in terms of Authentication, Authorization, Audit, Message and Transport Level Security, Encryption etc.

Some of the key requirements for the API interface are:

1. Uniquely identify a patient and return an ID or other token that can be used by an application to subsequently execute requests for that patient’s data.
2. Allow a request for “all” the patient data, or specific “by specific data category” i.e. demographics, labs, procedure, medications etc.
3. Must include accompanying documentation that contains API syntax, function names, mandatory and optional parameters, methods and their returns, and terms of use.
4. Documentation must be available via publicly accessible hyperlink
5. Authentication, Access Control, Authorization , Auditable Events and Tamper-Resistance — Trusted connection — Auditing actions on health information

Solution using IBM APIC:

1. APIC security policies jwt-validate or validate-usernametoken can uniquely identify a patient and use of JWT/OAuth token management system through DataPower can return token to requesting client for subsequent requests.  
2. APIC is an integrated creation, runtime, management and security foundation for enterprise grade API’s, and Microservices to power modern digital applications. Fine-grained services based on data category demographics, lab results etc. can be quickly built with standards-based visual API spec creation in Swagger 2.0.
3. APIC provides customizable, self-service developer portal for publishing APIs. Through the portal, application developers can access APIs directly and can take sample code snippet from the portal to implement APIs in their applications.
4. APIC self-service developer portal can be accessed publicly for API subscription and documentation.
5. IBM APIC provides access control over API’s, API Plans and API Products. API runtime environment – API gateway (Micro gateway or Datapower) acts as Policy Enforcement Point, and maintains security and control to APIs. Datapower’s AAA policy can support variety of Authentication/Authorization formats JWT, LTPA, SAML,WS-Security, OAuth etc. Datapower should also be used to provide message level security by encrypt/sign and transport through the use of SSL/TLS.

IBM DataPower Gateway is a purpose-built security and integration platform for mobile, cloud, API, SOA and B2B workloads. The current business model for nearly all industries relies mostly on data. The database has become a very important component of an enterprise’s IT structure providing more sophisticated and flexible options than the databases available a decade before. This digital transformation has placed demands on Enterprise Service Bus (ESB) products to connect with databases at higher speeds with the options of supporting multiple types of databases.

According to a report generated in September 2016, Oracle, My SQL, Microsoft SQL server and DB2 are the most popular Relational DBMS used all over the world. Considering the wide use of these databases, IBM Datapower gateway ( Firmware edition V7.5) is designed to connect to most of the popular databases and they are listed below:

• Oracle
• Sybase
• DB2
• Microsoft SQL Server
• IMS

The configuration of a data source to connect to a database through IBM Datapower gateway is achieved through a component called SQL data source. This article will provide the steps to configure a SQL data source in Datapower gateway. The database used for this illustration is Microsoft SQL server 2014 and the IBM Datapower Gateway firmware version is 7.5.

Step 1:

Obtain the following details about the database from the concern team.

• Database Type
• IP address / Hostname of the server in which the database is configured
• Port number in which the database is configured
• Username
• Password
• Database name

Step 2:

In this example the database used is Microsoft SQL server and the sample values for the above mentioned parameters will be as follows:

• Database Type – Microsoft SQL server
• IP address – 10.123.45.678
• Port number – 57498
• Username – datapoweruser
• Password – Ibm@12345
• Database name – testdb

Note: The user type used for authentication should be SQL server authentication. Please don’t use a user account with Window’s authentication.

Step 3:

Login to the Datapower gateway physical or virtual appliance and navigate to the Password map alias component under Objects > Configuration Management setting. Create a password alias configuration with the password of the user account which will be used in the SQL data source object.

Once configured, click Apply and save the configuration.

Step 4:

Navigate to the SQL data source object available under network > Other setting to create a new SQL data source object.

Step 5:

Create a new SQL data source and configure the details with the details gathered about the database.

Once configured, click Apply  and save the configuration.

Step 6:

Enable debug level logging to verify if the configuration is correct. In case any of the detail is incorrect or a network connection is blocked, the SQL data source object will be in a pending status.

Reference:

http://www-03.ibm.com/software/products/en/datapower-gateway

http://db-engines.com/en/ranking