Node.js and TypeScript Tutorial: Secure an Express API

build-api

git clone git@github.com:auth0-blog/menu-api-express-ts.git \
menu-api \
--branch build-api

cd menu-api

npm i

.env

touch .env

.env

PORT=7000

npm run dev

In the Build an API with Node.js and TypeScript Tutorial, you went over how to build an API using Express, a Node.js web framework, and TypeScript, an open-source language that builds on JavaScript. You learned how to define data models, create a data service, and quickly build modular endpoints.

Now, this tutorial will show you how to secure the API using Auth0. To see your API in action, you'll use a production client called "WHATABYTE Dashboard," which is inspired by the sleek web player from Spotify:

One of the requirements for this project is that only authorized users can write records to the store. To quickly and securely achieve that, you can use Auth0 to manage your application's user credentials.

.env

.env

PORT=7000
AUTH0_AUDIENCE=
AUTH0_DOMAIN=

.env

npm run dev

Create Authentication Middleware

You'll rely on a middleware function to protect an Express API endpoint. Express will execute an authorization middleware function before it executes the callback function of the controller that handles the request.

You can use two patterns to integrate your endpoints with the authorization middleware function.

The first option is to "inject" an authorization middleware function in the controller as follows:

itemsRouter.post(
  "/",
  authorizationFunction,
  async (req: Request, res: Response) => {
    // Controller logic...
  }
);

Here, Express calls

authorizationFunction()

itemsRouter.post

authorizationFunction

(a) invoke the next function in the middleware chain, the router handler function, if it can determine that the user has the authorization to access the resource or,

(b) close the request-response cycle by responding with a

401 Unauthorized

The approach of adding authorization middleware by controller gives you granular and low-level control of the authorization flow. However, it can be tedious to inject the authorization middleware function per controller if you have many of them.

As an alternative, you can separate the public controllers from the protected controllers using the authorization middleware as a boundary between groups. For example, within an Express router, you could do the following:

// Public API endpoints

itemsRouter.get(...);

// Protected API endpoints

itemsRouter.use(authorizationFunction);

itemsRouter.post(...);
itemsRouter.put(...);
itemsRouter.delete(...);

As such, client applications can access the

GET

However, client requests can only access endpoints that you define after your application mounts

authorizationFunction

itemsRouter

authorizationFunction

A JWT defines a compact and self-contained way to transmit information between parties as a JSON object securely. This information can be verified and trusted because it is digitally signed, making JWTs useful to perform authorization.

Once the user logs in using a client application, Auth0 provides the client with an access token that defines the resources that the client has permission to access or manipulate with that token. The access token defines what users can do in your API in the JSON object it encapsulates. As such, the client must include the access token with each subsequent request it makes to a protected API endpoint.

Interested in getting up-to-speed with JWTs as soon as possible?

Download the free ebook

You'll use the partition approach for this application as you need to protect all the endpoints that write data to the store.

Install authorization dependencies

To create your authorization middleware function, you need to install these two packages:

npm i express-jwt jwks-rsa

Here's what these packages do for you:

• express-jwt

  : Validates the authorization level of HTTP requests using JWT tokens in your Node.js application.

• jwks-rsa

  : A library to retrieve RSA signing keys from a JWKS (JSON Web Key Set) endpoint.

Since you are working on a TypeScript project, you also need the type definitions for these packages; however, only the

express-jwt

@types

npm i -D @types/express-jwt

The helper function you need from the

jwks-rsa

package is simple and doesn't require strong typing.

Next, create a file to define your authorization middleware function:

touch src/middleware/authz.middleware.ts

Populate

src/middleware/authz.middleware.ts

// src/middleware/authz.middleware.ts

import jwt from "express-jwt";
import jwksRsa from "jwks-rsa";
import * as dotenv from "dotenv";

dotenv.config();

export const checkJwt = jwt({
  secret: jwksRsa.expressJwtSecret({
    cache: true,
    rateLimit: true,
    jwksRequestsPerMinute: 5,
    jwksUri: `https://${process.env.AUTH0_DOMAIN}/.well-known/jwks.json`
  }),

  // Validate the audience and the issuer.
  audience: process.env.AUTH0_AUDIENCE,
  issuer: `https://${process.env.AUTH0_DOMAIN}/`,
  algorithms: ["RS256"]
});

