Topic

JSON Web Tokens (JWT)

Definition

A JSON Web Token (JWT) is a compact, signed token that encodes claims about an authenticated subject so a server can verify identity without querying a session store on every request.

In simpler words

A JWT is a signed ID card: once someone logs in, the server hands them a token that proves who they are without looking anything up again for every request.

In a Nest API, JWTs are typically issued on login and read from an httpOnly cookie on every request. Bearer-header JWTs are the same token format used by mobile apps and API tooling — a useful mental model even though the browser flow here relies on cookies.

Open official example (opens in new tab)

After this you can

Trace a JWT from login to a request that reuses it
Explain why the payload stays small (sub, email, role)
Compare cookie transport with the bearer-header mental model

How a Nest API issues and reads a JWT

Definition

AuthService.login verifies credentials, asks JwtService.signAsync for a signed token carrying sub, email, and role, and stores that token in an httpOnly access_token cookie; JwtStrategy later extracts and verifies the same token on every request.

In simpler words

Login proves identity once; the cookie carries a compact, tamper-evident version of that decision on every following request.

The signature (not encryption) is what makes a JWT trustworthy: the server can detect any edit to the payload, but the payload itself is base64, not secret.

Because verification only needs the signing secret, Nest can authenticate a request without a database round trip for the token itself — it still loads the user record to get the current role and confirm the account still exists.

Issuing the token

const token = await this.jwtService.signAsync({
  sub: user.id,
  email: user.email,
  role: user.role,
});

res.cookie(AUTH_COOKIE_NAME, token, {
  httpOnly: true,
  secure: this.env.COOKIE_SECURE,
  sameSite: 'lax',
  path: '/',
  maxAge: 7 * 24 * 60 * 60 * 1000,
});

Only sub, email, and role travel in the token — enough to authorize, not a full user profile.

Cookie session here, bearer header as the wider mental model

Definition

Cookie-based JWT delivery lets the browser attach the token automatically on same-site credentialed requests, while bearer-header delivery requires the client to read the token and set an Authorization: Bearer header on every request.

In simpler words

The browser never touches the token string here; other JWT clients — mobile apps, curl, Swagger — typically carry the same token by hand in a header.

A JwtStrategy can accept both: it tries the access_token cookie first, then falls back to an Authorization Bearer header — that fallback exists mainly for Swagger and tooling, not for the web app.

A cookie flow needs credentials: true on both the client and Nest CORS; a bearer flow needs the client to store and attach the token itself, which is exactly what an httpOnly cookie is designed to avoid.

Dual extractor

jwtFromRequest: ExtractJwt.fromExtractors([
  cookieExtractor,
  ExtractJwt.fromAuthHeaderAsBearerToken(),
]),

Cookie wins when present; bearer is the fallback used by Swagger’s Authorize flow and other non-browser clients.

Signed ≠ encrypted; expiry and CSRF notes

Definition

A JWT signature proves integrity and authenticity of the claims under a shared secret (or private key); it does not hide the payload. Cookie-based APIs must also consider cross-site request risks.

In simpler words

Anyone can decode the payload; only the server with the secret can forge a valid signature. Treat claims as public-ish, not secret.

Do not put passwords, tokens, or PII beyond what the API truly needs in the JWT. Prefer ids and role.

Expiry (exp) bounds damage if a token leaks. This course uses a multi-day cookie maxAge — production teams often shorten access tokens and add refresh flows.

httpOnly + Secure (in HTTPS) + SameSite=Lax/Strict reduces XSS token theft and some CSRF classes. State-changing cookie APIs still need CSRF strategy when cross-site posts are possible.

@Public() routes skip JwtAuthGuard — only mark truly public endpoints (login, health, register).

Mistake: localStorage JWT

// Wrong — any XSS can steal the token
localStorage.setItem('token', jwt);

// Right — httpOnly cookie set by Nest
res.cookie(AUTH_COOKIE_NAME, token, { httpOnly: true, sameSite: 'lax', secure });

If JavaScript can read the credential, an XSS bug becomes a session theft bug.

Mistake: huge JWT payload

// Wrong — entire user profile + permissions tree in the token
signAsync({ ...userEntity, permissions: fullTree })

// Right — minimal claims; load fresh user/role server-side when needed
signAsync({ sub: user.id, email: user.email, role: user.role })

Large tokens bloat every request and go stale when roles change; here the user record is reloaded in JwtStrategy.

Keep in mind

