How one can Use JWT and Node.js for Higher App Safety

To guard proprietary information, it’s crucial to safe any API that gives providers to shoppers by means of requests. A well-built API identifies intruders and prevents them from gaining entry, and a JSON Internet Token (JWT) permits shopper requests to be validated and doubtlessly encrypted.

On this tutorial, we’ll show the method of including JWT safety to a Node.js API implementation. Whereas there are a number of methods to implement API layer safety, JWT is a extensively adopted, developer-friendly safety implementation in Node.js API tasks.

JWT Defined

JWT is an open normal that safely permits info alternate in a space-constrained atmosphere utilizing a JSON format. It’s easy and compact, enabling a broad vary of functions that elegantly mix numerous different safety requirements.

JWTs, carrying our encoded information, could also be encrypted and hid, or signed and simply readable. If a token is encrypted, all required hash and algorithmic info is contained in it to assist its decryption. If a token is signed, its recipient will analyze the JWT’s contents and may be capable of detect whether or not it has been tampered with. Tamper detection is supported by means of JSON Internet Signature (JWS), essentially the most generally used signed token method.

JWT consists of three main elements, every composed of a name-value pair assortment:

We outline JWT’s header utilizing the JOSE normal to specify the token’s sort and cryptographic info. The required name-value pairs are:

JWS signatures assist each symmetric and uneven algorithms to supply token tamper detection. (Further header name-value pairs are required and specified by the varied algorithms, however a full exploration of these header names is past the scope of this text.)

Payload

JWT’s required payload is the encoded (doubtlessly encrypted) content material that one social gathering could ship to a different. A payload is a set of claims, every represented by a name-value pair. These claims are the significant portion of a message’s transmitted information (i.e., not together with the message header and metadata). The payload is enclosed in a safe communication, sealed with our token’s signature.

Every declare could use a reputation that originates within the JWT’s reserved set, or we could outline a reputation ourselves. If we outline a declare identify ourselves, finest practices dictate to keep away from any identify listed within the following reserved glossary, to keep away from any confusion.

Particular reserved names should be included within the payload no matter any extra claims current:

Signature

To securely implement JWT, a signature (i.e., JWS) is advisable to be used by an supposed token recipient. A signature is a straightforward, URL-safe, base64-encoded string that verifies a token’s authenticity.

The signature perform depends on the header-specified algorithm. The header and payload elements are each handed to the algorithm, as follows:

base64_url(fn_signature(base64_url(header)+base64_url(payload)))

Any social gathering, together with the recipient, could independently run this signature calculation to match it to the JWT signature from throughout the token to see whether or not the signatures match.

Whereas a token with delicate information must be encrypted (i.e., utilizing JWE), if our token doesn’t comprise delicate information, it’s acceptable to make use of JWS for nonencrypted and due to this fact public, but encoded, payload claims. JWS permits our signature to comprise info enabling our token’s recipient to find out if the token has been modified, and thus corrupted, by a 3rd social gathering.

Frequent JWT Use Circumstances

With JWT’s construction and intent defined, let’s discover the explanations to make use of it. Although there’s a broad spectrum of JWT use circumstances, we’ll concentrate on the most typical eventualities.

API Authentication

When a shopper authenticates with our API, a JWT is returned—this use case is frequent in e-commerce functions. The shopper then passes this token to every subsequent API name. The API layer will validate the authorization token, verifying that the decision could proceed. Purchasers could entry an API’s routes, providers, and assets as acceptable for the authenticated shopper’s degree.

Federated Id

JWT is often used inside a federated id ecosystem, during which customers’ identities are linked throughout a number of separate methods, resembling a third-party web site that makes use of Gmail for its login. A centralized authentication system is liable for validating a shopper’s id and producing a JWT to be used with any API or service linked to the federated id.

Whereas nonfederated API tokens are easy, federated id methods sometimes work with two token varieties: entry tokens and refresh tokens. An entry token is short-lived; throughout its interval of validity, an entry token authorizes entry to a protected useful resource. Refresh tokens are long-lived and permit a shopper to request new entry tokens from authorization servers with no requirement that shopper credentials be re-entered.

Stateless Classes

Stateless session authentication is much like API authentication, however with extra info packed right into a JWT and handed alongside to an API with every request. A stateless session primarily entails client-side information; for instance, an e-commerce utility that authenticates its customers and shops their purchasing cart gadgets may retailer them utilizing a JWT.

