Authenticate and protect REST API routes with JWT and refersh token rotation

This content originally appeared on DEV Community and was authored by Tasnim Ferdous

Overview

After reading this article, you will able to

Authenticate users with their username/email and password
Understand the uses of accessToken and refreshToken
Protect api endpoints from unauthorized clients by validating accessToken
Allow multi-logins with ability to revoke all session
Have a template with signup,signin and endpoint protection to kickstart your next rest api

The code is available on github

I suggest to read the full article first and then start coding

The source code structure is as follows

.
├── controllers
│   ├── auth
│   │   ├── login.ts
│   │   ├── logout.ts
│   │   ├── refreshAccessToken.ts
│   │   └── register.js
│   └── users.ts
├── db # functions to make calls to the database
│   ├── connect.ts
│   ├── tokens.ts
│   └── users.ts
├── index.ts
├── middlewares
│   ├── validateRegistrationData.ts
│   └── verifyTokens.ts
├── routes
│   ├── auth.ts
│   ├── index.ts
│   └── users.ts
└── utils
    ├── genToken.ts
    ├── hashString.ts
    └── verifyToken.ts

Table of Contents

Database Schema
Overview of auth routes
Registration
Log In
Refresh Access Token
Access protected resource
Log Out
- Log out current session
- Log out from All devices
Testing the api
- Register
- Login
- Accessing protected endpoint
- Refresh Access Token

Database Schema

The database is using sqlite so you don't have to setup any database in your system
This project uses prisma ORM which will give you typescript support with excellent auto completion experience

prisma/schema.prisma:

model User {
    id            String         @id @default(uuid())
    email         String         @unique
    username      String         @unique
    password      String
    refreshTokens RefreshToken[]
}

model RefreshToken {
    id          String   @id
    hashedToken String
    user        User     @relation(fields: [userId], references: [id], onDelete: Cascade)
    userId      String
    createdAt   DateTime @default(now())
}

User and RefreshToken has one to many relationship
One user can have multiple refreshToken so that logins from multiple devices can be persisted
Run npx prisma generate to generate prisma client code. Then run npx prisma migrate dev to create necessary tables according to the schema
Tip : You can use npx prisma studio to interect with the database in a Web GUI

Overview of auth routes

routes/auth.ts:

const router = express.Router();

router.post("/auth/login", login);
router.post("/auth/register", validateRegistrationData, register);
router.get("/auth/refresh", verifyRefreshToken, refreshAccessToken);
router.delete("/auth/logout", logout);
router.delete("/auth/logout_all", logout_all);

export { router as authRouter };

All routes are prefixed with "/api"

Registration

Route : router.post("/auth/register", validateRegistrationData, register)

The request body should contain username, email and password
We will create a middleware to validate the registration data

middlewares/validateRegistrationData.ts:

export const validateRegistrationData = async (req, res, next) => {
  const { email, username, password } = req.body;

  if (!password) return res.status(400).json({ error: "No password provided" });

  if (!username) return res.status(400).json({ error: "No username provided" });

  if (!email) return res.status(400).json({ error: "No email provided" });

  let user = await findUserByUsernameOrEmail(username, email);
  if (user) {
    let error = "Email already exits";
    if (user.email !== email) error = "Username already exits";
    return res.json({ error });
  }

  req.user = {
    email,
    username,
    password,
  };

  next();
};

If an account with the same username or email already exists then return
Else attach the user object to req and go to the next function

controllers/auth/register.ts:

export const register = async (req, res) => {
  const user = await createUser(req.user);
  if (!user) return res.json({ error: "Registration Failed" });

  const data = {
    username: user.username,
    email: user.email,
  };

  res.json({ data });
};

Hash the password before storing to the database

const createUser = async (user: any) => {
  user.password = await hashString(user.password);

  return db.user.create({
    data: user,
  });
};

Log In

Route : router.post("/auth/login", login)

The request body should contain { username, password }
Here username field can contain email also, providing the option to log in with both username and email
Return an error if user doesn't exist or password is incorrect
Create accessToken and refreshToken
Send the refreshToken to be saved as a httpOnly cookie with 30 days validity
Send the accessToken

