atlassian-jwt

atlassian-jwt

JWT (JSON Web Token) encoding & decoding library for node.js. Built on jwt-simple and adds support for Atlassian's custom QSH (query string hash) claim.

For more information on using JWT tokens with Atlassian add-ons, please read: Understanding JWT.

Install

$ npm install atlassian-jwt

Usage

Create a JWT token

import * as jwt from 'atlassian-jwt';
import moment from 'moment';

const now = moment().utc();

// Simple form of [request](https://npmjs.com/package/request) object
const req: jwt.Request = jwt.fromMethodAndUrl('GET', '/rest/resource/you/want');

const tokenData = {
    "iss": 'issuer-val',
    "iat": now.unix(),                      // the time the token is generated
    "exp": now.add(3, 'minutes').unix(),    // token expiry time (recommend 3 minutes after issuing)
    "qsh": jwt.createQueryStringHash(req)   // [Query String Hash](https://developer.atlassian.com/cloud/jira/platform/understanding-jwt/#a-name-qsh-a-creating-a-query-string-hash)
};

const secret = 'xxx';

const token = jwt.encode(tokenData, secret);
console.log(token);

Decode a JWT token

/*
 * jwt.decode(token, secret, noVerify, algorithm)
 *
 * Decodes the JWT token and verifies the signature using the secret and algorithm. Algorithm defaults to HS256.
 */
var decoded = jwt.decode(token, secret);
console.log(decoded); //=> { foo: 'bar' }

/*
 * Decode without verifing the signature of the token.
 * Tokens should never be used without verifying the signature as otherwise payload trust cannot be established.
 */
var decoded = jwt.decode(token, null, true);
console.log(decoded); //=> { foo: 'bar' }

Miscellaneous Utilities

• jwt.createQueryStringHash(req, checkBodyForParams, baseUrl)
  Create a QSH using the algorithm defined by the algorithm .
• jwt.createCanonicalRequest(req, checkBodyForParams, baseUrl)
  Creates a canonical request which is used to calculate the QSH for the JWT token. Prefer using #createQueryStringHash() directly.
• jwt.fromExpressRequest(expressRequest: ExpressRequest)
  Converts an Express.js Request into a Request object that can be used with other methods in this library.
• jwt.fromMethodAndUrl(method: string, url: string)
  This takes in a method and url, both as plain strings, and turns them into a Request object that can be used with other methods in this library.
• jwt.fromMethodAndPathAndBody
  This takes in a method, a url, and some form params from a request body and turns them into a Request object that can be used with other methods in this library.

Algorithms

By default the algorithm to encode is HS256.

The supported algorithms for encoding and decoding are HS256, HS384, HS512 and RS256.

// encode using HS512
jwt.encode(payload, secret, 'HS512')

Migrating from 0.1.x to 1.x.x

The 1.x.x release brings some breaking changes, probably the most important change is that our methods no longer accept the Express.js request object as an argument but instead use our own intermediate Request object.

A convenience method called fromExpressRequest has been written to ease the transition. You can use it like so:

import * as jwt from 'atlassian-jwt';
import { Request as ExpressRequest } from 'express';

const eReq: ExpressRequest = ...;
const qsh = jwt.createQueryStringHash(jwt.fromExpressRequest(eReq));

Other methods, like fromMethodAndUrl and fromMethodAndPathAndBody were written to allow easier generation of Request objects from other libraries.

Guides for developers

Publishing this library

To publish this library:

npm run tsc
npm publish

This has been combined into a single command with:

npm run build-and-publish

Only the built typescript files will be published with this library.