Implementing JWT-Based Authentication in NodeJS: Access and Refresh Tokens

In modern web applications, authentication plays a crucial role in securing user data and managing user sessions. One of the most popular techniques for implementing secure authentication is by using JWT-based (JSON Web Token) authentication. In this guide, we'll focus on implementing authentication using Access Tokens and Refresh Tokens in NodeJS.

Why JWT?

JWTs are stateless tokens that are digitally signed and provide a secure way to verify user identity without needing to store session data on the server. This makes JWT-based authentication lightweight, scalable, and a great fit for distributed systems like REST APIs and microservices.

Access Tokens vs. Refresh Tokens

Access Tokens: Short-lived tokens (usually valid for 15 minutes to a few hours) used to authenticate API requests. Once they expire, the user cannot make requests until a new access token is obtained.
Refresh Tokens: Long-lived tokens (usually valid for days or weeks) used to generate new access tokens. They provide a way to maintain a user session without needing to log in again after the access token expires.

Step-by-Step: JWT Access and Refresh Token Flow

1. User Login and Generating Tokens

During the login process, after the user provides valid credentials (like username and password), we issue both an access token and a refresh token.

Here’s an example of how to generate and send both tokens after successful login:

typescript

export const loginUser = async (req: Request, res: Response) => {
  try {
    const { login_id, password } = req.body;

    // Find the user by email or username
    const user = await UserModel.findOne({
      $or: [{ email_address: login_id }, { username: login_id }],
    });

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

    // Verify password
    const passwordMatch = await bcrypt.compare(password, user.password);
    if (!passwordMatch) {
      return res.status(401).json({ error: "Invalid password" });
    }

    // Token payload with user information
    const tokenDetails = {
      userId: user._id,
      username: user.username,
      user_role: user.user_role,
    };

    // Generate access token (valid for 1 day)
    const accessToken = jwt.sign(tokenDetails, process.env.SECRET_KEY || "", {
      expiresIn: "1d",
    });

    // Generate refresh token (valid for 7 days)
    const refreshToken = jwt.sign(
      tokenDetails,
      process.env.REFRESH_SECRET_KEY || "",
      { expiresIn: "7d" }
    );

    // Send tokens in response (or cookies)
    res.cookie("accessToken", accessToken, {
      secure: true,
      httpOnly: true,
      sameSite: "none",
    });
    res.cookie("refreshToken", refreshToken, {
      secure: true,
      httpOnly: true,
      sameSite: "none",
    });

    res.status(200).json({ message: "Login successful", accessToken, refreshToken });
  } catch (error) {
    console.error("Error during login:", error);
    res.status(500).json({ error: "Internal server error" });
  }
};

↕ click to expand

In this code: After successfully verifying the user’s credentials, we generate an Access Token that expires in 1 day and a Refresh Token that expires in 7 days.

Both tokens are sent back in HTTP-only cookies for security or can be included in the response for mobile applications.

2. Refreshing Access Tokens

Once the access token expires, we don't want to force users to log in again. Instead, the refresh token is used to issue a new access token.

Here’s how we handle that:

typescript

export const refreshToken = (req: Request, res: Response) => {
  try {
    // Get refresh token from cookies or headers
    const refreshToken = req.cookies.refreshToken || req.headers["refresh-token"];

    if (!refreshToken) {
      return res.status(400).json({ error: "Refresh token not provided" });
    }

    // Verify refresh token
    jwt.verify(
      refreshToken,
      process.env.REFRESH_SECRET_KEY || "",
      (err: any, decoded: any) => {
        if (err) {
          return res.status(403).json({ error: "Invalid refresh token" });
        }

        // Generate new access token
        const accessToken = jwt.sign(
          { userId: decoded.userId, username: decoded.username },
          process.env.SECRET_KEY || "",
          { expiresIn: "15m" } // Shorter lifespan (15 mins)
        );

        // Send the new access token in cookies or headers
        res.cookie("accessToken", accessToken, {
          secure: true,
          httpOnly: true,
          sameSite: "none",
        });
        res.status(200).json({ message: "Access token refreshed successfully" });
      }
    );
  } catch (error) {
    console.error("Error refreshing access token:", error);
    res.status(500).json({ error: "Internal server error" });
  }
};

↕ click to expand

In this refresh token flow:

The user sends their refresh token via cookies or headers.
The server verifies the refresh token. If valid, it generates a new access token (with a shorter lifespan, like 15 minutes).
The new access token is sent to the user in an HTTP-only cookie or JSON response.

3. Token Expiry and Security Considerations

Access Token Lifespan: Typically, access tokens should have short lifespans (e.g., 15 minutes to 1 day) to minimize the impact of token theft.
Refresh Token Lifespan: Refresh tokens have longer lifespans (e.g., 7 days or more), but they should be stored securely (preferably in HTTP-only cookies to avoid XSS attacks).
Token Blacklisting: In some applications, you might want to store refresh tokens in a database to handle logout or revoke refresh tokens if needed.

Conclusion

JWT-based authentication with access and refresh tokens allows for secure, scalable, and stateless user authentication in NodeJS. By issuing short-lived access tokens and long-lived refresh tokens, you can ensure user sessions remain secure while minimizing the need for frequent logins.