controllers/auth/login.ts:

export const login = async (req, res) => {
  try {
    if (!req.body.username)
      return res.status(400).json({ error: "No Username provided" });
    if (!req.body.password)
      return res.status(400).json({ error: "No Password provided" });

    const { username, password } = req.body;

    // User can log in with username or email
    const user = await findUserByUsernameOrEmail(username, username);

    if (!user) return res.status(404).json({ error: "User Not Found" });

    const match = await bcrypt.compare(password, user.password);

    if (!match) return res.status(401).json({ error: "Wrong Password" });

    const accessToken = genAccessToken(user);
    const tokenId = randomUUID();
    const refreshToken = genRefreshToken(user, tokenId);

    res.cookie("refreshToken", refreshToken, {
      httpOnly: true,
      maxAge: 24 * 60 * 60 * 30 * 1000, // 30 days
    });

    // add the token to the database
    addRefreshToken(tokenId, user.id, refreshToken);

    return res.json({ accessToken });
  } catch (error) {
    return res.status(500).json({ error: "Internal Error" });
  }
};

refreshToken is sensitive data, hence you shouldn't store it in plain text
You could either hash it or encrypt it

const addRefreshToken = async (
  id: string,
  userId: number,
  refreshToken: string
) => {
  const hashedToken = await hashString(refreshToken);
  return db.refreshToken.create({
    data: {
      id,
      userId,
      hashedToken,
    },
  });
};

Refresh Access Token

Route : router.get("/auth/refresh", verifyRefreshToken, refreshAccessToken)

If the token is expired or tampered with then the verification will fail
If the verification passes but the token doesn't exist in the db, then you can suspect that someone is trying to use an old token that might be stolen so you return Unauthorized
Otherwise, delete the refreshToken that was in the cookie of the request, create new token, save it to the database and send set it as a httpOnly cookie, this practice is called refresh token rotation
Send the accessToken

export const refreshAccessToken = async (req, res) => {
  const user = req.user;
  const newTokenId = randomUUID();
  const newRefreshToken = genRefreshToken(user, newTokenId);

  res.cookie("refreshToken", newRefreshToken, {
    httpOnly: true,
    maxAge: 24 * 60 * 60 * 1000 * 30,
  });

  // refresh token rotation
  deleteRefreshTokenById(user.jwtid);
  addRefreshToken(newTokenId, user.id, newRefreshToken);
  //

  const accessToken = genAccessToken(user);
  return res.json({ accessToken });
};

Access protected resource

As an example, /users can be used as a protected endpoint

Route : router.use("/users", verifyAccessToken, listUsers)

middlewares/verifyAccessToken.ts:

export const verifyAccessToken = (req, res, next) => {
  const authHeader = req.headers["authorization"];
  const token = authHeader && authHeader.split(" ")[1];
  if (token == null) return res.sendStatus(401);
  const user = tokenVerifier.validateAccessToken(token);
  if (user.tokenError)
    return res.status(401).json({
      error: "Invalid Access token",
      tokenError: user.tokenError,
    });

  req.user = user;
  return next();
};

The client has to send the token in the authorization header following the format Bearer $token
If the token is not valid, the error will be returned (such as TokenExpiredError or JsonWebTokenError if the token is modified)
Otherwise the server will query the database and send the list of users to the client

Log Out

Route : router.delete("/auth/logout", logout)

Log out current session

export const logout = async (req, res) => {
  const refreshToken = req.cookies.refreshToken;
  if (!refreshToken) return res.status(401).json({ error: "No Refresh Token" });

  // does not check if it exists in the db
  const user = tokenVerifier.verifyRefreshToken(refreshToken);

  if (user.tokenError)
    return res.status(401).json({
      error: "Invalid Refresh token",
      tokenError: user.tokenError,
    });

  res.clearCookie("refreshToken");
  deleteRefreshTokenById(user.jwtid);
  return res.sendStatus(200);
};

