Refresh token pattern in NestJS - Deep Dive

Overview - Refresh token pattern

What is it?

The refresh token pattern is a way to keep users logged in securely without asking them to enter their password repeatedly. It uses two tokens: an access token that lets users access resources for a short time, and a refresh token that can get a new access token when the old one expires. This pattern helps balance security and user convenience in web applications. It is commonly used in systems that require user authentication and authorization.

Why it matters

Without the refresh token pattern, users would have to log in again every time their access token expires, which can be annoying and disrupt the user experience. On the other hand, keeping access tokens valid for a long time increases security risks if they get stolen. The refresh token pattern solves this by allowing short-lived access tokens and longer-lived refresh tokens, improving security while keeping users logged in smoothly.

Where it fits

Before learning this, you should understand basic authentication concepts like tokens and JWTs, and how HTTP requests work. After mastering the refresh token pattern, you can explore advanced security topics like token revocation, multi-factor authentication, and secure cookie handling in NestJS.

Mental Model

Core Idea

The refresh token pattern uses a short-lived access token for security and a long-lived refresh token to get new access tokens without bothering the user.

Think of it like...

It's like having a hotel room keycard that expires every day (access token) and a master card (refresh token) that lets you get a new keycard without going back to the front desk every time.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│   Client      │──────▶│ Access Token  │──────▶│  Protected    │
│ (User Agent)  │       │ (Short-lived) │       │   Resource    │
└───────────────┘       └───────────────┘       └───────────────┘
        │                      ▲                       ▲
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        │                      │                       │
        ▼                      │                       │
┌───────────────┐              │                       │
│ Refresh Token │──────────────┘                       │
│ (Long-lived)  │                                      │
└───────────────┘                                      │
        │                                              │
        ▼                                              │
┌───────────────┐                                      │
│ Auth Server   │◀────────────────────────────────────┘
│ Issues new    │
│ Access Token  │
└───────────────┘

Build-Up - 6 Steps

1

Foundation

Understanding Tokens in Authentication

Concept: Tokens are small pieces of data that prove who you are when you use a website or app.

When you log in, the server gives you a token. This token is like a ticket that says you are allowed to use certain parts of the app. Usually, this token is called an access token. It has a time limit and stops working after some time.

Result

You get a token that lets you use the app without typing your password every time, but only for a short time.

Understanding tokens is the first step to knowing how refresh tokens help keep you logged in safely.

2

Foundation

Why Access Tokens Expire Quickly

Concept: Access tokens have short life spans to reduce the risk if someone steals them.

If an access token lasts too long, a thief who gets it can use it to pretend to be you. So, servers make access tokens expire quickly, like 15 minutes or an hour. But this means you need a way to get a new token without logging in again.

Result

Access tokens expire fast, improving security but causing inconvenience if no refresh method exists.

Knowing why access tokens expire helps you see why refresh tokens are needed to keep users logged in smoothly.

3

Intermediate

Introducing the Refresh Token

Concept: A refresh token is a special token that can get new access tokens without asking the user to log in again.

When you log in, the server gives you two tokens: an access token and a refresh token. The access token is short-lived and used to access resources. The refresh token lasts longer and is used only to get new access tokens when the old one expires.

Result

Users stay logged in longer without re-entering credentials, improving user experience.

Understanding the dual-token system is key to balancing security and convenience in authentication.

4

Intermediate

How Refresh Tokens Work in NestJS

🤔Before reading on: do you think refresh tokens are sent with every request or only when access tokens expire? Commit to your answer.

Concept: In NestJS, refresh tokens are stored securely and used only when the access token expires to request a new one from the server.

In a NestJS app, the client stores the refresh token securely (often in an HttpOnly cookie). When the access token expires, the client sends the refresh token to a special endpoint. The server verifies it and issues a new access token. This keeps the user logged in without exposing sensitive data.

Result

Access tokens are refreshed automatically, and users experience seamless authentication.

Knowing when and how refresh tokens are used prevents common security mistakes like sending them with every request.

5

Advanced

Securing Refresh Tokens Properly

