MigratoryData with JWT Authorization

MigratoryData has just released official support for authorization using the JSON Web Tokens (JWT) standard as an off-the-shelf JWT Authorization add-on to the MigratoryData server. It allows you to authorize users to subscribe to and/or publish real-time messages on specific subjects. The add-on is preinstalled in the MigratoryData server starting with version 6.0.9 and its source code is freely available on GitHub.

Overview

The following diagram highlights the JWT authorization workflow with MigratoryData.

1. Your client application connects to your backend services to request a JWT token. The client application typically provides the login credentials, such as the username and password of the user who opened the client application.

2. Your backend checks the login credentials of the user and retrieves the client’s permissions, typically from a database.
   
   Then, it should generate a JWT token with the payload containing several standard and custom fields, also referred to as claims. The JWT token must include at least the standard claim exp containing the expiration time of the token, expressed in seconds as epoch time. It must also include the custom claim permissions containing the permissions of the client using the following JSON format:

"permissions": {
    "sub": [
        "/subject/sub1",
        "/subject/sub2"
    ],
    "pub": [
        "/subject/pub1",
        "/subject/pub2",
        "/subject/pub3"
    ],
    "all": [
        "/subject/pubsub1",
        "/subject/pubsub2"
    ]
}

where the subfield sub defines the subjects to which the client is authorized to subscribe, the subfield pub defines the subjects on which the client is authorized to publish, and the subfield all defines the subjects on which the client is authorized to both publish and subscribe.

Finally, before sending the JWT token to the client application, the JWT token needs to be signed either with an HMAC secret or an RSA private key. Both the symmetric signature using HMAC algorithms and the asymmetric signature using RSA algorithms are supported as further detailed in the documentation of the parameter signature.type.

3. Once the client gets the JWT token from your backend services, it attempts to connect to the MigratoryData server by providing the JWT token with the MigratoryData client API method setEntitlementToken().

4. The JWT Authorization add-on of the MigratoryData server verifies the signature of the JWT token either with an HMAC secret if the JWT token was signed using an HMAC algorithm, or with an RSA public key if the JWT token was signed using an RSA algorithm. If correct, it parses the permissions from the JWT token and store them in memory for subsequent publish and subscribe authorization requests. Finally, if both the signature verification and permission parsing are successful, then the add-on sends a notification NOTIFY_CONNECT_OK to the client, or otherwise it sends a notification NOTIFY_CONNECT_DENY.

Why using JWT authorization with MigratoryData

• The ready-made JWT Authorization add-on relieves you of having to write Java code, using the Server Extensions API, to authorize your users. At most, you might customize the existing code of the JWT authorization add-on, which is freely available .
• JWT tokens are lightweight base64-encoded strings like the generic entitlement tokens of the MigratoryData server. Therefore they are easy to use by client applications such as web, mobile or IoT applications. Simply use the client API method client.setEntitlementToken().
• JWT tokens are self-contained, which means that the JWT Authorization add-on can consume them directly to get the client’s permissions from the JWT token.
• JWT tokens are generated by your backend and signed either symmetrically or asymmetrically using a HMAC secret key or respectively, an RSA private key. They are verified by the JTW Authorization add-on using the same HMAC secret key or respectively, the RSA public key corresponding to the RSA private key which was used by your backend for signing them. Only your backend and the MigratoryData Authorization add-on know the HMAC secret key or the RSA public/private key. The client does not have access to this information.
• JWT tokens have a built-in expiry mechanism.
• JWT tokens are widely adopted by various Single Sign-On cloud services. Therefore you could externalize the generation of JWT tokens to cloud services with zero or little coding (both the JWT tokens and the JWT Authorization add-on are customizable).

Precautions

While JWT tokens are lightweight, being encoded as base64, they need to be provided to the clients securely, since anyone would be able to decode them. For example, the website jwt.io provides a debugger to decode any JWT token. Therefore it is important that the connection between your client application and your backend as well as between your client and the MigratoryData server uses TLS/SSL encrypted connections. It is also recommended to generate JWT tokens using a reasonable expiry, especially for the clients connecting from the public Internet.

Finally, it is worth noting that once generated, a JWT token cannot be tampered with. Even if the payload of a JWT token is easily decoded, any unauthorized modification of the token will break its signature so the verification of a tampered token will fail in the MigratoryData JWT Authorization add-on. Therefore only your backend could generate valid tokens by signing them using the available symmetric and asymmetric signature algorithms.

Getting started with JWT authorization in MigratoryData

To start using JWT authorization with MigratoryData, please read the JWT Authorization add-on documentation.