Log out from All devices

Route : router.delete("/auth/logout", logout_all)

export const logout_all = async (req, res) => {
  const refreshToken = req.cookies.refreshToken;
  if (!refreshToken) return res.status(401).json({ error: "No Refresh Token" });

  res.clearCookie("refreshToken");

  // does not check if it exists in the db
  const user = tokenVerifier.verifyRefreshToken(refreshToken);

  if (user.tokenError)
    return res.status(401).json({
      error: "Invalid Refresh token",
      tokenError: user.tokenError,
    });

  // delete all tokens associated with this user
  deleteAllRefreshTokens(user.id);
  return res.sendStatus(200);
};

Notice 2 things,

There's no check to see if the token exists in db
Access token verification is skipped

Lets consider a scenario where the client's cookie is hijacked, so attacker has the refreshToken

Now he is going to use that refreshToken to get new accessToken
Which will invalidate the refreshToken of the client from which it was hijacked
That client may be the legitimate user
And now that client can't get any new accessToken
So if accesToken verification or the check to see if token exists was in db was present then that client wouldn't be able to logout

Testing the api

You can use curl to perform all the requests
All the commands listed below is written on tests/api-test-curl.sh

If you use Insomnia, which is an awesome open source api testing tool, you can import all the requests from tests/api-test-insomnia.json

Register

curl --request POST \
  --url http://localhost:5000/api/auth/register \
  --header 'Content-Type: application/json' \
  --data '{
    "username" : "gr523",
    "email" : "gr523@gmail.com",
    "password" : "Pass82G9"
}'

Login

curl --request POST \
  --url http://localhost:5000/api/auth/login \
  --header 'Content-Type: application/json' \
  --cookie-jar "cookie.txt" \
  --data '{
    "username" : "gr523",
    "password" : "Pass82G9"
}'

Output: {"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjNjY2Q2ZjNhLWQxMzItNDQzZi05NWM0LTRmMDJjYmU3ZDRlMSIsInVzZXJuYW1lIjoiZ3I1MjMiLCJlbWFpbCI6ImdyNTIzQGdtYWlsLmNvbSIsImlhdCI6MTY4MTkyOTYyNywiZXhwIjoxNjgxOTI5OTI3fQ.qbfKNvMk2W9JojB7O9CAtshOKoPQ1n2whLWrP4lzEJo"}

The cookie will be saved in cookie.txt
Copy the value of accessToken to your clipboard

Accessing protected endpoint

Paste the accessToken after Bearer

curl --request GET \
  --url http://localhost:5000/api/api/users \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjNjY2Q2ZjNhLWQxMzItNDQzZi05NWM0LTRmMDJjYmU3ZDRlMSIsInVzZXJuYW1lIjoiZ3I1MjMiLCJlbWFpbCI6ImdyNTIzQGdtYWlsLmNvbSIsImlhdCI6MTY4MTkyOTYyNywiZXhwIjoxNjgxOTI5OTI3fQ.qbfKNvMk2W9JojB7O9CAtshOKoPQ1n2whLWrP4lzEJo'

Output: {"users":[{"id":"3ccd6f3a-d132-443f-95c4-4f02cbe7d4e1","username":"gr523","email":"gr523@gmail.com"}]}

Modify the value of the accessToken

curl --request GET \
  --url http://localhost:5000/api/api/users \
  --header 'Authorization: Bearer xxxxxxxxxxxxxxxxNiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjNjY2Q2ZjNhLWQxMzItNDQzZi05NWM0LTRmMDJjYmU3ZDRlMSIsInVzZXJuYW1lIjoiZ3I1MjMiLCJlbWFpbCI6ImdyNTIzQGdtYWlsLmNvbSIsImlhdCI6MTY4MTkyOTYyNywiZXhwIjoxNjgxOTI5OTI3fQ.qbfKNvMk2W9JojB7O9CAtshOKoPQ1n2whLWrP4lzEJo'

Output {"error":"Invalid Access token","tokenError":"JsonWebTokenError"}

