Understanding Refresh Tokens: Theory, Implementation, and Security Best Practices

import Security

func storeRefreshToken(_ token: String) {
    let data = token.data(using: .utf8)!
    let query: [String: Any] = [
        kSecClass as String: kSecClassGenericPassword,
        kSecAttrAccount as String: "refresh_token",
        kSecValueData as String: data,
        kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
    ]
    SecItemAdd(query as CFDictionary, nil)
}

// revoke token
await redis.set(`revoked:${jti}`, 'true', 'EX', tokenExpirySeconds);

// middleware to check revocation
app.use(async (req, res, next) => {
  const token = extractAccessToken(req);
  const { jti } = jwt.decode(token);
  const revoked = await redis.get(`revoked:${jti}`);
  if (revoked) return res.status(401).json({ error: 'token_revoked' });
  next();
});

const { Model, DataTypes } = require('sequelize');
module.exports = (sequelize) => {
  class RefreshToken extends Model {}
  RefreshToken.init({
    token: {
      type: DataTypes.UUID,
      defaultValue: DataTypes.UUIDV4,
      primaryKey: true,
    },
    userId: { type: DataTypes.INTEGER, allowNull: false },
    expiresAt: { type: DataTypes.DATE, allowNull: false },
    revoked: { type: DataTypes.BOOLEAN, defaultValue: false },
    createdAt: DataTypes.DATE,
    updatedAt: DataTypes.DATE,
  }, { sequelize, modelName: 'RefreshToken' });
  return RefreshToken;
};

const jwt = require('jsonwebtoken');
const config = require('../config');

function signAccessToken(user) {
  return jwt.sign(
    { sub: user.id, name: user.name, role: user.role },
    config.accessTokenSecret,
    { expiresIn: '10m' } // short-lived
  );
}

module.exports = { signAccessToken };

const express = require('express');
const router = express.Router();
const { signAccessToken } = require('../utils/token');
const { RefreshToken } = require('../models');
const { Op } = require('sequelize');

// -------------------------------------------------
// 1️⃣ Login – issue both tokens
// -------------------------------------------------
router.post('/login', async (req, res) => {
  const { username, password } = req.body;
  const user = await authenticate(username, password); // implement your own
  if (!user) return res.status(401).json({ error: 'invalid_credentials' });

  const accessToken = signAccessToken(user);
  const refresh = await RefreshToken.create({
    userId: user.id,
    expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
  });

  res.json({ accessToken, refreshToken: refresh.token });
});

// -------------------------------------------------
// 2️⃣ Refresh – rotate token
// -------------------------------------------------
router.post('/token', async (req, res) => {
  const { refreshToken } = req.body;
  if (!refreshToken) return res.status(400).json({ error: 'missing_token' });

  const stored = await RefreshToken.findOne({
    where: {
      token: refreshToken,
      expiresAt: { [Op.gt]: new Date() },
      revoked: false,
    },
  });

  if (!stored) return res.status(401).json({ error: 'invalid_refresh' });

  // Rotate: revoke old token
  stored.revoked = true;
  await stored.save();

  // Issue new tokens
  const user = await getUserById(stored.userId);
  const newAccess = signAccessToken(user);
  const newRefresh = await RefreshToken.create({
    userId: user.id,
    expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000),
  });

  res.json({
    accessToken: newAccess,
    refreshToken: newRefresh.token,
  });
});

module.exports = router;

const jwt = require('jsonwebtoken');
const config = require('../config');

function authenticateAccessToken(req, res, next) {
  const auth = req.headers.authorization;
  if (!auth?.startsWith('Bearer ')) return res.sendStatus(401);
  const token = auth.slice(7);
  try {
    const payload = jwt.verify(token, config.accessTokenSecret);
    req.user = payload;
    next();
  } catch (e) {
    return res.sendStatus(401);
  }
}

module.exports = { authenticateAccessToken };

npm install express sequelize pg pg-hstore jsonwebtoken
node src/app.js

pip install Flask Flask-SQLAlchemy PyJWT python-dotenv

import os, uuid, datetime
from flask import Flask, request, jsonify
from flask_sqlalchemy import SQLAlchemy
import jwt

app = Flask(__name__)
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///tokens.db'
app.config['ACCESS_SECRET'] = os.getenv('ACCESS_SECRET', 'access-secret')
app.config['REFRESH_SECRET'] = os.getenv('REFRESH_SECRET', 'refresh-secret')
db = SQLAlchemy(app)

# -------------------------------------------------
# Model for opaque refresh tokens
# -------------------------------------------------
class RefreshToken(db.Model):
    id = db.Column(db.String, primary_key=True, default=lambda: str(uuid.uuid4()))
    user_id = db.Column(db.Integer, nullable=False)
    expires_at = db.Column(db.DateTime, nullable=False)
    revoked = db.Column(db.Boolean, default=False)