🤔Before reading on: do you think storing refresh tokens in localStorage is safe or risky? Commit to your answer.

Concept: Refresh tokens must be stored securely to prevent theft and misuse, often using HttpOnly cookies to avoid JavaScript access.

Storing refresh tokens in localStorage or regular cookies exposes them to cross-site scripting (XSS) attacks. Using HttpOnly cookies means JavaScript cannot read the token, reducing risk. Additionally, refresh tokens should be rotated and invalidated after use to prevent replay attacks.

Result

Refresh tokens are protected from common web attacks, improving overall app security.

Understanding secure storage and rotation of refresh tokens is critical to prevent attackers from hijacking user sessions.

6

Expert

Handling Refresh Token Revocation and Rotation

🤔Before reading on: do you think refresh tokens should be reusable indefinitely or replaced after each use? Commit to your answer.

Concept: Refresh token rotation means issuing a new refresh token every time the old one is used, and revocation means invalidating tokens when needed to prevent misuse.

In production, refresh tokens are rotated: when a client uses a refresh token to get a new access token, the server also issues a new refresh token and invalidates the old one. This prevents stolen tokens from being reused. Revocation lists or databases track invalid tokens to block compromised tokens. NestJS apps implement this with token storage and validation logic.

Result

Refresh tokens become one-time use, greatly reducing the risk of token theft leading to long-term access.

Knowing how to implement rotation and revocation protects users from advanced attacks and is a hallmark of secure authentication systems.

Under the Hood

When a user logs in, the server creates two tokens: a short-lived access token and a long-lived refresh token. The access token contains user info and permissions, signed cryptographically, and is sent with each request to protected resources. When it expires, the client sends the refresh token to a special endpoint. The server verifies the refresh token's validity, checks it against stored records or revocation lists, and if valid, issues a new access token (and often a new refresh token). This cycle continues until the refresh token expires or is revoked.

Why designed this way?

This pattern was designed to improve security by limiting the lifetime of access tokens, reducing the window for attackers. At the same time, it improves user experience by avoiding frequent logins. Alternatives like long-lived access tokens or session cookies either risk security or user convenience. The refresh token pattern balances these needs and fits well with stateless authentication systems like JWT.

┌───────────────┐          ┌───────────────┐          ┌───────────────┐
│   Client      │          │ Auth Server   │          │ Resource      │
│ (Browser/App) │          │               │          │ Server/API    │
└───────┬───────┘          └───────┬───────┘          └───────┬───────┘
        │                           │                           │
        │ 1. Login request          │                           │
        ├──────────────────────────▶                           │
        │                           │                           │
        │                           │ 2. Issue access & refresh │
        │                           ├──────────────────────────▶│
        │                           │                           │
        │ 3. Send tokens            │                           │
        ◀──────────────────────────┤                           │
        │                           │                           │
        │ 4. Access protected API   │                           │
        ├──────────────────────────▶                           │
        │                           │                           │
        │                           │ 5. Validate access token   │
        │                           ├──────────────────────────▶│
        │                           │                           │
        │                           │ 6. Respond with data       │
        │                           ◀──────────────────────────┤
        │                           │                           │
        │ 7. Access token expired   │                           │
        │ 8. Send refresh token     │                           │
        ├──────────────────────────▶                           │
        │                           │                           │
        │                           │ 9. Validate refresh token  │
        │                           ├──────────────────────────▶│
        │                           │                           │
        │                           │ 10. Issue new access token │
        │                           │                           │
        │                           ◀──────────────────────────┤
        │ 11. Use new access token  │                           │

Myth Busters - 4 Common Misconceptions

Quick: Do you think refresh tokens should be sent with every API request? Commit to yes or no.

Common Belief: Refresh tokens are sent with every request just like access tokens.

Reality: Refresh tokens are only sent when the access token expires to get a new access token, not with every request.

Why it matters: Sending refresh tokens with every request increases the risk of theft and misuse, weakening security.

Quick: Do you think storing refresh tokens in localStorage is safe? Commit to yes or no.