On this use case, the server avoids storing a per-user state, limiting its operations to utilizing solely the data handed to it. Having a stateless session on the server aspect entails storing extra info on the shopper aspect, and thus requires the JWT to incorporate details about the consumer’s interplay, resembling a cart or the URL to which it’s going to redirect. Because of this a stateless session’s JWT contains extra info than a comparable stateful session’s JWT.

JWT Safety Greatest Practices

To keep away from frequent assault vectors, it’s crucial to observe JWT finest practices:

With these finest practices in thoughts, let’s transfer to a sensible implementation of making a JWT and Node.js instance, during which we put these factors into use. At a excessive degree, we’re going to create a brand new mission during which we’ll authenticate and authorize our endpoints with JWT, following three main steps.

We are going to use Specific as a result of it gives a fast strategy to create back-end functions at each enterprise and interest ranges, making the mixing of a JWT safety layer easy and easy. And we’ll go together with Postman for testing because it permits for efficient collaboration with different builders to standardize end-to-end testing.

The ultimate, ready-to-deploy model of the complete mission repository is on the market as a reference whereas strolling by means of the mission.

Step 1: Create the Node.js API

Create the mission folder and initialize the Node.js mission:

mkdir jwt-nodejs-security
cd jwt-nodejs-security
npm init -y

Subsequent, add mission dependencies and generate a fundamental tsconfig file (which we is not going to edit throughout this tutorial), required for TypeScript:

npm set up typescript ts-node-dev @varieties/bcrypt @varieties/specific --save-dev
npm set up bcrypt body-parser dotenv specific
npx tsc --init

With the mission folder and dependencies in place, we’ll now outline our API mission.

Configuring the API Atmosphere

The mission will use system atmosphere values inside our code. Let’s first create a brand new configuration file, src/config/index.ts, that retrieves atmosphere variables from the working system, making them obtainable to our code:

import * as dotenv from 'dotenv';
dotenv.config();

// Create a configuration object to carry these atmosphere variables.
const config = {
    // JWT essential variables
    jwt: {
        // The key is used to signal and validate signatures.
        secret: course of.env.JWT_SECRET,
        // The viewers and issuer are used for validation functions.
        viewers: course of.env.JWT_AUDIENCE,
        issuer: course of.env.JWT_ISSUER
    },
    // The fundamental API port and prefix configuration values are:
    port: course of.env.PORT || 3000,
    prefix: course of.env.API_PREFIX || 'api'
};

// Make our affirmation object obtainable to the remainder of our code.
export default config;

The dotenv library permits atmosphere variables to be set in both the working system or inside an .env file. We’ll use an .env file to outline the next values:

• JWT_SECRET
• JWT_AUDIENCE
• JWT_ISSUER
• PORT
• API_PREFIX

Your .env file ought to look one thing just like the repository instance. With the fundamental API configuration full, we now transfer to coding our API’s storage.

Setting Up In-memory Storage

To keep away from the complexities that include a totally fledged database, we’ll retailer our information domestically within the server state. Let’s create a TypeScript file, src/state/customers.ts, to comprise the storage and CRUD operations for API consumer info:

import bcrypt from 'bcrypt';
import { NotFoundError } from '../exceptions/notFoundError';
import { ClientError } from '../exceptions/clientError';

// Outline the code interface for consumer objects. 
export interface IUser {
    id: string;
    username: string;
    // The password is marked as non-compulsory to permit us to return this construction 
    // with out a password worth. We'll validate that it isn't empty when making a consumer.
    password?: string;
    function: Roles;
}

// Our API helps each an admin and common consumer, as outlined by a job.
export enum Roles {
    ADMIN = 'ADMIN',
    USER = 'USER'
}

// Let's initialize our instance API with some consumer data.
// NOTE: We generate passwords utilizing the Node.js CLI with this command:
// "await require('bcrypt').hash('PASSWORD_TO_HASH', 12)"
let customers: { [id: string]: IUser } = {
    '0': {
        id: '0',
        username: 'testuser1',
        // Plaintext password: testuser1_password
        password: '$2b$12$ov6s318JKzBIkMdSMvHKdeTMHSYMqYxCI86xSHL9Q1gyUpwd66Q2e', 
        function: Roles.USER
    },
    '1': {
        id: '1',
        username: 'testuser2',
        // Plaintext password: testuser2_password
        password: '$2b$12$63l0Br1wIniFBFUnHaoeW.55yh8.a3QcpCy7hYt9sfaIDg.rnTAPC', 
        function: Roles.USER
    },
    '2': {
        id: '2',
        username: 'testuser3',
        // Plaintext password: testuser3_password
        password: '$2b$12$fTu/nKtkTsNO91tM7wd5yO6LyY1HpyMlmVUE9SM97IBg8eLMqw4mu',
        function: Roles.USER
    },
    '3': {
        id: '3',
        username: 'testadmin1',
        // Plaintext password: testadmin1_password
        password: '$2b$12$tuzkBzJWCEqN1DemuFjRuuEs4z3z2a3S5K0fRukob/E959dPYLE3i',
        function: Roles.ADMIN
    },
    '4': {
        id: '4',
        username: 'testadmin2',
        // Plaintext password: testadmin2_password
        password: '$2b$12$.dN3BgEeR0YdWMFv4z0pZOXOWfQUijnncXGz.3YOycHSAECzXQLdq',
        function: Roles.ADMIN
    }
};

