Another ExpressJS API tutorial for 2021, part 11— Configuring Permissions
Hi there, today we are going to configure one of the missing part of our API made with ExpressJS and Typescript, the permission levels to access the API
Hi there, if it is your first time arriving here we are creating a series on how to build an API using ExpressJS and Typescript. The first article can be found here.
Just as a quick overview, here is the series of articles that we are writing:
- Create your hello world ExpressJS API (Yes… we always need to start with a hello world)
- Configure our hello world application to use Typescript (TS is cool, believe me ;) )
- Create our first CRUD API endpoints for an user (Everyone wants a registered user in their applications, no?)
- Create and configure your controllers (We will talk about it after)
- Create and configure your services (What the h. is that?)
- Middleware’s! (Yes, we need and use it everyday)
- End to end testings!
- Configuring a secure way to manage user permissions via API
- Putting all together into a Docker container
- Configuring a simple MongoDB to connect to our application
- Configuring permission level to the application — We are here now ;)
- Add logs with Winston!
Articles ago we created the Auth module and in this article we are going to use it at our routes and ensure that the client of our API will use the JWT and will have a proper permissionLevel to use it.
Let’s get started!
First make sure to use our last updated branch that you can find here.
What we want to do is basically add a field called permissionLevel to the users who will generate a JWT at our API. We will use a bitwise AND approach.
Mathematically saying, bitwise AND approach is a very nice tool for us as a developer. I will not go into a deep explanation but I highly recommend you to read about and understand the background of how it works. In a short explanation:
Using a bitwise and approach will allow us to define a powder of 2 integer permissions that you can use to configure which is the required “level”. In the other way, a client would need a sum of the permission levels at his JWT which will be used to validate if the user can/cannot use a specific endpoint request.
That said, let’s pretend that we have the following permissions:
- 1: free account
- 2: paid not premium account can use it
- 4: only a premium account can use it
- 8: admin access routes
An admin JWT would want to use all routes, so it should have 1 + 2 + 4 + 8 permission level which will be 15. Following the logic, a premium account would be 7, a paid not premium 3, and a free account 1.
But how javascript would understand it? That’s simple, at javascript we are able to use the bitwise AND operator without coding it. For that, we just need to create a if condition and use the operator & (yep, just one and NOT &&) like the following:
if(requiredPermissionLevel & userPermissionLevel){...Every time that this condition will be true then you can assume that the user have the required permission to access a determined route.
How it will work at the code? Let’s create middlewares for it!
At the folder app/common/middlewares let’s create a filled called common.permission.middleware.ts and add the following:
export class CommonPermissionMiddleware {public static MAX_PERMISSION = 4096 * 2;
public static BASIC_PERMISSION = 1;constructor() {}
minimumPermissionLevelRequired(requiredPermissionLevel: any) {
return (req: any, res: any, next: any) => {
try {
let userPermissionLevel = parseInt(req.jwt.permissionLevel);
if (userPermissionLevel & Number.parseInt(requiredPermissionLevel)) {
next();
} else {
res.status(403).send({});
}
} catch (e) {
console.log(e);
}};
};async onlySameUserOrAdminCanDoThisAction(req: any, res: any, next: any) {
let userPermissionLevel = parseInt(req.jwt.permissionLevel);
let userId = req.jwt.userId;
if (req.params && req.params.userId && userId === req.params.userId) {
return next();
} else {
if (userPermissionLevel & CommonPermissionMiddleware.MAX_PERMISSION) {
return next();
} else {
return res.status(403).send({});
}
}
};async onlyAdminCanDoThisAction(req: any, res: any, next: any) {
let userPermissionLevel = parseInt(req.jwt.permissionLevel);
if (userPermissionLevel & CommonPermissionMiddleware.MAX_PERMISSION) {
return next();
} else {
return res.status(403).send({});
}
};}
We created three functions here that will be used whenever we will want. Basically one is a generic when you can add the value that you want (remember, powder of 2 always), then some user routes that an admin can use and finally an admin only middleware. Also, we added a public and static fields that can be shared when we will configure the permissionLevel at our routes.
Remember that we are creating a generic approach here, you can change the permissions as you wish
Now we need to update some code. We need to add a permission to the user, and set this permissionLevel whenever he generates a JWT code.
At our users.controller.ts let’s update the code as the following:
import express from 'express';
import {UsersService} from '../services/user.services';
import {SecurePass} from 'argon2-pass';export class UsersController {
constructor() {
}async listUsers(req: express.Request, res: express.Response) {
const usersService = UsersService.getInstance();
const users = await usersService.list(100, 0);
res.status(200).send(users);
}async getUserById(req: express.Request, res: express.Response) {
const usersService = UsersService.getInstance();
const user = await usersService.readById(req.params.userId);
res.status(200).send(user);
}async createUser(req: express.Request, res: express.Response) {
const usersService = UsersService.getInstance();
const sp = new SecurePass();
const password = Buffer.from(req.body.password);
req.body.password = (await sp.hashPassword(password)).toString('utf-8');
req.body.permissionLevel = 1 + 2 + 4 + 8;
const userId = await usersService.create(req.body);
res.status(201).send({_id: userId});
}async patch(req: express.Request, res: express.Response) {
const usersService = UsersService.getInstance();
await usersService.patchById(req.body);
res.status(204).send(``);
}async put(req: express.Request, res: express.Response) {
const usersService = UsersService.getInstance();
await usersService.updateById(req.body);
res.status(204).send(``);
}async removeUser(req: express.Request, res: express.Response) {
const usersService = UsersService.getInstance();
await usersService.deleteById(req.params.userId);
res.status(204).send(``);
}}
Here we added the permissionLevel whenever a new user is created with the following:
req.body.permissionLevel = 1 + 2 + 4 + 8;That means that a new user will always have at least 4 different types of permission level.
Since we are at the users folder, let’s already update the user.routes.config.ts file as the following:
import {CommonRoutesConfig, configureRoutes} from '../common/common.routes.config';
import {UsersController} from './controllers/users.controller';
import {UsersMiddleware} from './middlewares/users.middleware';
import {CommonPermissionMiddleware} from '../common/middlewares/common.permission.middleware';
import {JwtMiddleware} from '../auth/middlewares/jwt.middleware';import express from 'express';export class UsersRoutes extends CommonRoutesConfig implements configureRoutes {
constructor(app: express.Application) {
super(app, 'UsersRoute');
this.configureRoutes();
}configureRoutes() {
const usersController = new UsersController();
const usersMiddleware = UsersMiddleware.getInstance();
const jwtMiddleware = JwtMiddleware.getInstance();
const commonPermissionMiddleware = new CommonPermissionMiddleware();
this.app.get(`/users`, [
jwtMiddleware.validJWTNeeded,
commonPermissionMiddleware.onlyAdminCanDoThisAction,
usersController.listUsers
]);this.app.post(`/users`, [
usersMiddleware.validateRequiredCreateUserBodyFields,
usersMiddleware.validateSameEmailDoesntExist,
usersController.createUser
]);this.app.put(`/users/:userId`, [
jwtMiddleware.validJWTNeeded,
commonPermissionMiddleware.minimumPermissionLevelRequired(CommonPermissionMiddleware.BASIC_PERMISSION),
commonPermissionMiddleware.onlySameUserOrAdminCanDoThisAction,
usersMiddleware.validateUserExists,
usersMiddleware.extractUserId,
usersController.put
]);this.app.patch(`/users/:userId`, [
jwtMiddleware.validJWTNeeded,
commonPermissionMiddleware.minimumPermissionLevelRequired(CommonPermissionMiddleware.BASIC_PERMISSION),
commonPermissionMiddleware.onlySameUserOrAdminCanDoThisAction,
usersMiddleware.validateUserExists,
usersMiddleware.extractUserId,
usersController.patch
]);this.app.delete(`/users/:userId`, [
jwtMiddleware.validJWTNeeded,
commonPermissionMiddleware.minimumPermissionLevelRequired(CommonPermissionMiddleware.BASIC_PERMISSION),
commonPermissionMiddleware.onlySameUserOrAdminCanDoThisAction,
usersMiddleware.validateUserExists,
usersMiddleware.extractUserId,
usersController.removeUser
]);
this.app.get(`/users/:userId`, [
jwtMiddleware.validJWTNeeded,
commonPermissionMiddleware.minimumPermissionLevelRequired(CommonPermissionMiddleware.BASIC_PERMISSION),
commonPermissionMiddleware.onlySameUserOrAdminCanDoThisAction,
usersMiddleware.validateUserExists,
usersMiddleware.extractUserId,
usersController.getUserById
]);
}}
We added the middlewares and configured it for our code demonstration.
At our auth module, let’s update the app/auth/middlewares/auth.middleware.ts file:
import express from 'express';
import {UsersService} from '../../users/services/user.services';
import {SecurePass} from 'argon2-pass';export class AuthMiddleware {
private static instance: AuthMiddleware;static getInstance() {
if (!AuthMiddleware.instance) {
AuthMiddleware.instance = new AuthMiddleware();
}
return AuthMiddleware.instance;
}async validateBodyRequest(req: express.Request, res: express.Response, next: express.NextFunction) {
if(req.body && req.body.email && req.body.password){
next();
}else{
res.status(400).send({error: 'Missing body fields: email, password'});
}
}async verifyUserPassword(req: express.Request, res: express.Response, next: express.NextFunction) {
const userService = UsersService.getInstance();
const user: any = await userService.getByEmail(req.body.email);
if (user) {
let passwordHash = user.password;
const sp = new SecurePass();
const passwordBuffer = Buffer.from(passwordHash, 'utf8');
const requestPassword = Buffer.from(req.body.password, 'utf8');
const result = await sp.verifyHash(requestPassword, passwordBuffer);
if (SecurePass.isValid(result)) {
req.body = {
userId: user._id,
email: user.email,
provider: 'email',
permissionLevel: user.permissionLevel,
};
return next();
} else {
res.status(400).send({errors: `Invalid e-mail and/or password`});
}
} else {
res.status(400).send({errors: `Invalid e-mail and/or password`});
}
}
}Now we are sending the permissionLevel to the jwt that will be generated.
Before testing it, we will create a service to help our e2e testing that will generate some JWT for us. at app/auth/services folder (if doesn’t exist, let’s create it) let’s create a file called jwt.service.ts and add the following:
// todo: move to a secure place
const jwtSecret = 'My!@!Se3cr8tH4sh';
const tokenExpirationInSeconds = 36000;
const jwt = require('jsonwebtoken');
let crypto = require('crypto');
export class JwtService{
public static generateToken(permissionLevel: Number) {
try {let refreshId = '123321' + jwtSecret;
let salt = crypto.randomBytes(16).toString('base64');
let hash = crypto.createHmac('sha512', salt).update(refreshId).digest("base64");let expiresAt = new Date();
expiresAt.setHours(expiresAt.getHours() + (tokenExpirationInSeconds / 3600));
let token = jwt.sign({
userId: '007',
email: '[email protected]',
permissionLevel: permissionLevel,
provider: 'email',
name: 'bond',
refreshKey: salt
}, jwtSecret);
let b = Buffer.from(hash);
let refreshToken = b.toString('base64');
return token;
} catch (err) {
throw err;
}
}
}Updating and testing our e2e integration
Our code is already ready to go, but since we have our e2e testing integration, let’s update our tests!
/test/users/users.test.ts
import app from '../../app/app';
import {agent as request} from 'supertest';
import {expect} from 'chai';
import * as shortUUID from "short-uuid";
import {JwtService} from '../../app/auth/services/jwt.service';
let firstUserIdTest = '';
let firstUserBody = {
"name" : "Marcos SIlva",
"email" : `tio.makin+${shortUUID.generate()}@gmail.com`,
"password" : "Pass#your!word"
};let jwt = {
accessToken: '',
refreshToken: ''
};const adminJWT = JwtService.generateToken(2147483647);it('should POST /users', async function () {
const res = await request(app)
.post('/users').send(firstUserBody);
expect(res.status).to.equal(201);
expect(res.body).not.to.be.empty;
expect(res.body).to.be.an("object");
expect(res.body._id).to.be.an('string');
firstUserIdTest = res.body._id;
});it(`should POST to /auth and retrieve an access token`, async () => {
const res = await request(app)
.post('/auth').send({
"email" : firstUserBody.email,
"password" : firstUserBody.password
});
expect(res.status).to.equal(201);
expect(res.body).not.to.be.empty;
expect(res.body).to.be.an("object");
expect(res.body.accessToken).to.be.an("string");
expect(res.body.refreshToken).to.be.an("string");
jwt.accessToken = res.body.accessToken;
jwt.refreshToken = res.body.refreshToken;
});it(`should GET /users/:userId`, async function () {
console.log(`Bearer ${jwt.accessToken}`);
const res = await request(app)
.get(`/users/${firstUserIdTest}`)
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send();
expect(res.status).to.equal(200);
expect(res.body).not.to.be.empty;
expect(res.body).to.be.an("object");expect(res.body._id).to.be.an('string');
expect(res.body.name).to.be.equals(firstUserBody.name);
expect(res.body.email).to.be.equals(firstUserBody.email);
expect(res.body.permissionLevel).to.be.equals(15);
expect(res.body._id).to.be.equals(firstUserIdTest);
});it(`should GET /users`, async function () {
const res = await request(app)
.get(`/users`)
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${adminJWT}`)
.send();
expect(res.status).to.equal(200);
expect(res.body).not.to.be.empty;
expect(res.body).to.be.an("array");expect(res.body[0]._id).to.be.an('string');
expect(res.body[0].name).to.be.equals(firstUserBody.name);
expect(res.body[0].email).to.be.equals(firstUserBody.email);
expect(res.body[0]._id).to.be.equals(firstUserIdTest);
});it('should PUT /users/:userId', async function () {
const name = 'Jose';
const res = await request(app)
.put(`/users/${firstUserIdTest}`)
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send({
name: name,
email: firstUserBody.email
});
expect(res.status).to.equal(204);
});it(`should GET /users/:userId to have a new name`, async function () {
const res = await request(app)
.get(`/users/${firstUserIdTest}`)
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send();
expect(res.status).to.equal(200);
expect(res.body).not.to.be.empty;
expect(res.body).to.be.an("object");expect(res.body._id).to.be.an('string');
expect(res.body.name).to.be.not.equals(firstUserBody.name);
expect(res.body.email).to.be.equals(firstUserBody.email);
expect(res.body._id).to.be.equals(firstUserIdTest);
});it('should PATCH /users/:userId', async function () {
let newField = {description: 'My user description'};
const res = await request(app)
.patch(`/users/${firstUserIdTest}`)
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send(newField);
expect(res.status).to.equal(204);
});it(`should GET /users/:userId to have a new field called description`, async function () {
const res = await request(app)
.get(`/users/${firstUserIdTest}`)
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send();
expect(res.status).to.equal(200);
expect(res.body).not.to.be.empty;
expect(res.body).to.be.an("object");
expect(res.body._id).to.be.an('string');
expect(res.body.description).to.be.equals('My user description');
});it('should DELETE /users/:userId', async function () {
const res = await request(app)
.delete(`/users/${firstUserIdTest}`)
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send();
expect(res.status).to.equal(204);
});it(`should GET /users and receive a 403 for not being an ADMIN`, async function () {
const res = await request(app)
.get(`/users`)
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send();
expect(res.status).to.equal(403);
});/test/auth/auth.test.ts
import app from '../../app/app';
import {agent as request} from 'supertest';
import {expect} from 'chai';
import * as shortUUId from 'short-uuid';let firstUserIdTest = '';
let firstUserBody = {
"name": "Marcos SIlva",
"email": `tio.makin+auth${shortUUId.generate()}@gmail.com`,
"password": "Pass#your!word"
};let jwt = {
accessToken: '',
refreshToken: ''
};it('should POST /users', async function () {
const res = await request(app)
.post('/users').send(firstUserBody);
expect(res.status).to.equal(201);
expect(res.body).not.to.be.empty;
expect(res.body).to.be.an("object");
expect(res.body._id).to.be.an('string');
firstUserIdTest = res.body._id;
});it(`should POST to /auth and retrieve an access token`, async () => {
const res = await request(app)
.post('/auth').send({
"email" : firstUserBody.email,
"password" : firstUserBody.password
});
expect(res.status).to.equal(201);
expect(res.body).not.to.be.empty;
expect(res.body).to.be.an("object");
expect(res.body.accessToken).to.be.an("string");
expect(res.body.refreshToken).to.be.an("string");
jwt.accessToken = res.body.accessToken;
jwt.refreshToken = res.body.refreshToken;
});it(`should POST to /auth/refresh-token and receive 403 for having an invalid JWT`, async () => {
const res = await request(app)
.post('/auth/refresh-token')
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}123123`)
.send({
"refreshToken" : jwt.refreshToken
});
expect(res.status).to.equal(403);
});it(`should POST to /auth/refresh-token and receive 401 for not having a JWT set`, async () => {
const res = await request(app)
.post('/auth/refresh-token')
.set('Accept', 'application/json')
.send({
"refreshToken" : jwt.refreshToken
});
expect(res.status).to.equal(401);
});it(`should POST to /auth/refresh-token and receive 400 for having an invalid refreshToken`, async () => {
const res = await request(app)
.post('/auth/refresh-token')
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send({
"refreshToken" : '123'
});
expect(res.status).to.equal(400);
});it(`should POST to /auth/refresh-token and retrieve a new access token`, async () => {
const res = await request(app)
.post('/auth/refresh-token')
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send({
"refreshToken" : jwt.refreshToken
});
expect(res.status).to.equal(201);
expect(res.body).not.to.be.empty;
expect(res.body).to.be.an("object");
expect(res.body.accessToken).to.be.an("string");
expect(res.body.refreshToken).to.be.an("string");
jwt.accessToken = res.body.accessToken;
jwt.refreshToken = res.body.refreshToken;
});it('should DELETE /users/:userId', async function () {
const res = await request(app)
.delete(`/users/${firstUserIdTest}`)
.set('Accept', 'application/json')
.set('Authorization', `Bearer ${jwt.accessToken}`)
.send();
expect(res.status).to.equal(204);
});And that’s it, we just need to run our app now with npm run dev and see the updated tests and JWT working. You can try to modify the tests now to not use the JWT or to generate a wrong one and try… then you will start to see the errors!
In this article we created and configured a Permission module that works together with our pre-created Auth module. We focused on the code and to make it run and work but remember to read about our bitwise AND approach to understand why we used it.
Thanks for reading and see you at the next article!
tips:
- the full code of this article is here
- don’t forget to use a nice app to test your API such as Postman or Insomnia
- I know you still didn’t… Read the ExpressJS documentation!
- Learn Docker, start at their Documentation!
- Learn Mongoose, start also at their Documentation!
- Complete project is here! (Includes even the non existing articles yet)