Common Belief: Storing refresh tokens in localStorage is safe and convenient.

Reality: LocalStorage is vulnerable to cross-site scripting (XSS) attacks, so storing refresh tokens there is risky.

Why it matters: If attackers steal refresh tokens from localStorage, they can impersonate users for a long time.

Quick: Do you think refresh tokens can be reused indefinitely without risk? Commit to yes or no.

Common Belief: Refresh tokens can be reused many times without problems.

Reality: Refresh tokens should be rotated and invalidated after use to prevent replay attacks.

Why it matters: Reusing refresh tokens without rotation allows attackers to reuse stolen tokens and gain unauthorized access.

Quick: Do you think refresh tokens are always stored server-side? Commit to yes or no.

Common Belief: Refresh tokens must always be stored on the server to work.

Reality: Refresh tokens are usually stored client-side securely (e.g., HttpOnly cookies), but servers keep track of them for validation and revocation.

Why it matters: Misunderstanding storage leads to insecure implementations or unnecessary server-side state.

Expert Zone

1

Refresh token rotation is a subtle but powerful defense against token theft, requiring careful implementation to avoid locking out legitimate users.

2

Using HttpOnly and Secure flags on cookies for refresh tokens prevents JavaScript access and ensures tokens are sent only over HTTPS, reducing attack surface.

3

Implementing refresh token revocation lists or databases adds complexity but is essential for handling logout and compromised tokens in production.

When NOT to use

The refresh token pattern is not suitable for very short-lived sessions or public clients that cannot securely store tokens. Alternatives include using short-lived access tokens only or OAuth 2.0 implicit flow for public clients.

Production Patterns

In real NestJS apps, refresh tokens are often stored in HttpOnly cookies with Secure and SameSite flags. The backend uses guards and interceptors to check tokens. Rotation and revocation are implemented with token databases or Redis. Refresh endpoints are protected against brute force and abuse.

Connections

OAuth 2.0 Authorization Framework

The refresh token pattern is a core part of OAuth 2.0 flows for delegated authorization.

Understanding refresh tokens helps grasp how OAuth 2.0 manages long-lived access securely across different clients.

Session Management in Web Applications

Refresh tokens provide a stateless alternative to traditional server-side sessions.

Knowing refresh tokens clarifies how modern apps maintain user sessions without storing state on servers.

Physical Security Tokens (e.g., Key Cards)

Both use a short-term access method combined with a longer-term master key to control access.

Recognizing this pattern across digital and physical security deepens understanding of layered access control.

Common Pitfalls

#1 Sending refresh tokens with every API request.

Wrong approach:

fetch('/api/data', { headers: { Authorization: 'Bearer accessToken', 'x-refresh-token': 'refreshToken' } })

Correct approach:

fetch('/api/data', { headers: { Authorization: 'Bearer accessToken' } })
// Only send refresh token when access token expires to refresh it

Root cause:

Misunderstanding that refresh tokens are only for renewing access tokens, not for every request.

#2 Storing refresh tokens in localStorage.

Wrong approach:

localStorage.setItem('refreshToken', token);

Correct approach:

Set refresh token in HttpOnly, Secure cookie from server response headers.

Root cause:

Lack of awareness about XSS vulnerabilities and secure storage best practices.

#3 Not rotating refresh tokens after use.

Wrong approach:

Allow reuse of the same refresh token indefinitely without issuing a new one.

Correct approach:

Issue a new refresh token every time the old one is used and invalidate the old token.

Root cause:

Ignoring replay attack risks and token lifecycle management.

Key Takeaways

The refresh token pattern uses two tokens to balance security and user convenience: short-lived access tokens and long-lived refresh tokens.

Access tokens expire quickly to reduce risk, while refresh tokens allow seamless renewal without bothering users to log in again.

Refresh tokens must be stored securely, typically in HttpOnly cookies, to prevent theft via web attacks.

Rotation and revocation of refresh tokens are essential to prevent misuse if tokens are stolen.

Understanding and implementing this pattern correctly is critical for building secure, user-friendly authentication in NestJS applications.