JWT

Content Type: Module
Categories: Authentication

Overview

This module can be used in Mendix apps to generate and decode JWT tokens. JSON Web Tokens are often used to perform messaging or token authentication in web services. Try it at JWT.io! Supports both HMAC and RSA based signing algorithms. Includes an RSA key pair generator for convenience! And contains a PEM to DER and DER to PEM converter, which can be used for key imports and exports. Works for API authentication with Google Service Accounts (RSA private keys). NOTE: from version 1.6.0 dependencies were updated. Please disable the "Emulate Cloud Security" option in the Mendix Modeler to prevent errors during usage of the JWT module. For more details, refer to the release notes of version 1.6.0.

Documentation

Mendix JWT module

Welcome to the Mendix JWT (JSON Web Token) module. This module can be used in Mendix apps to generate and decode JWT tokens. The app uses the com.auth0/java-jwt/3.8.0 library. JSON Web Tokens are often used to perform token authentication in web services. Try it at JWT.io!

Contributed to the community by Ciphix - Webflight has been acquired by Ciphix per 2024! JWT logo

Related resources

Table of Contents

Getting started

  1. The JWT module can be downloaded from within the Mendix Business Modeler in the Mendix Appstore into any model that is build with Mendix 7.13.1+.
  2. Apply the Java actions in the _USE_ME folder or use the Generate JWT and Decode JWT activities in the Toolbox in the Integration activities category. Check the Examples folder to see how the Java actions can be used.

Application

Once the JWT module is imported in your Mendix model, the Java actions can be used in microflows. When using RSA algorithms, use the following OpenSSL commands to verify your self-generated or existing public and private keys:

openssl rsa -in private.der -inform DER
openssl x509 -in public.der -inform DER

Supported

  • Algorithms
    • HMAC with SHA-256
    • HMAC with SHA-384
    • HMAC with SHA-512
    • RSASSA-PKCS1-v1_5 with SHA-256
    • RSASSA-PKCS1-v1_5 with SHA-384
    • RSASSA-PKCS1-v1_5 with SHA-512
  • Registered claims according to RFC 7519
    • Encoding all registered claims (including array of audiences)
    • Decoding all registered claims (including array of audiences)
    • Verify registered claims jti (JWT ID), sub (subject), aud (audience) and iss (issuer). The Decode JWT throws an exception when the token is not valid or could not be verified. Be sure to catch the exceptions in the microflow if additional logic has be executed.
    • Check for expiry dates when decoding (exp claim), which is automatically done by the underlying JWT library. Specify leeway parameter in seconds to allow for more flexibiliy in time-based validations.
  • Public claims
    • Encode and decode public claims with different types. When decoding public claims, all possible types are parsed in an object of the PublicClaimResponse entity. Type casts that are not possible by default (e.g. String to Decimal), will be left empty.
      • Boolean
      • DateTime
      • Integer
      • Long
      • Decimal
      • String
    • When using the Decode & Verify JWT Plain Text, you will have access to the plain text header and payload JSON. Consequently, you can configure your own mapping to convert the JSON to an instance of a Mendix object. This provides the possibility to decode nested JSON objects and arrays.
  • RSA Key Pair generation
    • Generate public/private key pairs in Mendix (X.509 certificate and private key binary PKCS1 format)
    • Recommended not to generate new keypairs on runtime to prevent performance issues
    • Instantiate public/private keys based on known key specifications (modulus, public and private key exponent)
    • Key pairs will be persisted in the database (necessary for binary storage). Pay attention to security
    • Convert PEM certificate format (BASE64 String) to DER format (binary). Private key PKCS1 and PKCS8 supported.

Not supported

  • Algorithms
    • ECDSA
  • Encoding public claims containing an array of values

Logging

  • The JWT Log node is available for more information.

Dependencies

The JWT module implements the auth0/java-jwt library, which has the following dependencies that are included in the module package:

  • com.fasterxml.jackson.core/jackson-databind
    • com.fasterxml.jackson.core/jackson-annotations
    • com.fasterxml.jackson.core/jackson-core
  • commons-codec/commons-codec
  • org.bouncycastle/bcpkix-jdk18on
  • org.bouncycastle/bcprov-jdk18on
  • org.bouncycastle/bcutil-jdk18on

Dependency conflicts have been reported in combination with org.apache.servicemix.bundles.commons-codec-1.3.0.

Development notes

  • Functionality is tested using the Mendix UnitTesting module. The tests are included in the JWTTest module.
  • Use Git Flow. For contributions, fork the repository and issue a pull request to the develop branch

Releases

Version: 3.3.2
Framework Version: 9.18.4
Release Notes: As described by ArjenLammers in his MR and kmarcinkowski-objectivity in his opened issue, 3 years was hardcoded as validity in the created public certificate and the variable for years validity was unused. This is now fixed, a generated public certificate is now valid for the specified amount of years.
Version: 3.3.1
Framework Version: 9.18.4
Release Notes: Updated Mendix version to Mendix 9.18 for Mendix 10 compatibility, as requested in issue #21 by Johan Flikweert Resolved vulnerabilities, as resolved in issue #20 yshoret
Version: 3.3.0
Framework Version: 8.12.5
Release Notes: Upgraded Guava due to vulnerability Updated logo Added code to sanitize base64 string as requested by user Longrisko
Version: 3.2.2
Framework Version: 8.12.5
Release Notes: Updated JARs in order to fix security threat
Version: 3.2.1
Framework Version: 8.12.5
Release Notes: Updated to Mendix 8.12.5 for Mendix 9 compatibility
Version: 3.2.0
Framework Version: 8.1.1
Release Notes: - Added possibility to decode public claims with String array values - Added action to convert JWT to plain text without verify - Added claims to verify input to JWT to plain text with verify - Updated all dependencies to latest versions - Did some work under the hood (refactoring)
Version: 3.1.0
Framework Version: 8.1.1
Release Notes: - Support for PKCS#1 private key PEM to DER conversion in addition to PKCS#8 (thanks Ian Huddart) - Support for both X509 public key certificates and raw public keys (thanks Alissa Muffels)
Version: 3.0.0
Framework Version: 8.1.1
Release Notes: - Mendix 8 compatibility - Leeway specification for token verification (allow for leeway in time-based validations when server clocks are not synchronized)
Version: 2.0.0
Framework Version: 7.13.1
Release Notes: In previous versions, an incomplete public key specification was implemented, which made it not possible to import X.509 public key certificates. This issue is solved in both key generation and key imports using signed X.509 certificates (not only the X.509 key specifications). This fix makes the module incompatible with public keys that were generated in previous version.
Version: 1.6.0
Framework Version: 7.13.1
Release Notes: - Included decode plain text action, which allows the user to work with array and nested object claim values using Mendix JSON import mappings - Updated dependencies Warning: a dependency update (Jackson Core) is using a system property internally. The Java policies applied to the Mendix free sandbox environments will not allow the system to access the properties. In addition, disable the Emulate Cloud security feature in the Modeler to prevent this behavior. Reference: https://github.com/FasterXML/jackson-core/blob/master/src/main/java/com/fasterxml/jackson/core/util/BufferRecyclers.java