let nextUserId = Object.keys(customers).size;

Earlier than we implement particular API routing and handler features, let’s concentrate on error-handling assist for our mission to propagate JWT finest practices all through our mission code.

Including Customized Error Dealing with

Specific doesn’t assist correct error dealing with with asynchronous handlers, because it doesn’t catch promise rejections from inside asynchronous handlers. To catch such rejections, we have to implement an error-handling wrapper perform.

Let’s create a brand new file, src/middleware/asyncHandler.ts:

import { NextFunction, Request, Response } from 'specific';

/**
 * Async handler to wrap the API routes, permitting for async error dealing with.
 * @param fn Operate to name for the API endpoint
 * @returns Promise with a catch assertion
 */
export const asyncHandler = (fn: (req: Request, res: Response, subsequent: NextFunction) => void) => (req: Request, res: Response, subsequent: NextFunction) => {
    return Promise.resolve(fn(req, res, subsequent)).catch(subsequent);
};

The asyncHandler perform wraps API routes and propagates promise errors into an error handler. Earlier than we code the error handler, we’ll outline some customized exceptions in src/exceptions/customError.ts to be used in our utility:

// Notice: Our customized error extends from Error, so we are able to throw this error as an exception.
export class CustomError extends Error {
    message!: string;
    standing!: quantity;
    additionalInfo!: any;

    constructor(message: string, standing: quantity = 500, additionalInfo: any = undefined) {
        tremendous(message);
        this.message = message;
        this.standing = standing;
        this.additionalInfo = additionalInfo;
    }
};

export interface IResponseError {
    message: string;
    additionalInfo?: string;
}

Now we create our error handler within the file src/middleware/errorHandler.ts:

import { Request, Response, NextFunction } from 'specific';
import { CustomError, IResponseError } from '../exceptions/customError';

export perform errorHandler(err: any, req: Request, res: Response, subsequent: NextFunction) {
    console.error(err);
    if (!(err instanceof CustomError)) {
        res.standing(500).ship(
            JSON.stringify({
                message: 'Server error, please attempt once more later'
            })
        );
    } else {
        const customError = err as CustomError;
        let response = {
            message: customError.message
        } as IResponseError;
        // Test if there's extra data to return.
        if (customError.additionalInfo) response.additionalInfo = customError.additionalInfo;
        res.standing(customError.standing).sort('json').ship(JSON.stringify(response));
    }
}

We’ve got already carried out common error dealing with for our API, however we additionally need to assist throwing wealthy errors from inside our API handlers. Let’s outline these wealthy error utility features now, with each outlined in a separate file:

import { CustomError } from './customError';

export class ClientError extends CustomError {
    constructor(message: string) {
        tremendous(message, 400);
    }
}

import { CustomError } from './customError';

export class UnauthorizedError extends CustomError {
    constructor(message: string) {
        tremendous(message, 401);
    }
}

import { CustomError } from './customError';

export class ForbiddenError extends CustomError {
    constructor(message: string) {
        tremendous(message, 403);
    }
}

import { CustomError } from './customError';

export class NotFoundError extends CustomError {
    constructor(message: string) {
        tremendous(message, 404);
    }
}

With the fundamental mission and error-handling features carried out, let’s outline our API endpoints and their handler features.

Defining Our API Endpoints

Let’s create a brand new file, src/index.ts, to outline our API’s entry level:

import specific from 'specific';
import { json } from 'body-parser';
import { errorHandler } from './middleware/errorHandler';
import config from './config';

// Instantiate an Specific object.
const app = specific();
app.use(json());

// Add error dealing with because the final middleware, simply previous to our app.pay attention name.
// This ensures that every one errors are all the time dealt with.
app.use(errorHandler);

