{ "componentChunkName": "component---src-pages-blog-markdown-remark-fields-slug-js", "path": "/blog/revoking-access-with-a-jwt-blacklist", "result": {"data":{"markdownRemark":{"html":"

Table of Contents

\n
    \n
  1. Introduction
    2. \n
  2. A Word or Two About JSON Web Tokens (JWTs)
    3. \n
  3. 7 Ways to Revoke JWT Tokens
    4. \n
  4. How to Make Access Token Management Easier
    5. \n
  5. Risks of Improper Access Token Management
    6. \n
  6. Conclusion
    7. \n
\n

Why Revoking JWT Tokens Can Be Challenging

\n

JSON Web Tokens (JWT) are a fundamental part of modern web authentication and authorization systems, particularly in applications where secure and efficient user authentication is critical. Due to their stateless nature, JWTs are widely adopted, but managing and revoking these tokens presents unique challenges that developers must carefully address to maintain the security and integrity of their systems.

\n

This article delves into seven effective strategies for revoking JWT tokens, ensuring secure access management while navigating the complexities associated with JWTs.

\n

A Word or Two About JSON Web Tokens (JWTs)

\n

JWT tokens, or JSON Web Tokens, are self-contained tokens used in authentication systems to securely transmit information between parties. These tokens include a payload that carries claims, such as the user’s ID, roles, or other relevant details about the user’s data, and are signed using a secret key.

\n

The signed JWT is then sent to the client and used in subsequent requests, typically passed in the Authorization header. This stateless nature makes JWTs a popular choice for authentication in distributed systems, as it removes the need for maintaining a server-side session state.

\n

However, the statelessness of JWTs also poses significant challenges when it comes to revocation. Unlike traditional session-based authentication, where sessions can be invalidated by removing them from the server, JWTs remain valid until their expiration (exp) time, which is embedded within the token’s payload.

\n

This expiry time ensures that the token is valid only for a specified period, but it can be problematic when a user’s account is compromised. Since the token cannot be easily invalidated across all endpoints without a centralized mechanism, any delay in detecting and revoking the token can result in unauthorized access to the user’s data.

\n

Additionally, in distributed systems where multiple services or microservices rely on the same JWT access token, revocation becomes even more complex. Each service must recognize and enforce the revocation, which can be challenging without a shared state or revocation strategy. This complexity is further compounded when integrating with identity providers that issue JWTs as part of OAuth 2.0 or OpenID Connect protocols. It is recommended to refer to platform-specific documentation (docs) or GitHub repositories to implement best practices for revoking JWTs in such relatively complex environments.

\n

7 Ways to Revoke JWT Tokens

\n

Effectively revoking JWT tokens requires implementing strategies that accommodate their stateless design while ensuring security. Here are seven methods to revoke JWT tokens, each with its pros and cons.

\n

Token Blacklisting

\n

How It Works:

\n

Token blacklisting is a widely used method to revoke JWT tokens. This approach involves maintaining a server-side blacklist containing identifiers, such as the jti claim or a user ID, of tokens that should be considered invalid.

\n

When a token is presented at an API endpoint, the server checks the blacklist to determine whether the token has been revoked. This list can be stored in a database or in an in-memory store like Redis, which allows for quick lookups.

\n

Pros:

\n\n

Cons:

\n\n

Example in Node.js:

\n {\n callback(reply === 'revoked');\n });\n}\n\n// Middleware to check token blacklist\nfunction checkBlacklist(req, res, next) {\n const token = req.headers['authorization'];\n const secret = process.env.JWT_SECRET;\n const decoded = jwt.verify(token, secret);\n\n isTokenRevoked(decoded.jti, (isRevoked) => {\n if (isRevoked) {\n return res.status(401).send('Token has been revoked');\n }\n next();\n });\n}`, `61774448850358630000`)\"\n >\n \n \n \n \n
const redis = require('redis');\nconst client = redis.createClient();\n\nfunction blacklistToken(jti) {\n  client.set(jti, 'revoked', 'EX', 3600); // Expiry set for 1 hour\n}\n\nfunction isTokenRevoked(jti, callback) {\n  client.get(jti, (err, reply) => {\n    callback(reply === 'revoked');\n  });\n}\n\n// Middleware to check token blacklist\nfunction checkBlacklist(req, res, next) {\n  const token = req.headers['authorization'];\n  const secret = process.env.JWT_SECRET;\n  const decoded = jwt.verify(token, secret);\n\n  isTokenRevoked(decoded.jti, (isRevoked) => {\n    if (isRevoked) {\n      return res.status(401).send('Token has been revoked');\n    }\n    next();\n  });\n}
\n

In this example, a JWT token’s jti (JWT ID) is stored in Redis when the token is revoked. The middleware checks if the token’s jti exists in Redis before processing the request.

\n

Token Expiration and Short Lifespan

\n

How It Works:

\n

Setting a short lifespan (the exp parameter) for JWT tokens can mitigate the risks associated with needing to revoke them. By configuring JWTs with a short expiration time, you reduce the window of opportunity for an attacker to use a compromised token.

\n

Once the token reaches its expiry, it becomes invalid, and the user must obtain a new JWT access token, typically through re-authentication or using a refresh token.

\n

Pros:

\n\n

Cons:

\n\n

Example in Node.js:

\n\n \n \n \n \n
const jwt = require('jsonwebtoken');\n\nfunction generateToken(user) {\n  const payload = { userId: user.id, roles: user.roles };\n  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '15m' });\n}
\n

In this example, JWTs are generated with a 15-minute expiration time. Users must frequently refresh their tokens, reducing the risk associated with compromised tokens.

\n

Rotating Secrets

\n

How It Works:

\n

JWT tokens are signed with a secret key that verifies their authenticity. By periodically rotating this secret key, you can invalidate all existing tokens signed with the old key. This method is particularly useful when you need to revoke a large number of tokens simultaneously, such as after a security incident or when changing your authentication strategy.

\n

Pros:

\n
    \n
  • High Security: Regularly rotating secrets add an extra layer of security, making it more difficult for attackers to exploit a compromised key.
    • \n
  • Wide Impact: Secret rotation invalidates all tokens at once, which is effective in scenarios where a large-scale revocation is necessary.
    • \n
\n

Cons:

\n
    \n
  • Complex Key Management: Rotating secrets requires careful management to avoid invalidating legitimate tokens inadvertently.
    • \n
  • Token Recreation: After a key rotation, clients must obtain new JWTs signed with the updated key, which can complicate client-side and backend interactions.
    • \n
\n

Note: Doing secret management on your own is challenging and can open you to security vulnerabilities, so most auth services handle this on your behalf.

\n

Token Versioning

\n

How It Works:

\n

Token versioning involves assigning a version number to each JWT issued, which is then stored in the database alongside the user’s account information. When a token needs to be revoked, the version number is incremented in the database, rendering all previous tokens invalid. The next time the user tries to authenticate, they must present a token with the updated version.

\n

Pros:

\n
    \n
  • Selective Revocation: Token versioning allows for targeted revocation based on the user’s account status or other criteria.
    • \n
  • Flexibility: This method can be integrated with various identity providers and authentication systems, offering a flexible solution.
    • \n
\n

Cons:

\n
    \n
  • Increased Complexity: Managing token versions adds complexity to the backend, requiring additional logic to validate token versions.
    • \n
  • Database Dependency: This approach relies on database lookups to validate token versions, which can introduce latency, especially if not optimized for in-memory checks.
    • \n
\n

Example in Node.js (+ MongoDB):

\n\n \n \n \n \n
const mongoose = require('mongoose');\n\n// Define User schema with tokenVersion field\nconst UserSchema = new mongoose.Schema({\n  email: String,\n  password: String,\n  tokenVersion: { type: Number, default: 0 }\n});\n\nconst User = mongoose.model('User', UserSchema);\n\nfunction generateToken(user) {\n  const payload = { userId: user.id, tokenVersion: user.tokenVersion };\n  return jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '15m' });\n}\n\nasync function invalidateUserTokens(userId) {\n  await User.findByIdAndUpdate(userId, { $inc: { tokenVersion: 1 } });\n}\n\n// Middleware to check token version\nasync function checkTokenVersion(req, res, next) {\n  const token = req.headers['authorization'];\n  const decoded = jwt.verify(token, process.env.JWT_SECRET);\n\n  const user = await User.findById(decoded.userId);\n  if (user.tokenVersion !== decoded.tokenVersion) {\n    return res.status(401).send('Token version is invalid');\n  }\n  next();\n}
\n

In this example, the user’s tokenVersion is stored in the database. When a token is revoked, the tokenVersion is incremented, and the middleware checks if the presented token is still valid.

\n

User Logout and Forced Token Invalidation

\n

How It Works:

\n

When a user logs out, their JWT token can be invalidated by marking it as such on the server or by expiring the session. This method ensures that the token cannot be used to access protected resources after logout. In systems that support OAuth 2.0 or OpenID Connect, this might involve notifying the identity provider to revoke the token at the source.

\n

Pros:

\n
    \n
  • Immediate Effect: The token is immediately invalidated, providing a prompt security response.
    • \n
  • User-Controlled: Users can take control of their session’s security by actively logging out.
    • \n
\n

Cons:

\n
    \n
  • Statefulness: Forced token invalidation requires maintaining a server-side state, which conflicts with the stateless nature of JWTs.
    • \n
  • Implementation Complexity: Implementing this method can be challenging in systems that rely on stateless JWTs, especially in distributed environments with multiple endpoints.
    • \n
\n

Example: User Logout and Forced Token Invalidation in Node.js

\n {\n if (err || !sessionData) {\n return res.status(401).send('Invalid token');\n }\n req.user = decoded; // Attach user info to request\n next();\n });\n } catch (e) {\n res.status(401).send('Failed to authenticate token');\n }\n}\n\n// Endpoint for user login (simulated)\napp.post('/login', (req, res) => {\n const { username, email } = req.body;\n const sessionId = \\`\\${username}-\\${Date.now()}\\`; // Generate a unique session ID\n const token = jwt.encode({ sessionId }, SECRET_KEY, 'HS256');\n redisClient.set(sessionId, JSON.stringify({ username, email }), 'EX', 3600); // Store session with 1-hour expiry\n res.json({ token });\n});\n\n// Endpoint for user logout\napp.post('/logout', verifyToken, (req, res) => {\n const sessionId = req.user.sessionId;\n redisClient.del(sessionId, (err) => {\n if (err) {\n return res.status(500).send('Failed to logout');\n }\n // Notify user about session expiration\n redisClient.get(sessionId, (err, sessionData) => {\n if (!err && sessionData) {\n const userEmail = JSON.parse(sessionData).email;\n const mailOptions = {\n from: 'your_email@gmail.com',\n to: userEmail,\n subject: 'Session Expired',\n text: 'Your session has been terminated. If you did not request this, please contact support.'\n };\n transporter.sendMail(mailOptions, (error, info) => {\n if (error) {\n console.error('Error sending email:', error);\n } else {\n console.log('Email sent:', info.response);\n }\n });\n }\n });\n res.send('Logged out successfully');\n });\n});\n\n// Protected endpoint\napp.get('/protected', verifyToken, (req, res) => {\n res.send(\\`Hello \\${req.user.sessionId}, you have access to this protected resource\\`);\n});\n\napp.listen(PORT, () => {\n console.log(\\`Server running on port \\${PORT}\\`);\n});`, `35865789848716780000`)\"\n >\n \n \n \n \n
const express = require('express');\nconst jwt = require('jwt-simple');\nconst redis = require('redis');\nconst bodyParser = require('body-parser');\nconst nodemailer = require('nodemailer');\nconst app = express();\n\napp.use(bodyParser.json());\nconst redisClient = redis.createClient();\nconst SECRET_KEY = 'your_secret_key'; // Replace with your actual secret key\nconst PORT = 3000;\n\n// Configure email transport for notifications\nconst transporter = nodemailer.createTransport({\n  service: 'gmail',\n  auth: {\n    user: 'your_email@gmail.com', // Replace with your email\n    pass: 'your_email_password'   // Replace with your email password\n  }\n});\n\n// Middleware to verify JWT and check session\nfunction verifyToken(req, res, next) {\n  const token = req.headers['authorization'];\n  if (!token) {\n    return res.status(401).send('No token provided');\n  }\n  try {\n    const decoded = jwt.decode(token, SECRET_KEY);\n    const sessionId = decoded.sessionId;\n    redisClient.get(sessionId, (err, sessionData) => {\n      if (err || !sessionData) {\n        return res.status(401).send('Invalid token');\n      }\n      req.user = decoded; // Attach user info to request\n      next();\n    });\n  } catch (e) {\n    res.status(401).send('Failed to authenticate token');\n  }\n}\n\n// Endpoint for user login (simulated)\napp.post('/login', (req, res) => {\n  const { username, email } = req.body;\n  const sessionId = `${username}-${Date.now()}`; // Generate a unique session ID\n  const token = jwt.encode({ sessionId }, SECRET_KEY, 'HS256');\n  redisClient.set(sessionId, JSON.stringify({ username, email }), 'EX', 3600); // Store session with 1-hour expiry\n  res.json({ token });\n});\n\n// Endpoint for user logout\napp.post('/logout', verifyToken, (req, res) => {\n  const sessionId = req.user.sessionId;\n  redisClient.del(sessionId, (err) => {\n    if (err) {\n      return res.status(500).send('Failed to logout');\n    }\n    // Notify user about session expiration\n    redisClient.get(sessionId, (err, sessionData) => {\n      if (!err && sessionData) {\n        const userEmail = JSON.parse(sessionData).email;\n        const mailOptions = {\n          from: 'your_email@gmail.com',\n          to: userEmail,\n          subject: 'Session Expired',\n          text: 'Your session has been terminated. If you did not request this, please contact support.'\n        };\n        transporter.sendMail(mailOptions, (error, info) => {\n          if (error) {\n            console.error('Error sending email:', error);\n          } else {\n            console.log('Email sent:', info.response);\n          }\n        });\n      }\n    });\n    res.send('Logged out successfully');\n  });\n});\n\n// Protected endpoint\napp.get('/protected', verifyToken, (req, res) => {\n  res.send(`Hello ${req.user.sessionId}, you have access to this protected resource`);\n});\n\napp.listen(PORT, () => {\n  console.log(`Server running on port ${PORT}`);\n});
\n

Token Revocation Lists

\n

How It Works:

\n

A Token Revocation List (TRL) operates similarly to a blacklist but is often implemented as a centralized or distributed service that can be queried to determine if a token has been revoked. This method is especially effective in large-scale distributed systems where multiple services and endpoints need to recognize and enforce token revocation.

\n

Pros:

\n
    \n
  • Scalability: A TRL can be designed to handle high loads in distributed environments, ensuring that all services consistently enforce token revocation.
    • \n
  • Centralized Management: By centralizing token revocation, this method simplifies the management and enforcement of revocation policies.
    • \n
\n

Cons:

\n
    \n
  • Latency: Querying a TRL can introduce latency, especially if the revocation list is not stored in an in-memory database or is not optimized for fast lookups.
    • \n
  • Complexity: Implementing and maintaining a TRL requires careful design to ensure scalability and reliability across distributed services.
    • \n
\n

Implementation Tip:

\n

When designing a TRL, consider using in-memory data stores like Redis or distributed caching systems to reduce latency. Additionally, ensure that your system can handle large-scale requests by implementing load balancing and failover mechanisms.

\n

Example of Implementing a Simple TRL in Node.js:

\n {\n // Fetch the latest TRL from a trusted source\n const latestTRL = fetchTrustedRevocationList();\n updateRevocationList(latestTRL);\n}, 60000); // Update every 60 seconds`, `68933320570225520000`)\"\n >\n \n \n \n \n
let trustedRevocationList = [];\n\nfunction updateRevocationList(newList) {\n  trustedRevocationList = newList;\n}\n\nfunction isTokenRevoked(jti) {\n  return trustedRevocationList.includes(jti);\n}\n\n// Middleware to check TRL\nfunction checkRevocationList(req, res, next) {\n  const token = req.headers['authorization'];\n  const decoded = jwt.verify(token, process.env.JWT_SECRET);\n\n  if (isTokenRevoked(decoded.jti)) {\n    return res.status(401).send('Token has been revoked');\n  }\n  next();\n}\n\n// Example of updating TRL (this would typically be done periodically)\nsetInterval(() => {\n  // Fetch the latest TRL from a trusted source\n  const latestTRL = fetchTrustedRevocationList();\n  updateRevocationList(latestTRL);\n}, 60000); // Update every 60 seconds
\n

Refresh Tokens for Long-Lived Sessions

\n

How It Works:

\n

In scenarios where long-lived sessions are necessary, using refresh tokens in conjunction with JWTs provides a secure way to manage token expiry and revocation. The refresh token is stored securely on the server and is used to generate new JWT access tokens when the previous one expires. If a user’s account is compromised, the refresh token can be revoked, preventing the issuance of new JWT access tokens.

\n

Pros:

\n
    \n
  • Increased Security: This method enhances security by limiting the lifespan of JWT access tokens while providing a mechanism for immediate revocation through the refresh token.
    • \n
  • Flexible Control: Allows for the revocation of individual sessions without affecting others, providing a granular approach to session management.
    • \n
\n

Cons:

\n
    \n
  • Complexity: Managing refresh tokens adds complexity to the backend and client-side logic, as well as potential storage challenges if multiple refresh tokens are issued.
    • \n
  • No Immediate Revocation for Access Tokens: Revoking the refresh token does not immediately invalidate the existing JWT access token, leaving a short window of vulnerability.
    • \n
\n

Example in Node.js:

\n\n \n \n \n \n
const jwt = require('jsonwebtoken');\nconst uuid = require('uuid');\n\n// Simulated in-memory refresh token store\nlet refreshTokenStore = {};\n\nfunction generateToken(user) {\n  const payload = { userId: user.id };\n  const accessToken = jwt.sign(payload, process.env.JWT_SECRET, { expiresIn: '15m' });\n  const refreshToken = uuid.v4();\n\n  // Store refresh token server-side\n  refreshTokenStore[refreshToken] = user.id;\n\n  return { accessToken, refreshToken };\n}\n\nfunction refreshAccessToken(refreshToken) {\n  const userId = refreshTokenStore[refreshToken];\n  if (!userId) {\n    throw new Error('Invalid refresh token');\n  }\n\n  const newAccessToken = jwt.sign({ userId }, process.env.JWT_SECRET, { expiresIn: '15m' });\n  return newAccessToken;\n}\n\nfunction revokeRefreshToken(refreshToken) {\n  delete refreshTokenStore[refreshToken];\n}\n\n// Middleware example for refreshing access tokens\nfunction refreshTokenMiddleware(req, res, next) {\n  const { refreshToken } = req.body;\n\n  try {\n    const newAccessToken = refreshAccessToken(refreshToken);\n    res.json({ accessToken: newAccessToken });\n  } catch (err) {\n    res.status(401).send('Invalid or expired refresh token');\n  }\n}
\n

How to Make Access Token Management Easier

\n

Effective access token management is crucial for maintaining the security of your application. Here are some best practices to simplify the process:

\n
    \n
  • Use Refresh Tokens: As mentioned, refresh tokens can provide an effective way to manage and revoke JWTs. Ensure they are securely stored, either on the client-side or in Redis, and frequently rotated to prevent misuse.
    • \n
  • Minimize Token Lifespan: Short-lived tokens reduce the impact of a compromised token. Pair them with refresh tokens to balance security and usability, configuring the exp parameter appropriately.
    • \n
  • Ensure Secure Storage: Store tokens securely, whether in cookies with the HttpOnly and Secure flags or in secure client-side storage mechanisms like local storage.
    • \n
  • Monitor for Suspicious Activity: Implement monitoring and notifications for unusual token usage patterns, such as tokens being used from multiple locations.
    • \n
  • Automate Token Management: Use tools like SuperTokens to handle JWT creation, validation, and revocation. This can streamline your authentication process and reduce the risk of errors.
    • \n
\n

For more on creating JWTs and securing user sessions, see our docs on JWT Creation and our guide on Using JWTs for User Sessions. You can also explore how to configure secure tokens in Node.js with backend tools like Redis for in-memory storage.

\n

Risks of Improper Access Token Management

\n

Failing to properly manage and revoke JWT tokens can lead to serious security risks:

\n
    \n
  • Unauthorized Access: Compromised tokens can grant unauthorized access to your application, leading to data breaches and other security incidents.
    • \n
  • Token Theft: If tokens are not securely stored on the client-side, they can be stolen and used maliciously.
    • \n
  • Replay Attacks: Attackers can reuse a stolen token to gain unauthorized access if tokens are not properly managed.
    • \n
  • Poor User Experience: Improper token management can lead to unnecessary logouts or difficulties accessing services.
    • \n
  • Legal Implications: In regulated industries like fintech, failing to manage tokens properly can result in compliance violations, leading to legal penalties.
    • \n
\n

For a comprehensive guide on implementing secure authentication practices, check out our articles on OAuth 2.0 vs. JWT and Passwordless Login. You can also find code examples on GitHub for integrating these practices in your Node.js applications.

\n

Conclusion

\n

Revoking JWT tokens is a crucial aspect of securing modern web applications. While the stateless nature of JWTs presents challenges, the methods discussed above offer effective strategies for maintaining secure access management. Whether through token blacklisting, rotating secrets, or using refresh tokens, implementing a robust revocation strategy is essential to protecting your application and users’ data.

\n

There are a ton of intricacies while building a robust authentication solution with JWTs. Keeping up with best practices and the most secure standards, while keeping up-to-date with the latest threat vectors, is hard to say the least.

\n

Unless you’re building a personal project, learning, or have an extremely niche use case that is not supported by auth providers, it is better to offload the headache to a service instead.

\n

Easily manage user access with SuperTokens and take the hassle out of JWT management. Start securing your application today.

","frontmatter":{"date":"August 15, 2024","title":"7 Ways To Revoke JWT Tokens","cover":"revoking-access-with-a-jwt-blacklist.png","author":"Dejan Lukic","description":"Learn how to maintain a JWT token blacklist / deny list using an in-memory data cache"},"fields":{"slug":"/revoking-access-with-a-jwt-blacklist/"}},"site":{"siteMetadata":{"title":"SuperTokens Blog"}}},"pageContext":{"id":"83363a09-8990-5fc8-8d35-01d24bb3d4d5","fields__slug":"/revoking-access-with-a-jwt-blacklist/","__params":{"fields__slug":"revoking-access-with-a-jwt-blacklist"}}}, "staticQueryHashes": []}