Keep JWT payloads small and non-sensitive — sub, email, role, nothing else.
Treat the cookie as the transport used here; the bearer header is the same token format used elsewhere.
Never store a JWT in localStorage when an httpOnly cookie is available.
Signed means tamper-evident, not secret — do not put secrets in claims.

Test

Check your understanding

At least 10 questions — mix of concept, syntax, practical, and logic. Score ≥80% (enforced by the API) to save progress.

Checking your session…

15 questions · concept 5 · syntax 3 · practical 4 · logic 3

1. What is the access token in this API?

Concept

A server session id looked up in Postgres every requestThe plaintext password resent on every requestAn encrypted blob only the frontend can decodeA signed JWT carrying sub/email/role, stored in an httpOnly cookie

2. Who verifies the JWT on requests?

Syntax

ValidationPipe, since the token is validated like any DTOCorrelationIdMiddleware, which reads the cookie before guards runThe AuthService.login method on every subsequent requestJwtStrategy / JwtAuthGuard validating the token

3. Can bearer auth still work here?

Practical

No — the custom cookie extractor replaces all built-in header extractionOnly if you disable the httpOnly cookie flag firstYes — JwtStrategy also accepts a bearer header as a fallbackOnly after registering a separate BearerStrategy in Passport

4. Why httpOnly for the cookie?

Logic

It encrypts the cookie value so its contents cannot be decodedIt stops the cookie being sent on cross-site requests, blocking CSRFIt signs the cookie so the server can detect tamperingJavaScript on the page cannot read the token, reducing XSS theft risk

5. What claims are signed into the token here?

Concept

sub, email, role, plus the bcrypt password hashOnly sub and email; role is fetched from the database insteadsub, email, and rolesub and role only, omitting the email claim

6. Is a JWT the same as encrypting the whole user row?

Practical

Yes — the payload is encrypted so only the server with the secret can read itYes — signing and encrypting are the same operation for a JWTYes — the token embeds the full user row so no DB lookup is ever neededNo — it is typically signed claims, not a full encrypted user document for the client to decrypt

7. What happens on login success?

Syntax

AuthService returns the JWT in the JSON body for the client to storeAuthService creates a server-side session row and returns its idAuthService sets the refresh_token cookie but not the access_tokenAuthService signs a JWT and sets the access_token cookie

8. What should logout do?

Logic

Rotate the JWT signing secret for every userDelete the user row from PostgresAdd the token to a server-side allowlistClear the auth cookie

9. Why not store JWT in localStorage for this course API?

Concept

localStorage has a strict 4KB limit that a JWT would exceedBrowsers auto-attach localStorage values to every request, unlike cookiesPrefer httpOnly cookies to keep tokens away from XSS-accessible storagelocalStorage is shared across all origins, leaking the token

10. What does an expired JWT produce on guarded routes?

Practical

401 Unauthorized after verification fails403 Forbidden, since the credential is no longer permitted200 with a refreshed token issued automatically419 Session Expired returned by the guard

11. Which value keeps this auth cookie unreadable by page JavaScript?

Conceptintermediate

res.cookie('access_token', token, {
  httpOnly: ???,
  sameSite: 'lax',
});

httpOnly: false so the SPA can read the tokensecure: false, which controls JS accesssameSite: none, which hides it from JShttpOnly: true

12. What does the signed token contain after this call?

Syntaxintermediate

this.jwt.sign({ sub: user.id, email: user.email, role: user.role });

An encrypted blob only the server can readThe bcrypt password hash of the userA signed payload with sub, email, and role claims (not encrypted)Only the user id; the other fields are dropped

13. What is this jwtFromRequest configuration doing?

Practicaladvanced

ExtractJwt.fromExtractors([
  (req) => req?.cookies?.access_token,
]);

Encrypting the cookie before verificationRejecting any request that sends a bearer headerReading the JWT from the access_token cookie instead of the Authorization headerSigning a new token on every request

14. What belongs in the logout handler to end the session?

Logicintermediate

@Post('logout')
logout(@Res({ passthrough: true }) res: Response) {
  // ?
  return { ok: true };
}

res.cookie the same token with a longer maxAgeDelete the user row from PostgresCall this.jwt.sign(null) to blank the tokenres.clearCookie('access_token')

15. A token was signed with expiresIn 15m; a guarded request arrives 20 minutes later. What does the guard return?

Conceptadvanced

this.jwt.sign(payload, { expiresIn: '15m' });
// 20 minutes later, a guarded request arrives

401 Unauthorized, because the token has expired and verification fails200, because the cookie is still present403 Forbidden, because the role is wrong500, because expiry throws an unhandled error

Checking your session…