On this post, we will talk about JSON Web Tokens, most commonly known by its acronym JWT. If you have done any web development work for the last few years, you must have heard of it, or even used a package that uses JWT to implement a token-based authentication mechanism under the hood.
We will examine what a JWT is and describe what comprises a valid token. Next, we will implement basic authentication using Node/Express and the jwt-simple package.
What is JWT?
According to the comprehensive Introduction to JSON Web Tokens:
JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a secret (with the HMAC algorithm) or a public/private key pair using RSA.
JWT is said to be compact because it uses JSON which is pretty much how every web application these days pass data across consumers and other APIs. That means that a JWT can be easily passed around as a query parameter, through a POST request, or through request headers. Being self-contained adds up to the portability because it means that it can contain the needed information in the token itself. We will see this in practice in our small Express application.
Anatomy of JSON Web Tokens
A JSON Web Token is made up of three parts that are separated by dots. The first two parts are called Header and Payload, respectively. Both of them are Base64 encoded JSON objects that contain several information that we are going to briefly discuss below.
The Header object contains the type of the token and the encryption algorithm used. Since we are going to create a basic authentication mechanism on an Express app, the type is JWT and the encryption will be a keyed-hash message authentication code (HMAC). Since we will use a package which will simplify the encoding and decoding of our tokens, there is no need to set this explicitly and we will stick with the defaults which is HMAC SHA256.
The Payload contains what the specification refers to as claims. They are information that can be attached to the token for identification or verification purposes. Claims are further categorized as Registered Claims, Public Claims and Private Claims. On our example app, we will use Registered Claims to identify our application as the Issuer of the token and to set its expiry. We will also make use of the user's name and their password as Public Claims.
Now that we have discussed the first and the second part of a JWT, it is now time for the third one, which is called the Signature. Once we have the Header and the Payload properly encoded as a Base64 strings, they need to be concatenated with a dot, and then hashed with the app secret. This process will produce the token's signature. The secret can be any string, but as the name suggests, keep it secret because it can be used to decode your token's Header and Payload.
Here's an example token:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0ODk5OTEyNjI3NTIsImlzcyI6IkpvaG4gQ3Jpc29zdG9tbyIsIm5hbWUiOiJjcmlzb3N0b21vIiwiZW1haWwiOiJjcmlzb3N0b21vQGpvaG4uY29tIn0._CP8KU_AX4XNJKyxD561LTiFbY0HcPFKRgI1AztGMsI
Try to notice the dots that separate the three parts of the token. To wrap this section up and as a review, the first two parts are the Base64 encoded JSON objects that contains information about the user and our application. The third part is hashed version of the first two parts with the application key used as the hash key.
Application Demo
It is now time for the application demo. At this point, we already have a good grasp of what a JSON Web Token is and its parts. We are now ready to put this into practice by creating a demo application to solidify the concepts that we have learned. Before we start, a word of precaution:
The example app that we will build in this section will be for the sole purpose of understanding how JWT can be used to implement a barebones token-based authentication. Please do not use this example in production. There are better packages out there that uses jwt-simple under the hood and makes this process foolproof.
Dependencies
Creating the user store and the token store
Since this is a fairly small project, we will not use any real databases. Instead, the users will be hard coded in an array, as well as the tokens. We will create two files to implement these functionalities in this section.
USERS.JS
const users = [{ _id: 1, name: "john", email: "john@crisostomo.com", password: "john12345" },{ _id: 2, name: "crisostomo", email: "crisostomo@john.com", password: "crisostomo12345" },];function validateUser(username, password) {const user = users.find((user) => {return user.name === username && user.password === password;});return user;}module.exports = { validateUser };
TOKENS.JS
const tokens = [];module.exports = {add: function(token, payload) {tokens[token] = payload;},isValid: function(token) {if (!tokens[token]) {return false;}if (tokens[token].exp <= new Date()) {const index = tokens.indexOf(token);tokens.splice(index, 1);return false;} else {return true;}}}
On our users.js file, we exposed a convenience method to let us easily validate a user by searching through our users array. Our token.js file allows us to add a token with the associated payload. It also has a method that can check a token's validity.
Creating our application
This is where we create our application. Our app will have two entry points: one for accessing a restricted route, and another one where we can obtain tokens for registered users. The endpoint for these functionalities are /secretInfo and /token.
On a high level, we can obtain a valid token if we send a POST request to the /token endpoint with valid user credentials. This token can then be used to access the information at /secretInfo.
The first thing that we need to do is to require the dependencies mentioned above, and set the server to run at port 8080:
const express = require('express');const bodyParser = require('body-parser');const jwt = require('jwt-simple');const moment = require('moment');const users = require('./users');const tokens = require('./tokens');const app = express();app.use(bodyParser.json());const jwtAttributes = {SECRET: 'this_will_be_used_for_hashing_signature',ISSUER: 'John Crisostomo',HEADER: 'x-jc-token',EXPIRY: 120,};app.listen(8080);console.log('JWT Example is now listening on :8080');
This sets all our dependencies and imports our user and token stores. We also declared an object called jwtAttributes. This object contains the claims that will be used for our token, as well as some other attributes like the app secret and header key. At this point, this server will run but will not do anything because we have not implemented any routes or endpoints.
Let us start implementing the /token endpoint.
// AUTH MIDDLEWARE FOR /token ENDPOINTconst auth = function (req, res) {const { EXPIRY, ISSUER, SECRET } = jwtAttributes;if (req.body) {const user = users.validateUser(req.body.name, req.body.password);if (user) {const expires = moment().add(EXPIRY, 'seconds').valueOf();const payload = {exp: expires,iss: ISSUER,name: user.name,email: user.email,};const token = jwt.encode(payload, SECRET);tokens.add(token, payload);res.json({ token });} else {res.sendStatus(401);}} else {res.sendStatus(401);}};app.post('/token', auth, (req, res) => {res.send('token');});
Before we set up our route for the /token endpoint, we created the authentication middleware. It will check if the request has a body and it will try to validate if a user with the matching password is found on our user store. This middleware could make use of more validation, but I am keeping it simple to make our example less cluttered.
If a user is found, it sets the token's expiry with the help of moment and the set amount of time defined in our jwtAttributes object. Next, we proceed in constructing our payload. Notice that we have two registered claims exp and iss, which stands for expiry and issuer, and two public claims which are the user's name and email.
Finally, the encode method of the jwt-simple package abstracts the process of encoding our payload. It generates our token by concatenating the header and hashing them with the app secret. If the request's body is invalid or if the user/password combo is not found on our store, we return a 401 Unauthorized response. The same goes for sending blank requests, too.
Time for the /secretInfo endpoint.
// VALIDATE MIDDLEWARE FOR /secretInfoconst validate = function (req, res, next) {const { HEADER, SECRET } = jwtAttributes;const token = req.headers[HEADER];if (!token) {res.statusMessage = 'Unauthorized: Token not found';res.sendStatus('401').end();} else {try {const decodedToken = jwt.decode(token, SECRET);} catch(e) {res.statusMessage = 'Unauthorized: Invalid token';res.sendStatus('401');return;}if (!tokens.isValid(token)) {res.statusMessage = 'Unauthorized : Token is either invalid or expired';res.sendStatus('401');return;}next();}};app.get('/secretInfo', validate, (req, res) => {res.send('The secret of life is 42.');});
Similar to our /token endpoint, we start by implementing our validate middleware. It checks if a token exists in the header, then jwt-simple decodes the token. It gets validated through our token store's method. If the token is found and is not yet expired, we call on the next handler, and the secret message is sent. Otherwise, we send our 401 Unauthorized as the response.
Now that we have finished implementing both endpoints, we can proceed in testing them with Postman.
Testing our app with Postman
Postman is a nifty Chrome app that can be used to test REST APIs. You can get Postman here.
If we send a GET request directly to /secretInfo, we will get a status code of 401, along with an Unauthorized message:
Likewise, sending an incorrect user credentials will give us the same response:
Providing the /token endpoint with a valid payload (a valid JSON with correct user credentials) will provide us a token that is bound to expire in two minutes:
We can then use the token by sending another GET request to /secretInfoendpoint, by including the token through the x-jc-token header (we specified this key on the jwtAttributes object):
Wrap up
That's it! We have successfully implemented a basic token-based authentication on Express by using jwt-simple. Equipped with this knowledge, we can now understand how popular authentication packages uses JWT under the hood. That makes us more capable to troubleshoot JWT authentication problems or even contribute to these packages. If you want to clone the files in this mini-tutorial, you can get them on this Github repository. If you are interested in learning more about JWT, you can get a free eBook here.