When you call the

checkJwt

jwt

jwt

• The

  audience

  and

  issuer

  of the JWT. You have defined these values in your

  .env

  file. Express has loaded into this module using

  dotenv.config()

  .

• The

  algorithms

  used to sign the JWT.

• The

  secret

  used to sign the JWT.

To obtain the secret, you need to do some additional work: you use the

expressJwtSecret

jwks-rsa

The

checkJwt

req

res

next()

All that's left to do is mount the

checkJwt

itemsRouter

Open

src/items/items.router.ts

checkJwt

Required External Modules and Interfaces

/**
 * Required External Modules and Interfaces
 */

import express, { Request, Response } from "express";
import * as ItemService from "./items.service";
import { BaseItem, Item } from "./item.interface";

import { checkJwt } from "../middleware/authz.middleware";

Then, under the

Controller Definitions

POST items

itemsRouter.use(checkJwt)

/**
 * Controller Definitions
 */

// GET items
itemsRouter.get(...);

// GET items/:id

itemsRouter.get(...);

// ✨ New! Mount authorization middleware

itemsRouter.use(checkJwt); // 👈 👀

// POST items

itemsRouter.post(...);

// PUT items/:id

itemsRouter.put(...);

// DELETE items/:id

itemsRouter.delete(...);

To test that Express is protecting your write endpoints, issue the following requesting in the terminal:

curl -X POST -H 'Content-Type: application/json' -d '{
  "name": "Salad",
  "price": 499,
  "description": "Fresh",
  "image": "https://cdn.auth0.com/blog/whatabyte/salad-sm.png"
}' http://localhost:7000/api/menu/items -i

The server replies with an

HTTP/1.1 401 Unauthorized

No authorization token was found

https://dashboard.whatabyte.app/

https://menu-api.example.com

https://dashboard.whatabyte.app/home

https://dashboard.whatabyte.app/home

http://

https://

https://dashboard.whatabyte.app

https://dashboard.whatabyte.app/home

menu-admin

menu-admin

No authorization token was found

Configure Role-Based Access Control (RBAC)

Your API server is protecting your write endpoints, but any authenticated user can modify the menu items. This scenario is far from ideal as you don't want regular customers to change an item's price, for example. As such, you need a mechanism to limit access to your API resources and demonstrate that being authenticated is not the same as being authorized. However, if all that you want for now is to restrict API access to logged-in users, you've achieved that, and you are done.

A straightforward way to implement access control is to create a set of write permissions and bundle them in a

menu-admin

To re-iterate: being authenticated won't be enough to being authorized to write data to the store.

The practice described above is known as Role-Based Access Control (RBAC), which you can implement quickly for your API using the Auth0 Dashboard. You can implement RBAC and enforce it on your server as follows:

On the Auth0 side

• Create permissions for the Menu API you created earlier.

• Create a role called

  menu-admin

  .

• Assign permissions from the Menu API to the

  menu-admin

  role.

• Assign the

  menu-admin

  role to a user.

• Add the

  menu-admin

  role permissions to the access token created for users with the role when they sign in.

On the server side

• Define the

  menu-admin

  role permissions in a TypeScript

  enum

  .

• Define the permissions required to access an endpoint by passing permission values as arguments to an authorization middleware function, which Express calls before the endpoint route handler.

• Implement the authorization middleware function to determine authorization by comparing the permissions required by the endpoint against the permissions present in a user's access token.

As you can see, implementing authorization is a complex process that involves many steps. Any errors or omissions in the process of implementation can leave an API at risk of being compromised. Thankfully, you can delegate the creation and maintenance of permissions, roles, and users to Auth0 and focus only on enforcing authorization on your server.

With the plan clearly outlined, let's get started.

permissions

permissions

menu-admin

menu-admin

function(user, context, callback) {
  const namespace = 'https://menu-api.example.com';

  if (context.authorization && context.authorization.roles) {
    const assignedRoles = context.authorization.roles;

    if (context.idToken) {
      const idTokenClaims = context.idToken;
      idTokenClaims[`${namespace}/roles`] = assignedRoles;
      context.idToken = idTokenClaims;
    }

    if (context.accessToken) {
      const accessTokenClaims = context.accessToken;
      accessTokenClaims[`${namespace}/roles`] = assignedRoles;
      context.accessToken = accessTokenClaims;
    }
  }

  callback(null, user, context);
}