// Have our API pay attention on the configured port.
app.pay attention(config.port, () => {
    console.log(`server is listening on port ${config.port}`);
});

We have to replace the npm-generated bundle.json file so as to add our default utility entry level. Notice that we need to place this endpoint file reference on the prime of the primary object’s attribute listing:

{
    "primary": "index.js",
    "scripts": {
        "begin": "ts-node-dev src/index.ts"
...

Subsequent, our API wants its routes outlined, and for these routes to redirect to their handlers. Let’s create a file, src/routes/index.ts, to hyperlink consumer operation routes into our utility. We’ll outline the route specifics and their handler definitions shortly.

import { Router } from 'specific';
import consumer from './consumer';

const routes = Router();
// All consumer operations might be obtainable below the "customers" route prefix.
routes.use('/customers', consumer);
// Permit our router for use outdoors of this file.
export default routes;

We are going to now embody these routes within the src/index.ts file by importing our routing object after which asking our utility to make use of the imported routes. For reference, it’s possible you’ll evaluate the accomplished file model together with your edited file.

import routes from './routes/index';

// Add our route object to the Specific object. 
// This should be earlier than the app.pay attention name.
app.use('/' + config.prefix, routes);

// app.pay attention... 

Now our API is prepared for us to implement the precise consumer routes and their handler definitions. We’ll outline the consumer routes within the src/routes/consumer.ts file and hyperlink to the soon-to-be-defined controller, UserController:

import { Router } from 'specific';
import UserController from '../controllers/UserController';
import { asyncHandler } from '../middleware/asyncHandler';

const router = Router();

// Notice: Every handler is wrapped with our error dealing with perform.
// Get all customers.
router.get('/', [], asyncHandler(UserController.listAll));

// Get one consumer.
router.get('/:id([0-9a-z]{24})', [], asyncHandler(UserController.getOneById));

// Create a brand new consumer.
router.publish('/', [], asyncHandler(UserController.newUser));

// Edit one consumer.
router.patch('/:id([0-9a-z]{24})', [], asyncHandler(UserController.editUser));

// Delete one consumer.
router.delete('/:id([0-9a-z]{24})', [], asyncHandler(UserController.deleteUser));

The handler strategies our routes will name depend on helper features to function on our consumer info. Let’s add these helper features to the tail finish of our src/state/customers.ts file earlier than we outline UserController:

// Place these features on the finish of the file.
// NOTE: Validation errors are dealt with immediately inside these features.

// Generate a replica of the customers with out their passwords.
const generateSafeCopy = (consumer : IUser) : IUser => {
    let _user = { ...consumer };
    delete _user.password;
    return _user;
};

// Recuperate a consumer if current.
export const getUser = (id: string): IUser => {
    if (!(id in customers)) throw new NotFoundError(`Consumer with ID ${id} not discovered`);
    return generateSafeCopy(customers[id]);
};

// Recuperate a consumer based mostly on username if current, utilizing the username because the question.
export const getUserByUsername = (username: string): IUser | undefined => {
    const possibleUsers = Object.values(customers).filter((consumer) => consumer.username === username);
    // Undefined if no consumer exists with that username.
    if (possibleUsers.size == 0) return undefined;
    return generateSafeCopy(possibleUsers[0]);
};

export const getAllUsers = (): IUser[] => {
    return Object.values(customers).map((elem) => generateSafeCopy(elem));
};


export const createUser = async (username: string, password: string, function: Roles): Promise<IUser> => {
    username = username.trim();
    password = password.trim();

    // Reader: Add checks in keeping with your customized use case.
    if (username.size === 0) throw new ClientError('Invalid username');
    else if (password.size === 0) throw new ClientError('Invalid password');
    // Test for duplicates.
    if (getUserByUsername(username) != undefined) throw new ClientError('Username is taken');

    // Generate a consumer id.
    const id: string = nextUserId.toString();
    nextUserId++;
    // Create the consumer.
    customers[id] = {
        username,
        password: await bcrypt.hash(password, 12),
        function,
        id
    };
    return generateSafeCopy(customers[id]);
};

export const updateUser = (id: string, username: string, function: Roles): IUser => {
    // Test that consumer exists.
    if (!(id in customers)) throw new NotFoundError(`Consumer with ID ${id} not discovered`);

    // Reader: Add checks in keeping with your customized use case.
    if (username.trim().size === 0) throw new ClientError('Invalid username');
    username = username.trim();
    const userIdWithUsername = getUserByUsername(username)?.id;
    if (userIdWithUsername !== undefined && userIdWithUsername !== id) throw new ClientError('Username is taken');

    // Apply the adjustments.
    customers[id].username = username;
    customers[id].function = function;
    return generateSafeCopy(customers[id]);
};

export const deleteUser = (id: string) => {
    if (!(id in customers)) throw new NotFoundError(`Consumer with ID ${id} not discovered`);
    delete customers[id];
};

export const isPasswordCorrect = async (id: string, password: string): Promise<boolean> => {
    if (!(id in customers)) throw new NotFoundError(`Consumer with ID ${id} not discovered`);
    return await bcrypt.evaluate(password, customers[id].password!);
};

export const changePassword = async (id: string, password: string) => {
    if (!(id in customers)) throw new NotFoundError(`Consumer with ID ${id} not discovered`);
    
    password = password.trim();
    // Reader: Add checks in keeping with your customized use case.
    if (password.size === 0) throw new ClientError('Invalid password');

    // Retailer encrypted password
    customers[id].password = await bcrypt.hash(password, 12);
};

Lastly, we are able to create the src/controllers/UserController.ts file:

import { NextFunction, Request, Response } from 'specific';
import { getAllUsers, Roles, getUser, createUser, updateUser, deleteUser } from '../state/customers';

class UserController {
    static listAll = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Retrieve all customers.
        const customers = getAllUsers();
        // Return the consumer info.
        res.standing(200).sort('json').ship(customers);
    };

    static getOneById = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Get the ID from the URL.
        const id: string = req.params.id;

        // Get the consumer with the requested ID.
        const consumer = getUser(id);

        // NOTE: We are going to solely get right here if we discovered a consumer with the requested ID.
        res.standing(200).sort('json').ship(consumer);
    };

    static newUser = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Get the username and password.
        let { username, password } = req.physique;
        // We will solely create common customers by means of this perform.
        const consumer = await createUser(username, password, Roles.USER);

        // NOTE: We are going to solely get right here if all new consumer info 
        // is legitimate and the consumer was created.
        // Ship an HTTP "Created" response.
        res.standing(201).sort('json').ship(consumer);
    };

    static editUser = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Get the consumer ID.
        const id = req.params.id;

        // Get values from the physique.
        const { username, function } = req.physique;

        if (!Object.values(Roles).contains(function))
            throw new ClientError('Invalid function');

        // Retrieve and replace the consumer file.
        const consumer = getUser(id);
        const updatedUser = updateUser(id, username || consumer.username, function || consumer.function);

        // NOTE: We are going to solely get right here if all new consumer info 
        // is legitimate and the consumer was up to date.
        // Ship an HTTP "No Content material" response.
        res.standing(204).sort('json').ship(updatedUser);
    };

    static deleteUser = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Get the ID from the URL.
        const id = req.params.id;

        deleteUser(id);

        // NOTE: We are going to solely get right here if we discovered a consumer with the requested ID and    
        // deleted it.
        // Ship an HTTP "No Content material" response.
        res.standing(204).sort('json').ship();
    };
}

