Setting up JWT in Helical Insight

With version 4.1 GA of Helical Insight we are also supporting JWT as well. JWT offers a lot of advantages like enhanced security, sessionless mode support when implementing load balancing server at Helical Insight, another method of SSO implementation and more.

In a stateful architecture, when the load or session is shifted to another server, it still has the session details or cookies from the previous server instance. Hence, a login page appears to login onto that particular server. In order to avoid this, implementation of stateless load balancing is preferred. This can be achieved by having a JWT application.

In this blog, we will see details of the settings to be done.

In case of Distributed server or tomcat clustering and load balancing we can use the stateless session using the JWT token where for multiple requests JWT token will be set in the cookie information instead of setting JWT with every request.

• 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.
• JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA or ECDSA.
• JWT tokens are referred as stateless because authorizing server needs to maintain no state. The token itself is all that is needed to verify a token bearer’s authorization
• Below is the sample example of how JWT works :
  1. Browser is the client and server is which generates the JWT token
  2. Browser sends the post http request to server with username and password
  3. Server creates the JWT token with secret key and sends the JWt to the browser back
  4. Browser sends back to the server including JWT as part of authorization header
  5. Server checks the JWT signature received from the browser and gets the user information from the received JWT. If signature matches then server sends the response back to the client
  6. JWT does not maintain the session instead token verification will be done

JWT Token Structure:

JWT token has 3 parts: Header, Payload and Signature. The token typically has a structure like: Header.Payload.Signature

The header typically consists of two parts: the type of the token, which is JWT, and the signing algorithm being used, such as HMAC SHA256 or RSA.

The payload consists of claims, which contains information about the user and additional data.
Signature is used to verify the sender of the JWT is who it says it is and to ensure that the message wasn’t changed along the way.

All the three parts of the token are encoded using Base64 algorithm and then a token is formed by separating them with dots.

Steps to be followed:

1. Start the JWT application where Helical Insight will be embedded. We have also provided a dummy JWT application using simple HTML and JS , you may download the application that we have created as a reference from here. The application should be on a separate instance than Helical Insight. Extract the JWT.zip to /webapps/ folder.
2. Go to context.xml file located at “../hi/apache-tomcat-9/conf/” on both the servers (JWT and Helical Insight).
   Add below cookie class just below
   < CookieProcessor className=”org.apache.tomcat.util.http.LegacyCookieProcessor”/>
3. Enable https in apache tomcat for both the servers. Add below tag after line number -79
   < Connector port=”8443″ protocol=”HTTP/1.1″ SSLEnabled=”true” maxThreads=”150″ scheme=”https” secure=”true” keystoreFile=”/home/helical/selfsigned.jks” keystorePass=”helical” clientAuth=”false” sslProtocol=”TLS” sslVerifyClient=”optional” sslEnabledProtocols=”TLSv1.2,TLSv1.1,SSLv2Hello”/>
   Note : In case if you do not have HTTPS on helical insight server you can create self signed certificate. To create the keystoreFile using the below command
   keytool -genkey -keyalg RSA -noprompt -alias tomcat -dname “CN=localhost, OU=NA, O=NA, L=NA,
   S=NA, C=NA” -keystore selfsigned.jks -validity 9999 -storepass helical -keypass helical
4. Go to web.xml located at “../hi/apache-tomcat-9/webapps/hi-ee/WEB-INF/” and enable the JWT, cross-origin and cookies filters
   Enable JWT by filter by uncommenting lines 28 to 30.
   Enable cross-origin filter by uncommenting lines 37 to 61.
   Enable cookies filter by uncommenting lines 170 to 180.
   Save the file and restart the server.
5. If you are using the local JWT application by downloading the file given in this blog, you can access JWT application using URL: https://localhost:8443/jwt
   The project.properties file present at location “../hi/apache-tomcat-9/webapps/hi-ee/WEB-INF/classes” in Helical Insight contains the properties that can be used to configure JWT settings.
6. access_token_validity_seconds: This is the validity period for the token after which a new token needs to be generated. This is in seconds.
   • signing_key: This is the key that is used in the signature part of the token
   • token_prefix: This prefix is added to the token
   • header_string: This string becomes part of the token header
   • param_string: This is the parameter string for mapping the token
   • authorities_key:
   • signing_algorithm: This is the algorithm being used for JWT token. There are a number of algorithms that are supported by JWT.
   • issuer: This is the name that will be published as the issuer of this token
   • jwt_type: This is a static string with value JWT
   • jwt_cookie: From versions after Helical Insight 4.1GA, you can set this flag to false to disable cookies
   • altogether. With this you can decide whether tomcat level cookies are to be created or not.

