After long research, I finally got an implementation of an authentication workflow that I like. I think I researched this topic for more than a year (not extensively of course, but when I was seeing articles about auth, I would always save and read them). Please note that I don't think this implementation is perfect, but, for my use cases, it will work perfectly.
Part 1: Workflow
We are going to implement the following endpoints:
For /auth/login and /auth/register, the client needs to provide a user and a password in exchange for a pair of tokens ( access token and refresh token ).
With the access token, a request can be made to /users/profile. Here, the following workflow will be applied.
Note: We only check if the token is valid. This way, we keep our workflow stateless. Because of that, the access token should expire fast ( 5/10 minutes ).
In order to keep the user logged in, the client needs to make a request to /auth/refreshToken containing the refreshToken received on register/login.
Based on that token, on the server we will make some checks and provide a new pair of tokens. The process is explained in the following diagram.
Now, let's move to the coding part.
Part 2 Code
The code for this implementation can be found here ( I usually just store the tokens in local storage. Just make sure your frontend logic is safe against XSS attacks). Also, if you want to send the refresh token by HTTP Only Cookie, you can check this branch.
Step 1: Create the app
When I write javascript code on the backend, I prefer to use a boilerplate made by Coding Garden.
In order to use CJ's boilerplate, we can run the following code from the terminal.
npx create-express-api auth-server
cd auth-server
npm install
npm run dev
Now, you can test your server with a GET request on http://localhost:5000/api/v1/.
Step 2: Install dependencies and setup env variables
npm install -dev prisma
npm install @prisma/client bcrypt jsonwebtoken uuid
npx prisma init --datasource-provider sqlite
Add the following inside .env.
JWT_ACCESS_SECRET=SECRET123
JWT_REFRESH_SECRET=ANOTHER_SECRET123
Step 3: Prisma setup
Inside prisma/schema.prisma, we will define our database model. Paste the following.
model User {
id String @id @unique @default(uuid())
email String @unique
password String
refreshTokens RefreshToken[]
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
model RefreshToken {
id String @id @unique @default(uuid())
hashedToken String
userId String
User User @relation(fields: [userId], references: [id], onDelete: Cascade)
revoked Boolean @default(false)
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
}
And run npx prisma migrate dev in the console.
Now, we have everything ready for writing our authentication logic.
We are going to use 2 tables. The user table is self-explanatory. The refresh token table is going to be used as a Whitelist for the tokens that we generate as explained in part 1.
Step 4: Add utility functions.
Create a folder called utils inside src. Here, we will add the following files:
- db.js - used for database interaction with prisma.
const { PrismaClient } = require('@prisma/client');
const db = new PrismaClient();
module.exports = { db };
- jwt.js - used for token generation.
const jwt = require('jsonwebtoken');
// Usually I keep the token between 5 minutes - 15 minutes
function generateAccessToken(user) {
return jwt.sign({ userId: user.id }, process.env.JWT_ACCESS_SECRET, {
expiresIn: '5m',
});
}
// I choosed 8h because i prefer to make the user login again each day.
// But keep him logged in if he is using the app.
// You can change this value depending on your app logic.
// I would go for a maximum of 7 days, and make him login again after 7 days of inactivity.
function generateRefreshToken(user, jti) {
return jwt.sign({
userId: user.id,
jti
}, process.env.JWT_REFRESH_SECRET, {
expiresIn: '8h',
});
}
function generateTokens(user, jti) {
const accessToken = generateAccessToken(user);
const refreshToken = generateRefreshToken(user, jti);
return {
accessToken,
refreshToken,
};
}
module.exports = {
generateAccessToken,
generateRefreshToken,
generateTokens
};
- hashToken.js - used to hash the token before saving it to the database.
const crypto = require('crypto');
function hashToken(token) {
return crypto.createHash('sha512').update(token).digest('hex');
}
module.exports = { hashToken };
Step 5: Project structure
Delete the emojis.js from src/api and cleanup api/index.js by removing emojis route.
Create 2 folders: auth and users inside src/api. In each folder, we will create 2 files for routes and services.
┣ 📂src
┃ ┣ 📂api
┃ ┃ ┣ 📂auth
┃ ┃ ┃ ┣ 📜auth.routes.js
┃ ┃ ┃ ┗ 📜auth.services.js
┃ ┃ ┣ 📂users
┃ ┃ ┃ ┣ 📜users.routes.js
┃ ┃ ┃ ┗ 📜users.services.js
┃ ┃ ┗ 📜index.js
┃ ┣ 📂utils
┃ ┃ ┣ 📜db.js
┃ ┃ ┣ 📜hashToken.js
┃ ┃ ┣ 📜jwt.js
┃ ┃ ┗ 📜sendRefreshToken.js
Step 6: Services
Now, inside users.services.js paste the following code:
const bcrypt = require('bcrypt');
const { db } = require('../../utils/db');
function findUserByEmail(email) {
return db.user.findUnique({
where: {
email,
},
});
}
function createUserByEmailAndPassword(user) {
user.password = bcrypt.hashSync(user.password, 12);
return db.user.create({
data: user,
});
}
function findUserById(id) {
return db.user.findUnique({
where: {
id,
},
});
}
module.exports = {
findUserByEmail,
findUserById,
createUserByEmailAndPassword
};
Most of the code is self-explanatory, but as a summary, we define some helpers specific to the User table that we are going to use in the project.
Now, the code for auth.services.js.
const { db } = require('../../utils/db');
const { hashToken } = require('../../utils/hashToken');
// used when we create a refresh token.
function addRefreshTokenToWhitelist({ jti, refreshToken, userId }) {
return db.refreshToken.create({
data: {
id: jti,
hashedToken: hashToken(refreshToken),
userId
},
});
}
// used to check if the token sent by the client is in the database.
function findRefreshTokenById(id) {
return db.refreshToken.findUnique({
where: {
id,
},
});
}
// soft delete tokens after usage.
function deleteRefreshToken(id) {
return db.refreshToken.update({
where: {
id,
},
data: {
revoked: true
}
});
}
function revokeTokens(userId) {
return db.refreshToken.updateMany({
where: {
userId
},
data: {
revoked: true
}
});
}
module.exports = {
addRefreshTokenToWhitelist,
findRefreshTokenById,
deleteRefreshToken,
revokeTokens
};
Now, we have everything in place to write our routes.
Step 7: Auth Routes.
Let's make the /register endpoint. Inside auth.routes.js put the following code:
const express = require('express');
const { v4: uuidv4 } = require('uuid');
const { generateTokens } = require('../../utils/jwt');
const {
addRefreshTokenToWhitelist,
} = require('./auth.services');
// const jwt = require('jsonwebtoken');
const router = express.Router();
const {
findUserByEmail,
createUserByEmailAndPassword,
} = require('../users/users.services');
router.post('/register', async (req, res, next) => {
try {
const { email, password } = req.body;
if (!email || !password) {
res.status(400);
throw new Error('You must provide an email and a password.');
}
const existingUser = await findUserByEmail(email);
if (existingUser) {
res.status(400);
throw new Error('Email already in use.');
}
const user = await createUserByEmailAndPassword({ email, password });
const jti = uuidv4();
const { accessToken, refreshToken } = generateTokens(user, jti);
await addRefreshTokenToWhitelist({ jti, refreshToken, userId: user.id });
res.json({
accessToken,
refreshToken,
});
} catch (err) {
next(err);
}
});
module.exports = router;
Here, we take the email/password from the user. We make some basic validation ( you will need to add some validation steps here ( for example, use yup or joi ). We create the user, the tokens, and we add the refresh token to the whitelist ( check diagram 1 for the flow).
In order for the route to be recognised by our app, we need to add some code inside src/api/index.js:
const auth = require('./auth/auth.routes');
router.use('/auth', auth);
You can now test the endpoint by making a post request to http://localhost:5000/api/v1/auth/register. The response will be:
{
"accessToken": "generatedAccessToken...",
"refreshToken": "generatedRefreshToken..."
}
Let's move to the login endpoint. This one is very similar to the register one.
// add bcrypt at the top of the file.
const bcrypt = require('bcrypt');
router.post('/login', async (req, res, next) => {
try {
const { email, password } = req.body;
if (!email || !password) {
res.status(400);
throw new Error('You must provide an email and a password.');
}
const existingUser = await findUserByEmail(email);
if (!existingUser) {
res.status(403);
throw new Error('Invalid login credentials.');
}
const validPassword = await bcrypt.compare(password, existingUser.password);
if (!validPassword) {
res.status(403);
throw new Error('Invalid login credentials.');
}
const jti = uuidv4();
const { accessToken, refreshToken } = generateTokens(existingUser, jti);
await addRefreshTokenToWhitelist({ jti, refreshToken, userId: existingUser.id });
res.json({
accessToken,
refreshToken
});
} catch (err) {
next(err);
}
});
Now you can test the login endpoint by providing an existing user/password combination via a POST request to http://localhost:5000/api/v1/auth/login. If it is successful, you will get a response containing an access token and a refresh token.
Next, we will add the refresh_token endpoint and a test endpoint for revoking all tokens. Here is all the code for auth.routes.ts:
const express = require('express');
const bcrypt = require('bcrypt');
const jwt = require('jsonwebtoken');
const { v4: uuidv4 } = require('uuid');
const {
findUserByEmail,
createUserByEmailAndPassword,
findUserById
} = require('../users/users.services');
const { generateTokens } = require('../../utils/jwt');
const {
addRefreshTokenToWhitelist,
findRefreshTokenById,
deleteRefreshToken,
revokeTokens
} = require('./auth.services');
const { hashToken } = require('../../utils/hashToken');
const router = express.Router();
router.post('/register', async (req, res, next) => {
try {
const { email, password } = req.body;
if (!email || !password) {
res.status(400);
throw new Error('You must provide an email and a password.');
}
const existingUser = await findUserByEmail(email);
if (existingUser) {
res.status(400);
throw new Error('Email already in use.');
}
const user = await createUserByEmailAndPassword({ email, password });
const jti = uuidv4();
const { accessToken, refreshToken } = generateTokens(user, jti);
await addRefreshTokenToWhitelist({ jti, refreshToken, userId: user.id });
res.json({
accessToken,
refreshToken
});
} catch (err) {
next(err);
}
});
router.post('/login', async (req, res, next) => {
try {
const { email, password } = req.body;
if (!email || !password) {
res.status(400);
throw new Error('You must provide an email and a password.');
}
const existingUser = await findUserByEmail(email);
if (!existingUser) {
res.status(403);
throw new Error('Invalid login credentials.');
}
const validPassword = await bcrypt.compare(password, existingUser.password);
if (!validPassword) {
res.status(403);
throw new Error('Invalid login credentials.');
}
const jti = uuidv4();
const { accessToken, refreshToken } = generateTokens(existingUser, jti);
await addRefreshTokenToWhitelist({ jti, refreshToken, userId: existingUser.id });
res.json({
accessToken,
refreshToken
});
} catch (err) {
next(err);
}
});
router.post('/refreshToken', async (req, res, next) => {
try {
const { refreshToken } = req.body;
if (!refreshToken) {
res.status(400);
throw new Error('Missing refresh token.');
}
const payload = jwt.verify(refreshToken, process.env.JWT_REFRESH_SECRET);
const savedRefreshToken = await findRefreshTokenById(payload.jti);
if (!savedRefreshToken || savedRefreshToken.revoked === true) {
res.status(401);
throw new Error('Unauthorized');
}
const hashedToken = hashToken(refreshToken);
if (hashedToken !== savedRefreshToken.hashedToken) {
res.status(401);
throw new Error('Unauthorized');
}
const user = await findUserById(payload.userId);
if (!user) {
res.status(401);
throw new Error('Unauthorized');
}
await deleteRefreshToken(savedRefreshToken.id);
const jti = uuidv4();
const { accessToken, refreshToken: newRefreshToken } = generateTokens(user, jti);
await addRefreshTokenToWhitelist({ jti, refreshToken: newRefreshToken, userId: user.id });
res.json({
accessToken,
refreshToken: newRefreshToken
});
} catch (err) {
next(err);
}
});
// This endpoint is only for demo purpose.
// Move this logic where you need to revoke the tokens( for ex, on password reset)
router.post('/revokeRefreshTokens', async (req, res, next) => {
try {
const { userId } = req.body;
await revokeTokens(userId);
res.json({ message: `Tokens revoked for user with id #${userId}` });
} catch (err) {
next(err);
}
});
module.exports = router;
The /revokeRefreshTokens should not be exposed in the api. You should call the revokeTokens method only in a specific case where you would like to invalidate all the tokens ( ex: password reset ).
As for the refresh_token endpoint, it is used to get another pair of tokens, in order to keep the user logged. We check if the sent refresh token is valid and if it is in our database. If those conditions are met, we invalidate the previous refresh token and generate a new pair of tokens.
Step 8: Protected Routes.
First, in order to protect our routes, we need to define a middleware. Go to src/middlewares.js and add the following code:
function isAuthenticated(req, res, next) {
const { authorization } = req.headers;
if (!authorization) {
res.status(401);
throw new Error('🚫 Un-Authorized 🚫');
}
try {
const token = authorization.split(' ')[1];
const payload = jwt.verify(token, process.env.JWT_ACCESS_SECRET);
req.payload = payload;
} catch (err) {
res.status(401);
if (err.name === 'TokenExpiredError') {
throw new Error(err.name);
}
throw new Error('🚫 Un-Authorized 🚫');
}
return next();
}
module.exports = {
// ... other modules
isAuthenticated
}
We check if the client sends an Authorization header. The format should be: Bearer token. If the token is present, we verify it with our secret and add it to the request so it can be accessed in the routes.
NOTE: We only check if the token is valid. This way, we keep our workflow stateless.
Question: What happens if the user is deleted or the refresh tokens are invalidated?
Answer: The user will still have access until the access token expire. This will be for a maximum of 5 minutes ( that's why our access tokens expire fast). In my opinion, this will suit most of the apps ( Of course, if you develop a banking app, it might not work. But for most of the apps, it will be alright. For example, imagine you build an app that has some free and premium content. The user pays you for 30 days of premium content. After 30 days, you will decrease his access, but if he already had a token, he will still be able to access the content for 5 more minutes. Will be worth it to check the database on each call for each user inside our middleware? In my opinion, not. But as I said, depends on your use case.
Now, let's write the protected route. Go to src/api/users/users.routes.js and add the following code:
const express = require('express');
const { isAuthenticated } = require('../../middlewares');
const { findUserById } = require('./users.services');
const router = express.Router();
router.get('/profile', isAuthenticated, async (req, res, next) => {
try {
const { userId } = req.payload;
const user = await findUserById(userId);
delete user.password;
res.json(user);
} catch (err) {
next(err);
}
});
module.exports = router;
And inside src/api/index.js:
const users = require('./users/users.routes');
router.use('/users', users);
Now, you can make a GET request to http://localhost:5000/api/v1/users/profile. You will need to add an Authorization header with the access token that you got from the /login endpoint.
And that's it.🎉🎉🎉
If you have any questions, feel free to reach up in the comments section.
For the frontend part, you can check this blog post.
Top comments (30)
It might be a silly question, but why do we need a refresh token? Since the client can easily have access to the refresh token and use it to get an access token, why don't we just extend the access token to 8 hours or so and be done with it. I am new to this. So maybe I am missing something
Not a stupid question at all. You could use only an access token, But the problem is that in the middleware, you verify only if the access token is valid. You do not verify the user. So, in case a user might be deleted, if he keeps his access token, he will still get access to the app for a maximum of 8h ( in case you deleted him right after a new token was given ). If you keep the access token lifetime short (15 minutes), when a request to refresh token will be made, it will check again the user in the db, and based on that it will provide a new token or not. So, for ex, if you deleted the user, he will still have access for a maximum of 15 minutes. As a tldr, this depends on the purpose of your app. If you don’t mind a user getting access to your app for a longer time after you want to restrict it, you can just provide an access token. If there are still other questions, just ask and I will try to clarify😬
Aha yes, it makes sense now. :)
Ok, one more question for my understanding. Now, the access token has been sent by the client (a React app for example) and it was found to be expired. Who will initiate the request for a new token using the refresh token? will the user on the React app be requested to login again? This part confuses me. If the user will not be asked to login again (which I assume this is the case), how to make the experience smooth for the user so he will not know what's happening in the backend and keeps using the app while the refresh token is still alive?
You are right. He will not be asked to login again. There are multiple aproaches, but the one I use is usually with axios interceptors. The general flow is the following: You just make normal requests, and if the backend sends you an error that the access token is expired, you intercept that error and make a call to refreshToken in order to receive a new access + refresh token. If that call responds with 200, then you just continue making calls with the new token. Otherwise, if the refresh token request failed, it probably means also the refresh token is invalid, so you redirect the user to /login again.
I will try to make a blog post on the frontend part for this blog, but probably next week. Do you prefer any framework?
You are amazing man :)
Well, my app is using Node, Express and Prisma for backend .. and React for the frontend. Axios is something I use also for sending API requests from my React app. Honestly, I have never used or knew about "Interceptors". Would be great if you have a blog post which adds to this one so we can learn the follow end-to-end 😬
Done. You can check it now :D
Just perfect, I loved this implementation!! Applied it to my project
Awesome! What are you building? 💙
A simple CRUD just to study
Absolutely lovin' it
Glad you liked it😬
Great articles, thank you for sharing!
Great article, well done 👏👏
Thanks for this, Totally inspired .
But I'm having a problem with the typescript version (from your repo), the server is not running I'm getting "Property 'user' does not exist on type 'Request>"
from the middleware.ts file on the requireUser function, looks like user is not present on the request.
I've tried to created .d.ts
`import { z } from "zod";
export { };
declare global {
namespace Express {
interface Request {
user: z.AnyZodObject; // 👈️ turn off type checking
}
}
}`
but still, no luck, app crashed
How would do to get passed this, as I real like your approach. Thanks
github.com/mihaiandrei97/authentic...
Here is an example
Thanks for the reply (a quick one) :),
But I do still have trouble,
line 67 & 77 in middlewares.ts
req.user = payload
{ const user = req.user }
the error is "
TSError: ⨯ Unable to compile TypeScript:
src/middlewares.ts:67:9 - error TS2339: Property 'user' does not exist on type 'Request>'.
67 req.user = payload
~~~~
src/middlewares.ts:77:22 - error TS2339: Property 'user' does not exist on type 'Request>'.
github.com/mihaiandrei97/authentic...
You also need to have this in tsconfig:
"typeRoots": ["./typings"],
My tscofig.json
"baseUrl": "src","paths": {
"@/config/*": ["config/*"],
"@/utils/*": ["utils/*"],
"@/assets/*": ["assets/*"]
},
// "typeRoots": ["./typings", "./node_modules/@types"],
"typeRoots": ["./typings"],
"types": ["express", "@types/jest"],
"resolveJsonModule": true,
I even changed the file structure to honor the tsconfig, restarted the TS server (on VSCode) but n luck,. Looks like req.user is of type Any not of ParsedToken! Every where the req.user is of type Any, that's why I can't even assign req.user to payload.
I don't know what I'm missing or doing wrong
Can you explain the
delete user.password;in '/profile'?Also, it would be nice look this code in TypeScript.
Hello! That is in order to not return the password in the response. Here you can find the typescript equivalent: github.com/mihaiandrei97/authentic...
Oh thanks a lot! I'm gonna check your repo for future references. Keep going!
Do you have a plan to move this into Typescript?
You have an example on how to do it in TypeScript here:
github.com/mihaiandrei97/authentic...
thanks
how do we handle logout logic
You just delete the tokens from the frontend (ex: from localstorage )
thanks very much. I have one more question. Whenever I throw new Error() , my server crash. How do we prevent it?
github.com/mihaiandrei97/express-p...
You need to have the errorHandler defined and imported in the main file as middleware
On the middlewares.js you are using "payload" as property or method with "req" but I can't access to it. How can I use it? Am I missing something?
You need to use the IsAuthenticated middleware on a controller in order to have access to a payload inside controllers