# -------------------------------------------------
# Helper: create access JWT
# -------------------------------------------------
def create_access_token(user_id):
    payload = {
        'sub': user_id,
        'iat': datetime.datetime.utcnow(),
        'exp': datetime.datetime.utcnow() + datetime.timedelta(minutes=10)
    }
    return jwt.encode(payload, app.config['ACCESS_SECRET'], algorithm='HS256')

# -------------------------------------------------
# Helper: create JWT refresh token (optional)
# -------------------------------------------------
def create_jwt_refresh_token(user_id):
    payload = {
        'sub': user_id,
        'jti': str(uuid.uuid4()),
        'iat': datetime.datetime.utcnow(),
        'exp': datetime.datetime.utcnow() + datetime.timedelta(days=30)
    }
    return jwt.encode(payload, app.config['REFRESH_SECRET'], algorithm='HS256')

# -------------------------------------------------
# Login endpoint – issues both tokens
# -------------------------------------------------
@app.route('/login', methods=['POST'])
def login():
    data = request.json
    username, password = data.get('username'), data.get('password')
    # Dummy auth – replace with real DB check
    if username != 'alice' or password != 'wonderland':
        return jsonify({'error': 'invalid_credentials'}), 401

    user_id = 1  # static for demo
    access = create_access_token(user_id)

    # Choose opaque or JWT refresh token
    # opaque:
    rt = RefreshToken(user_id=user_id,
                     expires_at=datetime.datetime.utcnow() + datetime.timedelta(days=30))
    db.session.add(rt)
    db.session.commit()
    refresh = rt.id

    # # JWT variant:
    # refresh = create_jwt_refresh_token(user_id)

    return jsonify({'access_token': access, 'refresh_token': refresh})

# -------------------------------------------------
# Refresh endpoint – handles rotation
# -------------------------------------------------
@app.route('/refresh', methods=['POST'])
def refresh():
    data = request.json
    token = data.get('refresh_token')
    if not token:
        return jsonify({'error': 'missing_token'}), 400

    # Opaque token path
    rt = RefreshToken.query.filter_by(id=token, revoked=False).first()
    if not rt or rt.expires_at < datetime.datetime.utcnow():
        return jsonify({'error': 'invalid_refresh'}), 401

    # Rotate
    rt.revoked = True
    db.session.add(rt)

    # Issue new tokens
    user_id = rt.user_id
    new_access = create_access_token(user_id)
    new_rt = RefreshToken(user_id=user_id,
                          expires_at=datetime.datetime.utcnow() + datetime.timedelta(days=30))
    db.session.add(new_rt)
    db.session.commit()

    return jsonify({'access_token': new_access, 'refresh_token': new_rt.id})

# -------------------------------------------------
# Protected resource example
# -------------------------------------------------
@app.route('/profile')
def profile():
    auth = request.headers.get('Authorization', '')
    if not auth.startswith('Bearer '):
        return jsonify({'error': 'token_missing'}), 401
    token = auth.split()[1]
    try:
        payload = jwt.decode(token, app.config['ACCESS_SECRET'], algorithms=['HS256'])
        return jsonify({'user_id': payload['sub'], 'msg': 'Hello!'})
    except jwt.ExpiredSignatureError:
        return jsonify({'error': 'token_expired'}), 401
    except jwt.InvalidTokenError:
        return jsonify({'error': 'invalid_token'}), 401

if __name__ == '__main__':
    db.create_all()
    app.run(debug=True)

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-data-jpa</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.security</groupId>
        <artifactId>spring-security-oauth2-authorization-server</artifactId>
        <version>0.4.0</version>
    </dependency>
    <dependency>
        <groupId>com.nimbusds</groupId>
        <artifactId>nimbus-jose-jwt</artifactId>
    </dependency>
    <!-- H2 for demo -->
    <dependency>
        <groupId>com.h2database</groupId>
        <artifactId>h2</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies>

@Entity
@Table(name = "refresh_tokens")
public class RefreshToken {
    @Id
    private String token; // UUID string

    @Column(nullable = false)
    private Long userId;

    @Column(nullable = false)
    private Instant expiresAt;

    @Column(nullable = false)
    private boolean revoked = false;

    // getters & setters omitted for brevity
}