export default UserController;

This configuration exposes the next endpoints:

• /API_PREFIX/customers GET: Get all customers.
• /API_PREFIX/customers POST: Create a brand new consumer.
• /API_PREFIX/customers/{ID} DELETE: Delete a particular consumer.
• /API_PREFIX/customers/{ID} PATCH: Replace a particular consumer.
• /API_PREFIX/customers/{ID} GET: Get a particular consumer.

At this level, our API routes and their handlers are carried out.

Step 2: Add and Configure JWT

We now have our fundamental API implementation, however we nonetheless must implement authentication and authorization to maintain it safe. We’ll use JWTs for each functions. The API will emit a JWT when a consumer authenticates and confirm that every subsequent name is allowed utilizing that authentication token.

For every shopper name, an authorization header containing a bearer token passes our generated JWT to the API: Authorization: Bearer <TOKEN>.

To assist JWT, let’s set up some dependencies into our mission:

npm set up @varieties/jsonwebtoken --save-dev
npm set up jsonwebtoken

One strategy to signal and validate a payload in JWT is thru a shared secret algorithm. For our setup, we selected HS256 as that algorithm, because it is without doubt one of the easiest symmetric (shared secret) algorithms obtainable within the JWT specification. We’ll use the Node CLI, together with the crypto bundle to generate a novel secret:

require('crypto').randomBytes(128).toString('hex');

