JWT (JSON Web Token) authentication has become the standard for modern single-page applications, offering a stateless approach that scales beautifully across distributed systems. When combined with Vue 3's reactive architecture and Node.js's efficient runtime, developers can build secure, performant authentication systems that protect user data while delivering seamless user experiences. This comprehensive guide walks through implementing production-ready JWT authentication, from secure token storage patterns to route protection strategies, ensuring your application meets security best practices while maintaining the responsiveness users expect from professional web development services.
Understanding JWT Authentication
JWT (JSON Web Token) authentication provides a stateless, scalable approach to securing modern web applications. Unlike traditional session-based authentication that requires server-side storage, JWTs carry all necessary claims within the token itself, enabling distributed systems to validate requests without shared state.
How JWT Authentication Works
The authentication lifecycle begins when a user submits their credentials. Upon successful validation, the server generates a signed JWT containing user claims and returns it to the client. For subsequent requests, the client includes this token in the Authorization header, allowing the server to verify identity without consulting a database. This stateless nature makes JWT particularly well-suited for microservices architectures and applications expecting high traffic.
The three-part structure of JWTs includes a header specifying the algorithm, a payload containing claims about the user, and a signature ensuring token integrity. Common claims include the subject (user ID), expiration time, issued-at timestamp, and custom roles or permissions. Understanding this structure helps developers debug authentication issues and implement token validation effectively.
JWT Token Structure
A JWT consists of three Base64URL-encoded segments separated by periods. The header typically specifies HS256 as the signing algorithm and JWT as the token type. The payload contains registered claims like exp (expiration), sub (subject), and iat (issued at), along with custom claims for user roles and permissions. The signature is computed by Base64URL-encoding the header and payload, concatenating them with a period, and signing with the server's secret key.
// Example JWT decoded structure
{
"header": {
"alg": "HS256",
"typ": "JWT"
},
"payload": {
"sub": "1234567890",
"name": "John Doe",
"iat": 1516239022,
"exp": 1516242622,
"role": "user"
},
"signature": "HMACSHA256(base64UrlEncode(header) + '.' + base64UrlEncode(payload), secret)"
}
When implementing JWT authentication, always validate the signature before processing token contents, check expiration dates to prevent replay attacks, and verify the issuer when working with multiple services.
Secure Token Storage Strategies
The choice of token storage location significantly impacts application security. While storing tokens in localStorage offers convenience, it exposes applications to XSS (Cross-Site Scripting) attacks where malicious scripts can access and exfiltrate tokens. Third-party scripts embedded for analytics, ads, or functionality can potentially compromise token security if they become compromised.
The recommended approach combines httpOnly cookies with memory storage. HttpOnly cookies cannot be accessed by JavaScript, providing protection against XSS attacks. Access tokens remain in memory only, never written to storage, meaning they are cleared when the user closes the tab or refreshes the page. Refresh tokens, stored in httpOnly cookies, automatically reauthenticate users without exposing tokens to client-side scripts. This security-first approach is essential for any production web application handling sensitive user data.
// Secure Pinia auth store pattern
import { defineStore } from 'pinia'
export const useAuthStore = defineStore('auth', {
state: () => ({
user: null,
isAuthenticated: false,
accessToken: null // Stored in memory ONLY
}),
actions: {
async login(credentials) {
const response = await fetch('/api/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(credentials),
credentials: 'include' // Critical: include httpOnly cookies
})
if (response.ok) {
const data = await response.json()
this.user = data.user
this.isAuthenticated = true
this.accessToken = data.accessToken
}
}
}
})
When implementing this pattern, always configure SameSite=strict or SameSite=lax on cookies, use HTTPS exclusively in production, and set appropriate cookie expiration matching your refresh token lifecycle.
Vue 3 Pinia Authentication Store
Pinia provides an intuitive, type-safe state management solution for Vue 3 authentication. A well-designed auth store centralizes login, logout, token refresh, and user state management, making authentication logic reusable across components. The store should expose reactive state for current user and authentication status, along with actions for common operations.
Modern implementations use the Composition API pattern, providing better TypeScript support and easier composition with other composables. The store handles token storage (in memory only for access tokens), user persistence to localStorage, automatic token refresh scheduling, and proper cleanup on logout. This separation of concerns keeps components clean while centralizing authentication complexity for your Vue.js applications.
// stores/auth.js - Composition API pattern
import { ref, computed } from 'vue'
import { defineStore } from 'pinia'
export const useAuthStore = defineStore('auth', () => {
const user = ref(null)
const accessToken = ref(null)
const isAuthenticated = computed(() => !!user.value && !!accessToken.value)
async function login(email, password) {
const response = await fetch('/api/auth/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password })
})
if (!response.ok) throw new Error('Login failed')
const data = await response.json()
user.value = data.user
accessToken.value = data.accessToken
return data.user
}
async function logout() {
await fetch('/api/auth/logout', {
method: 'POST',
headers: { Authorization: `Bearer ${accessToken.value}` }
})
user.value = null
accessToken.value = null
}
return { user, accessToken, isAuthenticated, login, logout }
})
Axios Interceptors for JWT Handling
Axios interceptors provide a powerful mechanism for automatically handling JWT authentication across all API requests. The request interceptor attaches the current access token to outgoing requests, while the response interceptor handles authentication failures, particularly 401 errors that indicate expired or invalid tokens.
When a 401 error occurs, the response interceptor attempts to refresh the access token using the refresh token stored in httpOnly cookies. If successful, it retries the original request with the new token. For scenarios where multiple requests receive 401 errors simultaneously, a queue system ensures only one refresh request occurs, with queued requests automatically retrying after token refresh. This pattern prevents token refresh storms and ensures consistent user experience across your full-stack applications.
// utils/api.js with interceptors
import axios from 'axios'
import { useAuthStore } from '@/stores/auth'
const api = axios.create({ baseURL: process.env.VUE_APP_API_URL })
let isRefreshing = false
let failedRequestsQueue = []
api.interceptors.request.use((config) => {
const authStore = useAuthStore()
if (authStore.accessToken) {
config.headers.Authorization = `Bearer ${authStore.accessToken}`
}
return config
})
api.interceptors.response.use(
(response) => response,
async (error) => {
const originalRequest = error.config
if (error.response?.status === 401 && !originalRequest._retry) {
originalRequest._retry = true
if (!isRefreshing) {
isRefreshing = true
try {
const authStore = useAuthStore()
const response = await axios.post('/api/auth/refresh', {}, {
withCredentials: true
})
authStore.accessToken = response.data.accessToken
failedRequestsQueue.forEach(cb => cb(response.data.accessToken))
failedRequestsQueue = []
originalRequest.headers.Authorization = `Bearer ${response.data.accessToken}`
return api(originalRequest)
} catch (e) {
authStore.logout()
failedRequestsQueue = []
} finally {
isRefreshing = false
}
} else {
return new Promise((resolve) => {
failedRequestsQueue.push((token) => {
originalRequest.headers.Authorization = `Bearer ${token}`
resolve(api(originalRequest))
})
})
}
}
return Promise.reject(error)
}
)
Vue Router Route Protection
Vue Router's navigation guards enable fine-grained control over which routes require authentication. The beforeEach hook checks authentication status before each navigation, redirecting unauthenticated users to the login page while preserving their intended destination. Route meta fields specify authentication requirements, allowing flexible configuration per route.
For administrative routes, additional role-based checks ensure only authorized users can access sensitive areas. The login redirect flow preserves the originally requested URL, providing a seamless experience when users authenticate. Combining these patterns creates a robust navigation protection system that scales with application complexity in enterprise web applications.
// router/index.js with authentication guards
import { createRouter, createWebHistory } from 'vue-router'
import { useAuthStore } from '@/stores/auth'
const routes = [
{
path: '/login',
name: 'Login',
component: () => import('@/views/Login.vue'),
meta: { requiresAuth: false }
},
{
path: '/dashboard',
name: 'Dashboard',
component: () => import('@/views/Dashboard.vue'),
meta: { requiresAuth: true }
},
{
path: '/admin',
name: 'Admin',
component: () => import('@/views/Admin.vue'),
meta: { requiresAuth: true, requiresAdmin: true }
}
]
const router = createRouter({
history: createWebHistory(),
routes
})
router.beforeEach((to, from, next) => {
const authStore = useAuthStore()
if (to.meta.requiresAuth && !authStore.isAuthenticated) {
return next({ name: 'Login', query: { redirect: to.fullPath } })
}
if (to.meta.requiresAdmin && authStore.user?.role !== 'admin') {
return next({ name: 'Dashboard' })
}
if (to.meta.requiresAuth === false && authStore.isAuthenticated) {
return next({ name: 'Dashboard' })
}
next()
})
export default router
Node.js Backend Implementation
The server-side JWT implementation requires careful attention to security and token lifecycle management. Middleware verifies tokens on protected routes, extracting user information from valid tokens and attaching it to the request object. Error handling distinguishes between expired tokens, invalid signatures, and other authentication failures.
The authentication controller manages token generation, refresh, and logout operations. Access tokens use short expiration times (15-30 minutes) to limit exposure if tokens are compromised. Refresh tokens with longer lifespans (7-30 days) remain in httpOnly cookies, enabling seamless reauthentication without requiring user credentials. Storing refresh tokens in a server-side store (Redis or database) enables token revocation when users log out or administrators need to invalidate sessions.
// controllers/authController.js
exports.login = async (req, res) => {
const { email, password } = req.body
const user = await userModel.findByEmail(email)
if (!user || !(await user.comparePassword(password))) {
return res.status(401).json({ message: 'Invalid credentials' })
}
const accessToken = jwt.sign({ sub: user.id, role: user.role }, process.env.JWT_SECRET, {
expiresIn: '15m'
})
const refreshToken = jwt.sign({ sub: user.id, type: 'refresh' }, process.env.JWT_REFRESH_SECRET, {
expiresIn: '7d'
})
refreshTokenStore.set(refreshToken, { userId: user.id, expiresAt: Date.now() + 7 * 24 * 60 * 60 * 1000 })
res.cookie('refreshToken', refreshToken, { httpOnly: true, secure: true, sameSite: 'strict', maxAge: 7 * 24 * 60 * 60 * 1000 })
res.json({ accessToken, user: { id: user.id, email: user.email, role: user.role } })
}
Access Tokens vs Refresh Tokens
The dual-token architecture balances security with user experience by separating short-lived access tokens from long-lived refresh tokens. Access tokens, with expiration times of 15-30 minutes, authorize API requests and limit exposure if tokens are intercepted. Their short lifespan means compromised tokens quickly become useless, reducing the window for attacks.
Refresh tokens enable obtaining new access tokens without re-entering credentials, maintaining seamless authentication experiences. Stored in httpOnly cookies, they cannot be accessed by JavaScript, protecting against XSS attacks. Token rotation enhances security by invalidating refresh tokens after use and issuing new ones, preventing reuse of stolen refresh tokens.
Implementing refresh token rotation requires tracking used tokens server-side and rejecting attempts to reuse already-rotated tokens. When a refresh token is used, generate a new access token and a new refresh token, invalidate the old refresh token, and return the new refresh token in an httpOnly cookie. This creates a continuous rotation cycle that invalidates any stolen refresh tokens.
Logout and Token Invalidation
Proper logout handling requires coordinated cleanup on both client and server. Client-side, clear all authentication state including user data, access tokens, and any cached information. Server-side, invalidate refresh tokens to prevent token reuse, ensuring the logout request itself is authenticated to prevent unauthorized logouts.
The implementation should handle logout failures gracefully, always clearing client state regardless of server response. For applications requiring immediate session termination (password change, security alert), implement a token blacklist or use short refresh token expiration times. Consider also handling multiple concurrent sessions, providing users visibility into active sessions and the ability to terminate them remotely.
// Vue logout implementation
const handleLogout = async () => {
try {
await api.post('/auth/logout')
} catch (error) {
console.error('Server logout failed:', error)
} finally {
authStore.clearAuth()
router.push('/login')
}
}
Error Handling and Security Best Practices
Production authentication requires careful error handling that balances user experience with security. Avoid returning detailed error messages that could reveal user existence or valid credentials. Generic messages like "Invalid credentials" prevent enumeration attacks while providing users feedback on failed attempts.
Rate limiting on authentication endpoints prevents brute-force attacks, while proper HTTP status codes (401 for authentication failures, 403 for authorization failures) enable appropriate client handling. Security headers including X-Content-Type-Options, X-Frame-Options, and HSTS protect against common attack vectors. Always use HTTPS in production, as sending credentials or tokens over HTTP exposes them to interception. Implementing these security measures is essential for any production web application handling authenticated users.
// Security middleware and error responses
const securityHeaders = (req, res, next) => {
res.setHeader('X-Content-Type-Options', 'nosniff')
res.setHeader('X-Frame-Options', 'DENY')
res.setHeader('X-XSS-Protection', '1; mode=block')
res.setHeader('Strict-Transport-Security', 'max-age=31536000; includeSubDomains')
next()
}
const errorResponses = {
invalidCredentials: { status: 401, message: 'Invalid email or password' },
tokenExpired: { status: 401, message: 'Session expired. Please log in again.' },
insufficientPermissions: { status: 403, message: 'Access denied.' }
}
Frequently Asked Questions
Quick Reference: JWT Implementation Checklist
- Store refresh tokens in httpOnly cookies with SameSite=strict
- Keep access tokens in memory only, never write to localStorage
- Configure axios request interceptor to attach access tokens
- Implement axios response interceptor for automatic token refresh
- Set up Vue Router guards for protected routes
- Configure short access token expiration (15-30 minutes)
- Implement refresh token rotation on each refresh
- Add proper error handling with secure error messages
- Configure rate limiting for authentication endpoints
- Set security headers (X-Content-Type-Options, HSTS, etc.)
- Implement proper logout with server-side token invalidation
- Test authentication flows including edge cases
Following this checklist ensures production-ready JWT authentication that balances security with user experience. For organizations seeking expert implementation, professional web development services can help architect and deploy secure authentication systems tailored to your specific requirements.