function(user, context, callback) {
  // ...
}

function(user, context, callback) {
  const namespace = 'https://menu-api.example.com';

  //...
}

context

authorization

roles

function(user, context, callback) {
  const namespace = 'https://menu-api.example.com';

  if (context.authorization && context.authorization.roles) {
   // ...
  }

  // ...
}

context.authorization

context.authorization.roles

roles

assignedRoles

context

function(user, context, callback) {
  const namespace = 'https://menu-api.example.com';

  if (context.authorization && context.authorization.roles) {
    const assignedRoles = context.authorization.roles;

    if (context.idToken) {
      // ...
    }

    if (context.accessToken) {
      // ...
    }
  }

  // ...
}

<namespace>/roles

assignedRoles

function(user, context, callback) {
  const namespace = 'https://menu-api.example.com';

  if (context.authorization && context.authorization.roles) {
    const assignedRoles = context.authorization.roles;

    if (context.idToken) {
      const idTokenClaims = context.idToken;
      idTokenClaims[`${namespace}/roles`] = assignedRoles;
      context.idToken = idTokenClaims;
    }

    if (context.accessToken) {
      const accessTokenClaims = context.accessToken;
      accessTokenClaims[`${namespace}/roles`] = assignedRoles;
      context.accessToken = accessTokenClaims;
    }
  }

  // ...
}

callback

function(user, context, callback) {
  // ...

  callback(null, user, context);
}

menu-admin

menu-admin

menu-admin

admin@example.com

menu-admin

menu-admin

admin@example.com

menu-admin

Implement Role-Based Access Control

To implement role-based access control (RBAC) in Express, you create an RBAC middleware function that inspects the access token provided in the client request and verifies that it has the permissions required by the endpoint it needs to access. You also must call this function before your application reaches the route handler function of the protected endpoint controller.

Consequently, if the proper permissions are present in the access token, your RBAC middleware function calls the next middleware function in the chain, effectively granting the client request with access to the protected endpoint. Otherwise, your application terminates the request-response cycle and sends a response with a

403 Forbidden

To help you inspect the access token for permissions easily, you will use the

express-jwt-authz

npm install express-jwt-authz

Using this package, you will inspect the

permissions

To start, create a file to define a middleware function that checks for permissions:

touch src/middleware/permissions.middleware.ts

Then, populate

src/middleware/permissions.middleware.ts

const jwtAuthz = require("express-jwt-authz");

export const checkPermissions = (permissions: string | string[]) => {
  return jwtAuthz([permissions], {
    customScopeKey: "permissions",
    checkAllScopes: true,
    failWithError: true
  });
};

The

jwtAuthz

jwtAuthz

• customScopeKey

  : By default,

  jwtAuthz

  checks permissions against the

  scope

  claim of the access token. You can use this option to change the claim

  jwtAuthz

  should use. In this case, you specify that the access token stores permission-related data in a claim called

  permissions

  .

• checkAllScopes

  : When set to

  true

  , all the expected permissions by the endpoint must be present in the

  customScopeKey

  claim of the access token. If any permission is missing, this middleware function throws an error, which effectively denies the client application making the request from accessing the protected endpoint.

• failWithError

  : When set to

  true

  ,

  jwtAuthz

  will forward any errors to the

  next()

  middleware function instead of ending the response directly. In this case,

  jwtAuthz

  will forward the error to your

  errorHandler

  middleware function, where you can better customize the error response sent to the client.

jwtAuthz

Request

Response

next

checkPermissions

jwtAuthz

itemsRouter.post(
  "/",
  [
    checkJwt,
    jwtAuthz([ItemPermissions.CreateItems], {
      customScopeKey: "permissions",
      checkAllScopes: true,
      failWithError: true
    })
  ],
  async (req: Request, res: Response) => {
    // function body...
  }
);

itemsRouter.put(
  "/",
  [
    checkJwt,
    jwtAuthz([ItemPermissions.UpdateItems], {
      customScopeKey: "permissions",
      checkAllScopes: true,
      failWithError: true
    })
  ],
  async (req: Request, res: Response) => {
    // function body...
  }
);

However, this requires you to repeatedly configure