We will change the key at any time. Nonetheless, every change will make all customers’ authentication tokens invalid and pressure them to sign off.

Creating the JWT Authentication Controller

For a consumer to log in and replace their passwords, our API’s authentication and authorization functionalities require endpoints that assist these actions. To attain this, we’ll create src/controllers/AuthController.ts, our JWT authentication controller:

import { NextFunction, Request, Response } from 'specific';
import { signal } from 'jsonwebtoken';
import { CustomRequest } from '../middleware/checkJwt';
import config from '../config';
import { ClientError } from '../exceptions/clientError';
import { UnauthorizedError } from '../exceptions/unauthorizedError';
import { getUserByUsername, isPasswordCorrect, changePassword } from '../state/customers';

class AuthController {
    static login = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Make sure the username and password are offered.
        // Throw an exception again to the shopper if these values are lacking.
        let { username, password } = req.physique;
        if (!(username && password)) throw new ClientError('Username and password are required');

        const consumer = getUserByUsername(username);

        // Test if the offered password matches our encrypted password.
        if (!consumer || !(await isPasswordCorrect(consumer.id, password))) throw new UnauthorizedError("Username and password do not match");

        // Generate and signal a JWT that's legitimate for one hour.
        const token = signal({ userId: consumer.id, username: consumer.username, function: consumer.function }, config.jwt.secret!, {
            expiresIn: '1h',
            notBefore: '0', // Can't use prior to now, could be configured to be deferred.
            algorithm: 'HS256',
            viewers: config.jwt.viewers,
            issuer: config.jwt.issuer
        });

        // Return the JWT in our response.
        res.sort('json').ship({ token: token });
    };

    static changePassword = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Retrieve the consumer ID from the incoming JWT.
        const id = (req as CustomRequest).token.payload.userId;

        // Get the offered parameters from the request physique.
        const { oldPassword, newPassword } = req.physique;
        if (!(oldPassword && newPassword)) throw new ClientError("Passwords do not match");

        // Test if outdated password matches our presently saved password, then we proceed.
        // Throw an error again to the shopper if the outdated password is mismatched.
        if (!(await isPasswordCorrect(id, oldPassword))) throw new UnauthorizedError("Previous password would not match");

        // Replace the consumer password.
        // Notice: We is not going to hit this code if the outdated password evaluate failed.
        await changePassword(id, newPassword);

        res.standing(204).ship();
    };
}
export default AuthController;

Our authentication controller is now full, with separate handlers for login verification and consumer password adjustments.

Implementing Authorization Hooks

To make sure that every of our API endpoints is safe, we have to create a typical JWT validation and function authentication hook that we are able to add to every of our handlers. We are going to implement these hooks into middleware, the primary of which can validate incoming JWT tokens within the src/middleware/checkJwt.ts file:

import { Request, Response, NextFunction } from 'specific';
import { confirm, JwtPayload } from 'jsonwebtoken';
import config from '../config';

// The CustomRequest interface permits us to supply JWTs to our controllers.
export interface CustomRequest extends Request {
    token: JwtPayload;
}

export const checkJwt = (req: Request, res: Response, subsequent: NextFunction) => {
    // Get the JWT from the request header.
    const token = <string>req.headers['authorization'];
    let jwtPayload;

    // Validate the token and retrieve its information.
    attempt {
        // Confirm the payload fields.
        jwtPayload = <any>confirm(token?.break up(' ')[1], config.jwt.secret!, {
            full: true,
            viewers: config.jwt.viewers,
            issuer: config.jwt.issuer,
            algorithms: ['HS256'],
            clockTolerance: 0,
            ignoreExpiration: false,
            ignoreNotBefore: false
        });
        // Add the payload to the request so controllers could entry it.
        (req as CustomRequest).token = jwtPayload;
    } catch (error) {
        res.standing(401)
            .sort('json')
            .ship(JSON.stringify({ message: 'Lacking or invalid token' }));
        return;
    }

    // Go programmatic movement to the subsequent middleware/controller.
    subsequent();
};

Our code provides token info to the request, which is then forwarded. Notice that the error handler isn’t obtainable at this level in our code’s context as a result of the error handler will not be but included in our Specific pipeline.

Subsequent we create a JWT authorization file, src/middleware/checkRole.ts, to validate consumer roles:

import { Request, Response, NextFunction } from 'specific';
import { CustomRequest } from './checkJwt';
import { getUser, Roles } from '../state/customers';

