Examples ☁️

Include a Bitbucket markdown file

Here is a markdown file from the public repository atlassian/atlassian-jwt-js available at this url: https://bitbucket.org/atlassian/atlassian-jwt-js/src/master/README.md.

atlassian-jwt

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

For more information on using JWT tokens with Atlassian apps, 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.encodeSymmetric(tokenData, secret);
console.log(token);

Decode a JWT token

const decoded = jwt.decodeSymmetric(token, secret);
console.log(decoded); //=> { foo: 'bar' }

// Decode without verifing the signature of the token.
// Don't do this unless that's your intention.
const decoded = jwt.decodeSymmetric(token, null, true);
console.log(decoded); //=> { foo: 'bar' }

Miscellaneous Utilities

jwt.createQueryStringHash(req, checkBodyForParams, baseUrl) Creates 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, url) 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(method, url, body) 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.
jwt.getKeyId(token) Extracts kid from a jwt token.
jwt.getAlgorithm(token) Extracts alg from a jwt token.

Algorithms

By default the algorithm to encode is HS256.

The supported algorithms for encoding and decoding are HS256, HS384, HS512, and RS256. See Critical vulnerabilities in JSON Web Token libraries.

If you use TypeScript:

// Encode using HS256 (default)
jwt.encodeSymmetric(payload, secret);

// Encode using HS512
jwt.encodeSymmetric(payload, secret, jwt.Algorithm.HS512);

// Encode using RS256, optinally accepts kid
jwt.encodeAsymmetric(payload, privateKey, jwt.Algorithm.RS256, { kid: 'f50f8562-f146-4b98-9bbb-7ce9545603b6' });

// Decode using RS256
jwt.decodeAsymmetric(token, publicKey, jwt.Algorithm.RS256);

If you use JavaScript:

// Encode using HS256 (default)
jwt.encodeSymmetric(payload, secret);

// Encode using HS512
jwt.encodeSymmetric(payload, secret, 'HS512');

// Encode using RS256, optinally accepts kid
jwt.encodeAsymmetric(payload, privateKey, 'RS256', { kid: 'f50f8562-f146-4b98-9bbb-7ce9545603b6' });

// Decode using RS256
jwt.decodeAsymmetric(token, publicKey, 'RS256');

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.

Migrating from 1.x.x to 2.x.x

The 2.x.x release supports RS256 asymmetric algorithm which can be used with encodeAsymmetric and decodeAsymmetric functions. encode and decode functions in 1.x.x are renamed to encodeSymmetric and decodeSymmetric which supports symmetric algorithms only.

Guides for developers

Publishing this library

Update version in package.json and lib/jwt.ts.

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.

Include a Bitbucket source code file

Here is a typescript file from the public repository atlassian/atlassian-jwt-js available at this url: https://bitbucket.org/atlassian/atlassian-jwt-js/src/master/test/signed_url_interoperability_test.ts.

/**
 * The file ./resources/jwt-signed-urls.json is generated by a corresponding test in Atlassian Connect:
 * com.atlassian.plugin.connect.test.plugin.JwtSigningInteroperabilityTest
 *
 * See the file for the most up-to-date reference.
 */
import _ from 'lodash';
import * as fs from 'fs';
import Uri from 'jsuri';
import qs from 'qs';
import * as jwt from '../lib/jwt';
import * as assert from 'assert';
import { Request } from 'express';

const file = __dirname + '/resources/jwt-signed-urls.json';
const testData = JSON.parse(fs.readFileSync(file, 'utf8'));

_.each(testData.tests, test => {
    describe(test.name, function () {
        const uri = new Uri(test.signedUrl);
        const queryString = qs.parse((uri as any).uriParts.query);
        const token = queryString.jwt;

        it('should decode', done => {
            // Throws error if not valid
            jwt.decodeSymmetric(token as string, testData.secret, jwt.SymmetricAlgorithm.HS256, false);
            done();
        });

        it('should match canonical url', done => {
            const req = createRequest();
            const actualCanonicalUrl = jwt.createCanonicalRequest(req, false, test.addonBaseUrl || '');
            assert.equal(actualCanonicalUrl, test.canonicalUrl);
            done();
        });

        it('should match qsh', done => {
            const req = createRequest();
            const actualQsh = jwt.createQueryStringHash(req, false, test.addonBaseUrl || '');
            const decodedToken =
                jwt.decodeSymmetric(token as string, testData.secret, jwt.SymmetricAlgorithm.HS256, true);
            assert.equal(actualQsh, decodedToken.qsh);
            done();
        });

        function createRequest(): jwt.Request {
            return jwt.fromExpressRequest({
                method: 'GET',
                originalUrl: uri.path(),
                query: queryString
            } as Request);
        }
    });
});

Include Bitbucket pull requests

Here is an example of including the Pull Requests from the public repository atlassian/atlassian-jwt-js with the filters state="MERGED" AND title~"fix":

Include Bitbucket branches

Here is an example of including the branches from the public repository atlassian/atlassian-jwt-js :

Include Bitbucket commits

Here is an example of including commits from the public repository atlassian/atlassian-jwt-js :

Include Bitbucket tags

Here is an example of including the tags from the public repository atlassian/atlassian-jwt-js :

Include Bitbucket issues

Here is an example of including the issues from the public repository atlassian/atlassian-jwt-js with the filters state="resolved":