JSON Web Token

Last Updated: 30 Oct 2019

Overview

The JSON Web Token (JWT) extension is a Matrix package that lets you generate dynamic JSON Web Tokens (JWTs) from Matrix. The tokens can be used to integrate with third-party services and platforms that implement JWT authentication.

The JWTs created by the extension are signed using a secret and are encoded using the HMAC SHA256 standard.

Prerequisites

Read the following prerequisites and information before installing and using the JSON Web Token Extension.

Key package information

Supported Matrix version

5.5.0.0

Extension type

Matrix package

Installation method

.tgz archive

Asset category

Connectors

Asset name

JSON Web Token

Asset availability

Admin mode only

JWT implementation

Read this section if you need to cross-check how the JWT implementation compares to a third-party JWT implementation.

Signing

Supported: HMAC SHA256

Not supported: RSA or ECDSA

Encryption

Not supported

Payload visibility

Signed (publicly visible)

All payload information is visible in the payload when decoded. Do not put sensitive information such as passwords in the payload.

Installing the extension

This extension is installed using the Matrix package installation process.

See Matrix Packages for installation instructions.

Using the extension

The JWT asset type is available through the Matrix Admin interface.

Before you set up a JWT you need to understand the three configuration items the asset requires:

  • Secret
  • Payload
  • Expiry Time

Make sure you have the required information for each configuration item prior to setting up a JWT asset in Matrix.

Secret

The secret is shared key issued by the third-party service you are integrating with. It is used to verify that the token header and payload are authentic.

Get the JWT secret from the third-party service you are integrating with.

Check the third-party integration documentation for instructions on obtaining the correct secret.

Payload

Do not include sensitive information in the payload. The payload is signed using a shared secret but is not encrypted. Anyone can check the contents of the payload.

The payload is used to set the entity claims that are encoded within the token.

Entity claims are most commonly user credentials that the third-party service needs as part of the request.

The payload you send will vary based on the service you are integrating with, but will almost certainly use one or more JWT public claims as documented on the IANA.org website.

Payloads use a standard JSON body with claims declared as key-value pairs.

 {
  "sub": "1234567890",
  "name": "John Smith",
  "admin": true
}

In this example, sub is a registered claim, name is a public claim, and admin is a private claim specific to a third-party service.

Get the correct payload from the third-party service you are integrating with.

Expiry Time

The expiry time is used to populate the registered claim portion of the payload, specifically the exp value.

While you can leave the expiry time blank (unlimited expiry), this is not good JWT security practice.
A value between five and 15 minutes is generally recommended.

The third-party service you are integrating with may also recommend an expiry time, which you should honour in your configuration.

Creating a JWT asset

You can create a JWT asset anywhere in the asset tree. The location you select determines the web path where the token is available from.

Follow these steps to create a JWT asset for authenticating to a third-party service:

  1. In the Matrix Admin view, select the asset you want to create the JWT asset beneath.
  2. Click New Child > Connectors > JSON Web Token to create the asset, and configure the name and link type.
  3. In the Secret field, supply the third-party service’s JWT secret.
  4. In the Payload field, specify the JSON claims required by the third-party service.
  5. In the Expiry Time field, specify an expiry time for the token.

Testing the JWT asset

You can test whether the token is working correctly by testing it with a service like the jwt.io debugger.

  1. Right-click on the JWT asset and select Preview > In new window.
  2. Copy the JWT string displayed on the asset’s webpage.
  3. Visit the jwt.io debugger and decode the token.
  4. Verify the decoded token matches the configuration in Matrix.

Managing the extension

You can manage versions of this extension by upgrading or uninstalling the package.

Upgrading

This extension is upgraded using the Matrix package upgrade process.

See Matrix Packages for upgrade instructions.

Uninstalling

To uninstall this extension, you need to have both Matrix system administrator and command line access to your Matrix instance.

  1. Log in to Matrix as a system administrator and access admin mode.
  2. Move all JSON Web Token assets in your Matrix instance to the Trash.
  3. Purge any trashed JSON Web Token assets from the Trash.
  4. Follow the regular package uninstallation steps described in Matrix Packages.

Additional Resources

Send Feedback

Noticed an error?
Want to suggest an improvement?

Let Us Know

The Latest

Let Us Know What You Think

Let us know if you spot any errors or if you have any ideas on how we can improve the Matrix Community Website.

Contact Squiz for Demo

Let us show you the true power of Squiz Matrix by giving you a personalised demonstration.