export const checkRole = (roles: Array<Roles>) => {
    return async (req: Request, res: Response, subsequent: NextFunction) => {
        // Discover the consumer with the requested ID.
        const consumer = getUser((req as CustomRequest).token.payload.userId);

        // Guarantee we discovered a consumer.
        if (!consumer) {
            res.standing(404)
                .sort('json')
                .ship(JSON.stringify({ message: 'Consumer not discovered' }));
            return;
        }

        // Make sure the consumer's function is contained within the approved roles.
        if (roles.indexOf(consumer.function) > -1) subsequent();
        else {
            res.standing(403)
                .sort('json')
                .ship(JSON.stringify({ message: 'Not sufficient permissions' }));
            return;
        }
    };
};

Notice that we retrieve the consumer’s function as saved on the server, as an alternative of the function contained within the JWT. This enables a beforehand authenticated consumer to have their permissions modified midstream inside their authentication session. Authorization to a route might be appropriate, whatever the authorization info that’s saved throughout the JWT.

Now we replace our routes information. Let’s create the src/routes/auth.ts file for our authorization middleware:

import { Router } from 'specific';
import AuthController from '../controllers/AuthController';
import { checkJwt } from '../middleware/checkJwt';
import { asyncHandler } from '../middleware/asyncHandler';

const router = Router();
// Connect our authentication route.
router.publish('/login', asyncHandler(AuthController.login));

// Connect our change password route. Notice that checkJwt enforces endpoint authorization.
router.publish('/change-password', [checkJwt], asyncHandler(AuthController.changePassword));

export default router;

So as to add in authorization and required roles for every endpoint, let’s replace the contents of our consumer routes file, src/routes/consumer.ts:

import { Router } from 'specific';
import UserController from '../controllers/UserController';
import { Roles } from '../state/customers';
import { asyncHandler } from '../middleware/asyncHandler';
import { checkJwt } from '../middleware/checkJwt';
import { checkRole } from '../middleware/checkRole';

const router = Router();

// Outline our routes and their required authorization roles.
// Get all customers.
router.get('/', [checkJwt, checkRole([Roles.ADMIN])], asyncHandler(UserController.listAll));

// Get one consumer.
router.get('/:id([0-9]{1,24})', [checkJwt, checkRole([Roles.USER, Roles.ADMIN])], asyncHandler(UserController.getOneById));

// Create a brand new consumer.
router.publish('/', asyncHandler(UserController.newUser));

// Edit one consumer.
router.patch('/:id([0-9]{1,24})', [checkJwt, checkRole([Roles.USER, Roles.ADMIN])], asyncHandler(UserController.editUser));

// Delete one consumer.
router.delete('/:id([0-9]{1,24})', [checkJwt, checkRole([Roles.ADMIN])], asyncHandler(UserController.deleteUser));

export default router;

Every endpoint validates the incoming JWT with the checkJwt perform after which authorizes the consumer roles with the checkRole middleware.

To complete integrating the authentication routes, we have to connect our authentication and consumer routes to our API’s route listing within the src/routes/index.ts file, changing its contents:

import { Router } from 'specific';
import consumer from './consumer';

const routes = Router();
// All auth operations might be obtainable below the "auth" route prefix.
routes.use('/auth', auth);
// All consumer operations might be obtainable below the "customers" route prefix.
routes.use('/customers', consumer);
// Permit our router for use outdoors of this file.
export default routes;

This configuration now exposes the extra API endpoints:

• /API_PREFIX/auth/login POST: Log in a consumer.
• /API_PREFIX/auth/change-password POST: Change a consumer’s password.

With our authentication and authorization middleware in place, and the JWT payload obtainable in every request, our subsequent step is to make our endpoint handlers extra sturdy. We’ll add code to make sure customers have entry solely to the specified functionalities.

Combine JWT Authorization into Endpoints

So as to add additional validations to our endpoints’ implementation in an effort to outline the info every consumer can entry and/or modify, we’ll replace the src/controllers/UserController.ts file:

import { NextFunction, Request, Response } from 'specific';
import { getAllUsers, Roles, getUser, createUser, updateUser, deleteUser } from '../state/customers';
import { ForbiddenError } from '../exceptions/forbiddenError';
import { ClientError } from '../exceptions/clientError';
import { CustomRequest } from '../middleware/checkJwt';