Note that right now JWT method is only useful for viewing the created report/dashboard/canned report and not for other modules and functions.

In order to connect using API, the username, organisation name and password must be passed in the below format:

1. When using SSO
   SSO
   {“username”: “hiadmin”,”password”: “hiadmin”,”authenticateUser”: “SSOUser”}
   Token generated
   eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIZWxpY2FsSW5zaWdodCIsInN1YiI6IlNTT1VzZXI6SGVsaWNhbEluc2lnaHQiLCJzY29wZXMiOiJST0xFX1VTRVIiLCJpYXQiOjE2MTAwODk2NzAsImV4cCI6MTYyODA4OTY3MH0.maZeyFC-rN27ecTek-xtrMXe76BGv0JFpwZ8PGdKhV8
   {“username”: “hiadmin”,”password”: “hiadmin”,”authenticateUser”: “SSOUser:HelicalInsight”}
   Token generated
   eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIZWxpY2FsSW5zaWdodCIsInN1YiI6IlNTT1VzZXI6SGVsaWNhbEluc2lnaHQiLCJzY29wZXMiOiJST0xFX1VTRVIiLCJpYXQiOjE2MTAwODk2NzAsImV4cCI6MTYyODA4OTY3MH0.maZeyFC-rN27ecTek-xtrMXe76BGv0JFpwZ8PGdKhV8
2. When using CAS
   {“username”: “hiadmin”,”password”: “hiadmin”,”authenticateUser”: “somen”}
   {“username”: “hiadmin”,”password”: “hiadmin”,”authenticateUser”: “somen:ExternalOrganization”}
3. Normal Authentication
   {“username”: “hiadmin”,”password”: “hiadmin”}
   {“username”: “hiadmin:HelicalInsight”,”password”: “hiadmin”}

If there is a need to pass username only then its simply “hiadmin”, if there is a need to pass username and organization then pass “hiadmin:HelicalInsight” in the above examples wherein username is hiadmin and organization name is HelicalIsnight.

The POST request must append /rest/authToken to the base URL of Helical Insight to generate a token. An example of the request, the user details and the token generated is shown in the below image.

The generated token can be appended to the report URL as shown below:

http://localhost:8085/hi-ee/hi.html?dir=1463377807724/1463377978248/Sample%20EFW%20Report&file=sample_report.efw&authToken=Bearer%20eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIZWxpY2FsSW5zaWdodCIsInN1YiI6ImhpYWRtaW4iLCJzY29wZXMiOiJST0xFX0FETUlOLFJPTEVfVVNFUixST0xFX1ZJRVdFUiIsImlhdCI6MTYyMzMyODI5NSwiZXhwIjoxNjQxMzI4Mjk1fQ.AtBLcoiig59VW8MB13CyoOf5YDBs8zrMnNNv2QgOORI

Understanding index.html file of sample JWT application provided:

In the index.html file, we have created a page where we have 3 buttons – Report List, Login and Logout. Unless the login button is clicked, the report list will not be populated as the user is not logged in using the JWT token. Once the logout button is clicked, all the token properties are reset.

In the index.html file, the requestBaseUrl is the URL of the Helical Insight application on HTTPS. In settings variable inside the url key, we are adding the authToken to the base URL of the application. Hence, the URL will be appended with the JWT authToken.

You need to change the requestBaseURL as per your Helical Insight application URL.

In the “data” object, we need to pass the details of the user who is logging in.

The format for this would be:

{\”username\”:\”hiadmin\”, \”password\”:\”hiadmin\”, \”authenticateUser\”:\”username:orgName\”}

Since we are using hiadmin and impersonating the behaviour of the loggedin user, first we are providing the admin username and password and then after authenticateUser keyword, we are passing the username and organization name. If the organization name is null, only username needs to be passed. This holds true for all SSO mechanisms like CAS, LDAP, Active Directory etc. that Helical Insight supports.

In the callAjax function, we are adding the request header string (defined in project.properties as Authorization) to the token.

Once these settings are done, you can click on the login button to login and then click on reports list button to see the list of reports.

Similarly, you can use other report URL’s or APIs to view the report or dashboard that you require. For this, you can replace the URLs in the show() function.

NOTE: SAML, oAuth, oAuth 2.0 etc are all types of JSON web token which we have covered here. Every customer can have their own additional fields or changes in the way they are using the JSON webtoken. Then steps and methods which we have elaborated here can be used as a base to further develop and enahance and meet a client’s requirements.

For any help or queries, please write to us on support@helicalinsight.com