The validity duration of the accessToken is set to 5 minutes, after that you can't use that token to access protected resources

The response will be {"error":"Invalid Access token","tokenError":"TokenExpiredError"}

You can change the validity duration in utils/genToken.ts

Refresh Access Token

Use the value of refreshToken from cookie.txt

curl --request GET \
  --url http://localhost:5000/api/auth/refresh \
  --cookie refreshToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqd3RpZCI6IjQwY2VkYmRjLWM2NmQtNGJlYy1hNjc4LTg0MWJkZDhlMTBkMyIsImlkIjoiM2NjZDZmM2EtZDEzMi00NDNmLTk1YzQtNGYwMmNiZTdkNGUxIiwidXNlcm5hbWUiOiJncjUyMyIsImVtYWlsIjoiZ3I1MjNAZ21haWwuY29tIiwiaWF0IjoxNjgxOTI4MzgwLCJleHAiOjE2ODQ1MjAzODB9.WDk-YbqxX7_yCr8ATbDxbCV-W6EUNzxZPchPaHnuZAI

Or in linux you can use sed,

curl --request GET \
  --url http://localhost:5000/api/auth/refresh \
  --cookie refreshToken="$(sed -En '/refreshToken/s/.*refreshToken\s*(.*)/\1/p' cookie.txt)"

You have read up to this point, you are ready to take kickstart your next rest-api project. Would appreciate any feedback. Tell me, if you like this style of tutorial or what could be changed to make it better

This content originally appeared on DEV Community and was authored by Tasnim Ferdous

Print Share Comment Cite Upload Translate Updates

APA

Tasnim Ferdous | Sciencx (2023-04-19T20:17:59+00:00) Authenticate and protect REST API routes with JWT and refersh token rotation. Retrieved from https://www.scien.cx/2023/04/19/authenticate-and-protect-rest-api-routes-with-jwt-and-refersh-token-rotation/

MLA

" » Authenticate and protect REST API routes with JWT and refersh token rotation." Tasnim Ferdous | Sciencx - Wednesday April 19, 2023, https://www.scien.cx/2023/04/19/authenticate-and-protect-rest-api-routes-with-jwt-and-refersh-token-rotation/

HARVARD

Tasnim Ferdous | Sciencx Wednesday April 19, 2023 » Authenticate and protect REST API routes with JWT and refersh token rotation., viewed ,<https://www.scien.cx/2023/04/19/authenticate-and-protect-rest-api-routes-with-jwt-and-refersh-token-rotation/>

VANCOUVER

Tasnim Ferdous | Sciencx - » Authenticate and protect REST API routes with JWT and refersh token rotation. [Internet]. [Accessed ]. Available from: https://www.scien.cx/2023/04/19/authenticate-and-protect-rest-api-routes-with-jwt-and-refersh-token-rotation/

CHICAGO

" » Authenticate and protect REST API routes with JWT and refersh token rotation." Tasnim Ferdous | Sciencx - Accessed . https://www.scien.cx/2023/04/19/authenticate-and-protect-rest-api-routes-with-jwt-and-refersh-token-rotation/

IEEE

" » Authenticate and protect REST API routes with JWT and refersh token rotation." Tasnim Ferdous | Sciencx [Online]. Available: https://www.scien.cx/2023/04/19/authenticate-and-protect-rest-api-routes-with-jwt-and-refersh-token-rotation/. [Accessed: ]

rf:citation

» Authenticate and protect REST API routes with JWT and refersh token rotation | Tasnim Ferdous | Sciencx | https://www.scien.cx/2023/04/19/authenticate-and-protect-rest-api-routes-with-jwt-and-refersh-token-rotation/ |

Please log in to upload a file.

There are no updates yet.
Click the Upload button above to add an update.

You must be logged in to translate posts. Please log in or register.

Overview

Database Schema

Overview of auth routes

Registration

Log In

Refresh Access Token

Access protected resource

Log Out

Log out current session

Log out from All devices

Testing the api

Register

Login

Accessing protected endpoint

Refresh Access Token

Related Posts