public interface RefreshTokenRepository extends JpaRepository<RefreshToken, String> {
    Optional<RefreshToken> findByTokenAndRevokedFalseAndExpiresAtAfter(String token, Instant now);
}

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Value("${jwt.access.secret}")
    private String accessSecret;

    @Autowired
    private RefreshTokenRepository refreshRepo;

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .csrf().disable()
            .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            .and()
            .authorizeRequests()
                .antMatchers("/login", "/token").permitAll()
                .anyRequest().authenticated()
            .and()
            .addFilterBefore(new JwtAuthenticationFilter(accessSecret), UsernamePasswordAuthenticationFilter.class);
    }

    // ---- AuthenticationManager bean for /login endpoint ----
    @Bean
    @Override
    public AuthenticationManager authenticationManagerBean() throws Exception {
        return super.authenticationManagerBean();
    }
}

public class JwtAuthenticationFilter extends OncePerRequestFilter {

    private final String secret;

    public JwtAuthenticationFilter(String secret) {
        this.secret = secret;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        String header = request.getHeader(HttpHeaders.AUTHORIZATION);
        if (header != null && header.startsWith("Bearer ")) {
            String token = header.substring(7);
            try {
                SignedJWT signedJWT = SignedJWT.parse(token);
                JWSVerifier verifier = new MACVerifier(secret);
                if (signedJWT.verify(verifier)) {
                    JWTClaimsSet claims = signedJWT.getJWTClaimsSet();
                    if (new Date().before(claims.getExpirationTime())) {
                        UsernamePasswordAuthenticationToken auth = new UsernamePasswordAuthenticationToken(
                                claims.getSubject(), null, List.of(new SimpleGrantedAuthority("USER")));
                        SecurityContextHolder.getContext().setAuthentication(auth);
                    }
                }
            } catch (Exception e) {
                // invalid token – let it fall through to 401 later
            }
        }
        filterChain.doFilter(request, response);
    }
}

@RestController
public class AuthController {

    @Autowired private AuthenticationManager authManager;
    @Autowired private RefreshTokenRepository refreshRepo;

    @Value("${jwt.access.secret}")
    private String accessSecret;

    @PostMapping("/login")
    public ResponseEntity<?> login(@RequestBody AuthRequest req) {
        try {
            Authentication auth = authManager.authenticate(
                new UsernamePasswordAuthenticationToken(req.getUsername(), req.getPassword()));
            String userId = ((UserDetails) auth.getPrincipal()).getUsername(); // assume ID = username

            // issue access token
            String access = JwtUtil.createAccessToken(userId, accessSecret);

            // issue opaque refresh token
            RefreshToken rt = new RefreshToken();
            rt.setToken(UUID.randomUUID().toString());
            rt.setUserId(Long.valueOf(userId));
            rt.setExpiresAt(Instant.now().plus(30, ChronoUnit.DAYS));
            refreshRepo.save(rt);

            return ResponseEntity.ok(Map.of(
                "access_token", access,
                "refresh_token", rt.getToken()));
        } catch (AuthenticationException ex) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(Map.of("error", "invalid_credentials"));
        }
    }

    @PostMapping("/token")
    public ResponseEntity<?> refresh(@RequestBody Map<String, String> body) {
        String token = body.get("refresh_token");
        if (token == null) {
            return ResponseEntity.badRequest().body(Map.of("error", "missing_token"));
        }

        Optional<RefreshToken> opt = refreshRepo.findByTokenAndRevokedFalseAndExpiresAtAfter(
                token, Instant.now());

        if (opt.isEmpty()) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(Map.of("error", "invalid_refresh"));
        }

        RefreshToken old = opt.get();
        old.setRevoked(true);
        refreshRepo.save(old);

        // new tokens
        String access = JwtUtil.createAccessToken(old.getUserId().toString(), accessSecret);
        RefreshToken newRt = new RefreshToken();
        newRt.setToken(UUID.randomUUID().toString());
        newRt.setUserId(old.getUserId());
        newRt.setExpiresAt(Instant.now().plus(30, ChronoUnit.DAYS));
        refreshRepo.save(newRt);

        return ResponseEntity.ok(Map.of(
                "access_token", access,
                "refresh_token", newRt.getToken()));
    }
}

public class JwtUtil {

    public static String createAccessToken(String subject, String secret) {
        try {
            JWSSigner signer = new MACSigner(secret);
            JWTClaimsSet claims = new JWTClaimsSet.Builder()
                    .subject(subject)
                    .issueTime(new Date())
                    .expirationTime(Date.from(Instant.now().plus(10, ChronoUnit.MINUTES)))
                    .build();

            SignedJWT jwt = new SignedJWT(new JWSHeader(JWSAlgorithm.HS256), claims);
            jwt.sign(signer);
            return jwt.serialize();
        } catch (JOSEException e) {
            throw new RuntimeException(e);
        }
    }
}

./mvnw spring-boot:run

POST /token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=abcd1234&
client_id=mobile-app&
code_verifier=xyz987