jwtAuthz

jwtAuthz

checkPermissions

permissions

jwtAuthz

permissions

jwtAuthz

With the RBAC authorization middleware function created, you are now ready to wire it into any controller that needs role-based access control (RBAC).

Define permissions locally

To make it easy to manage and use permissions in your code, you can define them using a TypeScript

enum

src/items

touch src/items/item-permission.ts

Populate

src/items/item-permission.ts

export enum ItemPermission {
  CreateItems = "create:items",
  UpdateItems = "update:items",
  DeleteItems = "delete:items",
}

A TypeScript

enum

Apply permissions middleware

To protect the write endpoints with RBAC, you need to inject the

checkPermissions

Open

src/items/items.router.ts

Required External Modules and Interfaces

/**
 * Required External Modules and Interfaces
 */

import express, { Request, Response } from "express";
import * as ItemService from "./items.service";
import { BaseItem, Item } from "./item.interface";

import { checkJwt } from "../middleware/authz.middleware";
import { checkPermissions } from "../middleware/permissions.middleware";
import { ItemPermission } from "./item-permission";

Next, locate the

Controller Definitions

/**
 * Controller Definitions
 */

// GET items/ ...

// GET items/:id ...

// Mount authorization middleware

itemsRouter.use(checkJwt);

// POST items

itemsRouter.post(
  "/",
  checkPermissions(ItemPermission.CreateItems),
  async (req: Request, res: Response) => {
    try {
      const item: BaseItem = req.body;

      const newItem = await ItemService.create(item);

      res.status(201).json(newItem);
    } catch (e) {
      res.status(500).send(e.message);
    }
  }
);

// PUT items/:id

itemsRouter.put(
  "/:id",
  checkPermissions(ItemPermission.UpdateItems),
  async (req: Request, res: Response) => {
    const id: number = parseInt(req.params.id, 10);

    try {
      const itemUpdate: Item = req.body;

      const existingItem: Item = await ItemService.find(id);

      if (existingItem) {
        const updatedItem = await ItemService.update(id, itemUpdate);
        return res.status(200).json(updatedItem);
      }

      const newItem = await ItemService.create(itemUpdate);

      res.status(201).json(newItem);
    } catch (e) {
      res.status(500).send(e.message);
    }
  }
);

// DELETE items/:id

itemsRouter.delete(
  "/:id",
  checkPermissions(ItemPermission.DeleteItems),
  async (req: Request, res: Response) => {
    try {
      const id: number = parseInt(req.params.id, 10);
      await ItemService.remove(id);

      res.sendStatus(204);
    } catch (e) {
      res.status(500).send(e.message);
    }
  }
);

Now that the authorization guards are in place, any attempt to create a new menu item directly using a non-admin access token results in failure:

• The

  checkPermissions()

  function injected in the

  POST api/menu/items/

  endpoint detects the presence of the required permissions.

• If the required permissions are missing, it then passes a

  403

  exception down the middleware chain.

• As such, you successfully prevent the application from invoking the route handler of this endpoint.

Remember that by mounting the

checkJwt()

itemsRouter.use(checkJwt)

checkPermissions()

You are effectively implementing Role-Based Access Control (RBAC) using a two-layer approach powered by Express middleware functions.

name: Coffee
price: 299
description: Woke
image: https://images.ctfassets.net/23aumh6u8s0i/6HS0xLG6bx52KJrqyqfznk/50f9350a7791fa86003024af4762f4ca/whatabyte_coffee-sm.png

menu-admin

Insufficient scope

403 (Forbidden)

menu-admin

menu-admin

What's Next

You have implemented authorization in Express to control the resources that your users can access. You have learned how to implement different access levels:

• Access based on authentication status.
  • If you have logged in, you are authorized to access the resources.
• Access based on permissions.

  • If you have logged in and have the required permissions, you are authorized to access the resources.

    This tutorial covered the most common authorization use cases for an Express API server. However, Auth0 is an extensible and flexible platform that can help you achieve even more. If you have a more complex use case, check out the [Auth0 Architecture Scenarios](https://auth0.com/docs/architecture-scenarios) to learn more about the typical architecture scenarios we have identified when working with customers on implementing Auth0.

Let me know in the comments below what you thought of this tutorial. Thank you for reading this far, and happy engineering!