class UserController {
    static listAll = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Retrieve all customers.
        const customers = getAllUsers();
        // Return the consumer info.
        res.standing(200).sort('json').ship(customers);
    };

    static getOneById = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Get the ID from the URL.
        const id: string = req.params.id;

        // New code: Prohibit USER requestors to retrieve their very own file.
        // Permit ADMIN requestors to retrieve any file.
        if ((req as CustomRequest).token.payload.function === Roles.USER && req.params.id !== (req as CustomRequest).token.payload.userId) {
            throw new ForbiddenError('Not sufficient permissions');
        }

        // Get the consumer with the requested ID.
        const consumer = getUser(id);

        // NOTE: We are going to solely get right here if we discovered a consumer with the requested ID.
        res.standing(200).sort('json').ship(consumer);
    };

    static newUser = async (req: Request, res: Response, subsequent: NextFunction) => {
        // NOTE: No change to this perform.
        // Get the consumer identify and password.
        let { username, password } = req.physique;
        // We will solely create common customers by means of this perform.
        const consumer = await createUser(username, password, Roles.USER);

        // NOTE: We are going to solely get right here if all new consumer info 
        // is legitimate and the consumer was created.
        // Ship an HTTP "Created" response.
        res.standing(201).sort('json').ship(consumer);
    };

    static editUser = async (req: Request, res: Response, subsequent: NextFunction) => {
        // Get the consumer ID.
        const id = req.params.id;

        // New code: Prohibit USER requestors to edit their very own file.
        // Permit ADMIN requestors to edit any file.
        if ((req as CustomRequest).token.payload.function === Roles.USER && req.params.id !== (req as CustomRequest).token.payload.userId) {
            throw new ForbiddenError('Not sufficient permissions');
        }

        // Get values from the physique.
        const { username, function } = req.physique;

        // New code: Don't permit USERs to vary themselves to an ADMIN.
        // Confirm you can not make your self an ADMIN if you're a USER.
        if ((req as CustomRequest).token.payload.function === Roles.USER && function === Roles.ADMIN) {
            throw new ForbiddenError('Not sufficient permissions');
        }
        // Confirm the function is appropriate.
        else if (!Object.values(Roles).contains(function)) 
             throw new ClientError('Invalid function');

        // Retrieve and replace the consumer file.
        const consumer = getUser(id);
        const updatedUser = updateUser(id, username || consumer.username, function || consumer.function);

        // NOTE: We are going to solely get right here if all new consumer info 
        // is legitimate and the consumer was up to date.
        // Ship an HTTP "No Content material" response.
        res.standing(204).sort('json').ship(updatedUser);
    };

    static deleteUser = async (req: Request, res: Response, subsequent: NextFunction) => {
        // NOTE: No change to this perform.
        // Get the ID from the URL.
        const id = req.params.id;

        deleteUser(id);

        // NOTE: We are going to solely get right here if we discovered a consumer with the requested ID and    
        // deleted it.
        // Ship an HTTP "No Content material" response.
        res.standing(204).sort('json').ship();
    };
}

export default UserController;

With a whole and safe API, we are able to start testing our code.

Step 3: Take a look at JWT and Node.js

To check our API, we should first begin our mission:

npm run begin

Subsequent, we’ll set up Postman, after which create a request to authenticate a take a look at consumer:

Now that we’ve got a JWT for our take a look at consumer, we’ll create one other request to check certainly one of our endpoints and get the obtainable USER data:

1. Create a brand new GET request for consumer authentication.
2. Identify this request “JWT Node.js Get Customers.”
3. Set the request’s deal with to localhost:3000/api/customers.
4. On the request’s authorization tab, set the sort to Bearer Token.
5. Copy the return JWT from our earlier request into the “Token” discipline on this tab.
6. Run the request in Postman.
7. View the consumer listing returned by our API.

These examples are just some of many attainable checks. To totally discover the API calls and take a look at our authorization logic, observe the demonstrated sample to create extra checks.

Higher Node.js and JWT Safety

After we mix JWT right into a Node.js API, we achieve leverage with industry-standard libraries and implementations to maximise our outcomes and decrease developer effort. JWT is each feature-rich and developer-friendly, and it’s straightforward to implement in our app with a minimal studying curve for builders.

Nonetheless, builders should nonetheless train warning when including JWT safety to their tasks to keep away from frequent pitfalls. By following our steerage, builders ought to really feel empowered to higher apply JWT implementations inside Node.js. JWT’s trusted safety together with the flexibility of Node.js supplies builders nice flexibility to create options.

The editorial workforce of the Toptal Engineering Weblog extends its gratitude to Abhijeet Ahuja and Mohamed Khaled for reviewing the code samples and different technical content material introduced on this article.