Post Date: September 21, 2024
Last Updated: November 02, 2026<\/p>\n\n\n\n
Authentication and security are crucial for maintaining user privacy and application integrity. One popular method of managing authentication in web applications is JSON Web Token (JWT).<\/p>\n\n\n\n
JWT authentication allows applications to securely exchange information between clients and servers. By implementing access tokens and refresh tokens, developers can manage user sessions while reducing the security risks associated with long-lived authentication tokens.<\/p>\n\n\n\n
In this tutorial, we will learn how to implement JWT authentication with access and refresh tokens in Node.js<\/strong> using the A JSON Web Token (JWT) is a compact, URL-safe token that carries information between two parties, usually a client and a server.<\/p>\n\n\n\n A JWT consists of three parts:<\/p>\n\n\n\n 1. Header<\/strong><\/p>\n\n\n\n The header contains metadata about the token, such as the token type (JWT) and the signing algorithm used (for example, HS256).<\/p>\n\n\n\n 2. Payload<\/strong><\/p>\n\n\n\n The payload contains claims or information about the user, such as the user ID, username, and other relevant details.<\/p>\n\n\n\n 3. Signature<\/strong><\/p>\n\n\n\n The signature is generated using the encoded header, payload, and a secret key. The server uses it to verify that the token has not been modified.<\/p>\n\n\n\n A JWT is signed, not automatically encrypted. Therefore, sensitive information such as passwords or confidential personal data should never be included in its payload.<\/p>\n\n\n\n When a user successfully logs in to an application, the server generates two tokens.<\/p>\n\n\n\n Access Token<\/strong><\/p>\n\n\n\n Refresh Token<\/strong><\/p>\n\n\n\n Access tokens have a short expiration time to reduce the impact of token theft. Refresh tokens allow users to obtain new access tokens without repeatedly entering their login credentials.<\/p>\n\n\n\n For example, when an access token expires, the client sends a request to the refresh-token endpoint. The server validates the refresh token and generates a new access token if the refresh token is still valid.<\/p>\n\n\n\n Before implementing JWT authentication in Node.js, make sure you have:<\/p>\n\n\n\n First, install the required packages for JWT authentication and Express.js.<\/p>\n\n\n\n The packages are used for the following purposes:<\/p>\n\n\n\n Create a Use strong, randomly generated secrets in production. Keep the When a user successfully logs in, the application generates two JWT tokens.<\/p>\n\n\n\n The access token is configured to expire after one minute for demonstration purposes, while the refresh token expires after 30 days.<\/p>\n\n\n\n Explanation:<\/strong><\/p>\n\n\n\n The refresh token contains the user ID, which will be used to identify the user when generating a new access token.<\/p>\n\n\n\n After successful login, return the access token in the response and store the refresh token in a secure HTTP-only cookie.<\/p>\n\n\n\n The refresh token should not be exposed to client-side JavaScript. An HTTP-only cookie helps prevent JavaScript from reading the refresh token during an XSS attack.<\/p>\n\n\n\n The following example shows how to send the tokens after successful user authentication.<\/p>\n\n\n\n Call The cookie settings provide the following protections:<\/p>\n\n\n\n If your frontend and backend are hosted on different sites, you may need to configure To protect API routes, create middleware that verifies the access token sent through the Authorization header.<\/p>\n\n\n\n The client should include the access token in the following format:<\/p>\n\n\n\n The middleware checks whether the token exists and verifies its signature and expiration.<\/p>\n\n\n\n Explanation:<\/strong><\/p>\n\n\n\n When the access token expires, the client can request a new access token using the refresh token stored in the HTTP-only cookie.<\/p>\n\n\n\n Create a refresh-token handler to verify the refresh token and generate a new access token.<\/p>\n\n\n\n Explanation:<\/strong><\/p>\n\n\n\n The refresh token remains in the cookie until it expires or is cleared. For production applications, implement refresh-token rotation and server-side revocation to prevent the continued use of compromised refresh tokens.<\/p>\n\n\n\n Now, configure the Express application to use the authentication middleware and refresh-token handler.<\/p>\n\n\n\n The refresh endpoint must be accessible without an access token because its purpose is to obtain a new access token.<\/p>\n\n\n\n Explanation:<\/strong><\/p>\n\n\n\n If you are using GraphQL, authentication can also be implemented through the GraphQL context so that protected resolvers receive the authenticated user information. Public login and token-refresh operations should be handled explicitly rather than bypassing authentication through simple request-body string matching.<\/p>\n\n\n\n A refresh token can remain valid until its expiration time unless the application implements a revocation mechanism.<\/p>\n\n\n\n For production applications, consider storing refresh-token records or token identifiers in a database. When a user logs out, revoke the corresponding refresh token and clear the cookie.<\/p>\n\n\n\n The following example clears the refresh-token cookie during logout:<\/p>\n\n\n\n Clearing the cookie removes it from the browser, but it does not invalidate a copied JWT. For complete revocation, the server must also invalidate the refresh-token record or token identifier stored in the database.<\/p>\n\n\n\n When implementing JWT authentication with access and refresh tokens, consider the following security practices:<\/p>\n\n\n\n 1. Refresh Token Storage<\/strong><\/p>\n\n\n\n Store refresh tokens in HTTP-only, Secure cookies. Configure appropriate SameSite and CSRF protections based on your application architecture.<\/p>\n\n\n\n 2. Short-Lived Access Tokens<\/strong><\/p>\n\n\n\n Use short expiration periods for access tokens to reduce the impact of token theft.<\/p>\n\n\n\n 3. Separate Secret Keys<\/strong><\/p>\n\n\n\n Use separate, strong secret keys for access tokens and refresh tokens. Store them securely as environment variables.<\/p>\n\n\n\n JWT authentication with access and refresh tokens is an effective approach to managing authentication in Node.js applications.<\/p>\n\n\n\n In this tutorial, we explored the structure of JWTs, generating access and refresh tokens, implementing authentication middleware, refreshing expired access tokens, and handling token revocation.<\/p>\n\n\n\n By using short-lived access tokens, securely storing refresh tokens, and implementing proper token validation and revocation mechanisms, developers can build more secure authentication systems for their applications.<\/p>\n\n\n\n An access token is a short-lived token used to authenticate API requests. A refresh token has a longer lifetime and is used to generate new access tokens when the existing access token expires.<\/p>\n\n\n\n Refresh tokens should preferably be stored in HTTP-only, Secure cookies with appropriate SameSite and CSRF protections. This prevents client-side JavaScript from directly accessing the cookie.<\/p>\n\n\n\n When a refresh token expires, the server rejects the refresh request. The user must authenticate again by logging in to obtain new access and refresh tokens.<\/p>\n\n\n\n Looking for reliable Node.js development, application security, or authentication solutions?<\/p>\n\n\n\njsonwebtoken<\/code> package and Express.js. We will also explore token expiration, middleware authentication, and secure refresh-token storage.<\/p>\n\n\n\nWhat is a JWT?<\/h2>\n\n\n\n
Flow of JWT Authentication with Access and Refresh Tokens<\/h2>\n\n\n\n
\n
\n
Why Use Two Tokens?<\/h3>\n\n\n\n
Prerequisites<\/h2>\n\n\n\n
\n
Node.js Implementation<\/h2>\n\n\n\n
Step 1: Install the Required Packages<\/h3>\n\n\n\n
npm install express jsonwebtoken cookie-parser dotenv<\/pre>\n\n\n\n
\n
express<\/code> \u2013 Creates the Node.js application and handles HTTP requests.<\/li>\n\n\n\njsonwebtoken<\/code> \u2013 Generates and verifies JWT tokens.<\/li>\n\n\n\ncookie-parser<\/code> \u2013 Reads cookies from incoming requests.<\/li>\n\n\n\ndotenv<\/code> \u2013 Loads environment variables from a .env<\/code> file.<\/li>\n<\/ul>\n\n\n\nStep 2: Configure Environment Variables<\/h3>\n\n\n\n
.env<\/code> file in your project root directory and configure separate secret keys for access tokens and refresh tokens.<\/p>\n\n\n\nJWT_SECRET=your_access_token_secret\nJWT_REFRESH_SECRET=your_refresh_token_secret\nNODE_ENV=development\nPORT=3000<\/pre>\n\n\n\n
.env<\/code> file private and never commit it to a public repository.<\/p>\n\n\n\nStep 3: Generate Access and Refresh Tokens<\/h3>\n\n\n\n
const jwt = require('jsonwebtoken');\n\nconst generateTokens = (user) => {\n\n \/\/ Generate the access token\n const accessToken = jwt.sign(\n {\n userId: user._id,\n username: user.username\n },\n process.env.JWT_SECRET,\n {\n expiresIn: \"1m\"\n }\n );\n\n \/\/ Generate the refresh token\n const refreshToken = jwt.sign(\n {\n userId: user._id\n },\n process.env.JWT_REFRESH_SECRET,\n {\n expiresIn: \"30d\"\n }\n );\n\n return {\n accessToken,\n refreshToken\n };\n};<\/pre>\n\n\n\n\n
jwt.sign()<\/code> generates a signed JWT.<\/li>\n\n\n\nuser._id<\/code> identifies the authenticated user.<\/li>\n\n\n\nusername<\/code> is included in the access token payload.<\/li>\n\n\n\nJWT_SECRET<\/code> is used to sign the access token.<\/li>\n\n\n\nJWT_REFRESH_SECRET<\/code> is used to sign the refresh token.<\/li>\n\n\n\nexpiresIn<\/code> specifies how long each token remains valid.<\/li>\n<\/ul>\n\n\n\nStep 4: Store the Refresh Token in an HTTP-Only Cookie<\/h3>\n\n\n\n
const sendTokens = (req, res, user) => {\n\n const { accessToken, refreshToken } = generateTokens(user);\n\n res.cookie(\"refreshToken\", refreshToken, {\n httpOnly: true,\n secure: process.env.NODE_ENV === \"production\",\n sameSite: \"strict\",\n maxAge: 30 * 24 * 60 * 60 * 1000\n });\n\n res.json({\n accessToken\n });\n};<\/pre>\n\n\n\nsendTokens()<\/code> after verifying the user’s login credentials.<\/p>\n\n\n\n\n
httpOnly: true<\/code> prevents JavaScript from accessing the cookie.<\/li>\n\n\n\nsecure: true<\/code> sends the cookie only over HTTPS in production.<\/li>\n\n\n\nsameSite: \"strict\"<\/code> helps reduce cross-site request risks.<\/li>\n\n\n\nmaxAge<\/code> sets the cookie lifetime to 30 days.<\/li>\n<\/ul>\n\n\n\nSameSite=None<\/code>, Secure<\/code>, credentialed requests, and appropriate CSRF protection.<\/p>\n\n\n\nStep 5: Create Middleware to Authenticate Requests<\/h3>\n\n\n\n
Authorization: Bearer ACCESS_TOKEN<\/code><\/p>\n\n\n\nconst jwt = require('jsonwebtoken');\n\nconst authenticateJWT = (req, res, next) => {\n\n \/\/ Extract the access token from the Authorization header\n const authHeader = req.headers.authorization;\n\n if (!authHeader || !authHeader.startsWith(\"Bearer \")) {\n return res.status(401).json({\n message: \"Access token is required\"\n });\n }\n\n const token = authHeader.split(\" \")[1];\n\n \/\/ Verify the access token\n jwt.verify(token, process.env.JWT_SECRET, (err, user) => {\n\n if (err) {\n return res.status(403).json({\n message: \"Invalid or expired access token\"\n });\n }\n\n \/\/ Attach the decoded user information to the request\n req.user = user;\n\n next();\n });\n};\n\nmodule.exports = authenticateJWT;<\/pre>\n\n\n\n\n
jwt.verify()<\/code> validates the token using the access-token secret.<\/li>\n\n\n\nreq.user<\/code>.<\/li>\n\n\n\nnext()<\/code> allows the request to continue to the next middleware or route handler.<\/li>\n<\/ul>\n\n\n\nStep 6: Create an API Endpoint to Refresh the Access Token<\/h3>\n\n\n\n
const jwt = require('jsonwebtoken');\n\nconst refreshTokenHandler = (req, res) => {\n\n \/\/ Get the refresh token from the HTTP-only cookie\n const refreshToken = req.cookies.refreshToken;\n\n if (!refreshToken) {\n return res.status(401).json({\n message: \"Refresh token is required\"\n });\n }\n\n \/\/ Verify the refresh token\n jwt.verify(\n refreshToken,\n process.env.JWT_REFRESH_SECRET,\n (err, user) => {\n\n if (err) {\n return res.status(403).json({\n message: \"Invalid or expired refresh token\"\n });\n }\n\n \/\/ Generate a new access token\n const newAccessToken = jwt.sign(\n {\n userId: user.userId\n },\n process.env.JWT_SECRET,\n {\n expiresIn: \"1m\"\n }\n );\n\n res.json({\n accessToken: newAccessToken\n });\n }\n );\n};\n\nmodule.exports = refreshTokenHandler;<\/pre>\n\n\n\n\n
req.cookies.refreshToken<\/code>.<\/li>\n\n\n\njwt.verify()<\/code> validates the refresh token using JWT_REFRESH_SECRET<\/code>.<\/li>\n\n\n\nStep 7: Configure Express Routes<\/h3>\n\n\n\n
const express = require('express');\nconst cookieParser = require('cookie-parser');\nconst dotenv = require('dotenv');\n\nconst authenticateJWT = require('.\/middleware\/authenticateJWT');\nconst refreshTokenHandler = require('.\/controllers\/refreshTokenHandler');\n\ndotenv.config();\n\nconst app = express();\n\napp.use(express.json());\napp.use(cookieParser());\n\n\/\/ Public refresh-token endpoint\napp.post('\/refresh-token', refreshTokenHandler);\n\n\/\/ Protected API endpoint\napp.get('\/profile', authenticateJWT, (req, res) => {\n\n res.json({\n message: \"Authentication successful\",\n user: req.user\n });\n\n});\n\nconst PORT = process.env.PORT || 3000;\n\napp.listen(PORT, () => {\n console.log(`Server running on port ${PORT}`);\n});<\/pre>\n\n\n\n\n
express.json()<\/code> parses incoming JSON request bodies.<\/li>\n\n\n\ncookieParser()<\/code> makes cookies available through req.cookies<\/code>.<\/li>\n\n\n\n\/refresh-token<\/code> is a public endpoint that validates the refresh token independently.<\/li>\n\n\n\n\/profile<\/code> is protected by the authenticateJWT<\/code> middleware.<\/li>\n\n\n\nStep 8: Implement Refresh Token Revocation<\/h3>\n\n\n\n
app.post('\/logout', (req, res) => {\n\n res.clearCookie(\"refreshToken\", {\n httpOnly: true,\n secure: process.env.NODE_ENV === \"production\",\n sameSite: \"strict\"\n });\n\n res.json({\n message: \"Logged out successfully\"\n });\n\n});<\/pre>\n\n\n\nSecurity Considerations<\/h2>\n\n\n\n
Conclusion<\/h2>\n\n\n\n
FAQ<\/h2>\n\n\n\n
1. What is the difference between an access token and a refresh token?<\/h4>\n\n\n\n
2. Where should refresh tokens be stored in Node.js applications?<\/h4>\n\n\n\n
3. What happens when a refresh token expires?<\/h4>\n\n\n\n
Related Links<\/h2>\n\n\n\n
\n
Official Links<\/h2>\n\n\n\n
\n
Consult Our Node.js Development Experts<\/h2>\n\n\n\n