Edit: Implementing JWT Authentication in Node…

Posts›Implementing JWT Authentication in Node…

PublishedView Live →

Title

Slug

Preview: https://jwtsecretgenerator.com/blog/implementing-jwt-authentication-in-nodejs

⚠ Changing the slug will break existing links to this post.

Description / Excerpt

142 / 180 characters

Content (Markdown)

## Why JWT Authentication in Node.js Needs More Than `jwt.sign`

JSON Web Tokens carry authenticated identity between clients and Node.js APIs, but most JWT breaches come from weak secrets, missing claim validation, unsafe token storage, or refresh flows that never rotate credentials. This guide covers a threat-aware implementation with `jsonwebtoken` or `jose`, using JavaScript and TypeScript examples for Express, Fastify, or NestJS.

Generate a signing key with the [JWT Secret Generator](/tools/jwt-secret-generator) and review [HS256 vs RS256](/compare/hs256-vs-rs256) before choosing an algorithm.

## Threat Model: What You Are Defending Against

Assume attackers can steal tokens from browser storage, replay refresh tokens, and forge JWTs if they obtain your [JWT secret](/glossary/jwt-secret). Your service must enforce:

- **Key confidentiality** — load secrets from env or a vault ([Env Vars vs Vault](/compare/env-vars-vs-vault)).
- **Signature integrity** — verify on every request; decoding alone proves nothing ([JWT Validator](/tools/jwt-validator)).
- **Algorithm pinning** — reject unexpected `alg` values, including `none`.
- **Claim binding** — validate `iss`, `aud`, and `exp` so tokens for other services cannot replay here.
- **Session lifecycle** — short [access tokens](/glossary/access-token) plus rotated [refresh tokens](/glossary/refresh-token) ([Access Token vs Refresh Token](/compare/access-token-vs-refresh-token)).

JWT alone does not stop XSS or CSRF; use HttpOnly cookies, SameSite, CSP, and separate authorization checks. Treat every access token as a bearer credential: anyone holding it can act as that user until expiry or revocation, so minimize what you embed in the payload and never store passwords or payment data in claims ([JWT](/glossary/jwt) payloads are only base64-encoded, not encrypted).

## Project Setup and Configuration

```bash
npm install jsonwebtoken cookie-parser
npm install -D typescript @types/jsonwebtoken @types/cookie-parser
```

Load secrets from the environment per the [Node.js secret guide](/guides/jwt-secret-generator/nodejs):

```javascript
const JWT_SECRET = process.env.JWT_SECRET;
const JWT_ISSUER = process.env.JWT_ISSUER ?? 'https://api.example.com';
const JWT_AUDIENCE = process.env.JWT_AUDIENCE ?? 'https://app.example.com';

if (!JWT_SECRET || JWT_SECRET.length < 32) {
  throw new Error('JWT_SECRET must be at least 256 bits');
}
```

TypeScript interfaces keep claim shapes explicit:

```typescript
export interface AccessTokenClaims {
  sub: string;
  role: 'user' | 'admin';
  typ: 'access';
}
```

## Issuing and Verifying Access Tokens

```javascript
function signAccessToken(user) {
  return jwt.sign(
    { sub: user.id, role: user.role, typ: 'access' },
    JWT_SECRET,
    { algorithm: 'HS256', expiresIn: '15m', issuer: JWT_ISSUER, audience: JWT_AUDIENCE }
  );
}
```

Pin algorithm, issuer, and audience on every verify call:

```typescript
export function verifyAccessToken(token: string): AccessTokenClaims {
  const payload = jwt.verify(token, JWT_SECRET, {
    algorithms: ['HS256'],
    issuer: JWT_ISSUER,
    audience: JWT_AUDIENCE,
  }) as jwt.JwtPayload & AccessTokenClaims;

if (payload.typ !== 'access') throw new jwt.JsonWebTokenError('Invalid token type');
  return payload;
}
```

With `jose`, pass the same constraints to `jwtVerify` — never trust decoded JSON without cryptographic verification.

## Refresh Token Flow Outline

1. User authenticates; server creates a session record.
2. Server returns a 15-minute access token and sets a refresh token in an HttpOnly cookie.
3. On expiry, client calls `POST /auth/refresh`; server validates refresh token, checks `jti` against a denylist, rotates refresh token, and issues a new access token.
4. On logout, revoke `jti` and clear the cookie.

Store refresh token hashes server-side; treat plaintext values like passwords.

## Cookie Settings for Browser Clients

Misconfigured cookies are a top production failure ([LocalStorage vs Cookies](/compare/localstorage-vs-cookies-jwt)):

```javascript
res.cookie('refresh_token', refreshToken, {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'strict',
  path: '/auth/refresh',
  maxAge: 7 * 24 * 60 * 60 * 1000,
});
```

Never expose refresh tokens to JavaScript. Keep access tokens in memory with short TTLs rather than `localStorage`.

## Protected Routes, Error Handling, and Middleware

```javascript
function requireAuth(req, res, next) {
  const header = req.headers.authorization;
  if (!header?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'missing_token' });
  }
  try {
    req.user = verifyAccessToken(header.slice(7));
    return next();
  } catch (err) {
    const code = err.name === 'TokenExpiredError' ? 'token_expired' : 'invalid_token';
    return res.status(401).json({ error: code });
  }
}

app.get('/api/profile', requireAuth, (req, res) => {
  res.json({ userId: req.user.sub, role: req.user.role });
});
```

Map verification failures to stable 401 responses; return 403 when the token is valid but roles are insufficient. A consistent error contract helps clients distinguish expired tokens (trigger refresh) from invalid ones (force re-login):

| Condition | HTTP | Error code |
|-----------|------|------------|
| Missing Bearer header | 401 | `missing_token` |
| Expired signature | 401 | `token_expired` |
| Bad signature or wrong aud/iss | 401 | `invalid_token` |
| Valid token, wrong role | 403 | `forbidden` |

Log correlation IDs, never raw tokens or stack traces. Add `requireRole('admin')` after `requireAuth` for authorization.

## Common Pitfalls

- **Trusting decoded payloads** — verify signatures ([Bearer Token](/glossary/bearer-token) proof is mandatory).
- **Using `jwt.decode()` in auth middleware** — `decode()` does not check the signature at all. It is only for inspecting already-verified tokens. Authentication must call `jwt.verify()` (or `jose.jwtVerify`) with an algorithm allowlist.
- **Omitting `{ algorithms: ['HS256'] }`** — without an allowlist, libraries may accept whatever `alg` is in the header, including `none` or algorithm-confusion tricks.
- **Skipping `aud` and `iss`** — breaks multi-service and multi-tenant setups.
- **Accepting `alg: none`** — always pass an algorithm allowlist.
- **Long-lived access tokens** — use 15–60 minute [token expiration](/glossary/token-expiration) with refresh for UX.
- **Same secret across environments** — isolate and rotate per stage.

Debug with the [JWT Encoder](/tools/jwt-encoder) on non-production keys only.

## Production Checklist

- [ ] 256-bit+ CSPRNG secret in env or vault, never in git
- [ ] `algorithms`, `iss`, `aud`, `exp`, and `sub` validated on every request
- [ ] Custom `typ` claim separates access from refresh tokens
- [ ] Refresh rotation with server-side `jti` tracking
- [ ] HttpOnly, Secure, SameSite cookies for refresh tokens
- [ ] Uniform 401/403 responses; rate limit `/auth/login` and `/auth/refresh`
- [ ] Secret rotation plan with `kid` header support

See [JWT Best Practices](/blog/jwt-best-practices-checklist) and [JWT vs Session](/compare/jwt-vs-session) for broader architecture decisions.

## Frequently Asked Questions

### Should I use jsonwebtoken or jose in Node.js?

Both work in production. `jsonwebtoken` is ubiquitous; `jose` offers modern Web Crypto APIs and strong TypeScript support. Either way, pin algorithms and validate `iss`/`aud` explicitly.

### Where should SPAs store access tokens?

Prefer in-memory storage with silent refresh via HttpOnly cookies. `localStorage` survives XSS and lets attackers exfiltrate tokens easily.

### Do I need refresh tokens if access tokens expire in 15 minutes?

Yes, for browser sessions users expect persistence. Refresh tokens keep access tokens short while allowing server-side revocation via session records.

### When should I switch from HS256 to RS256?

When multiple services verify tokens but only one signs them. RS256 lets verifiers hold a public key only; monoliths often stay on [HS256](/glossary/hs256) with a strong secret ([HS256 vs RS256](/compare/hs256-vs-rs256)).

### How do I invalidate a JWT before it expires in Node.js?

JWTs are stateless — you cannot invalidate them without a server-side store. Practical approaches: (1) keep access token lifetimes short (15 minutes) so leaks self-expire; (2) maintain a Redis (or DB) blocklist keyed by `jti` and check it on every request; (3) rotate refresh sessions server-side so stolen access tokens cannot be renewed.

1139 words · ~6 min readMarkdown guide →

Tags (5/8)

jwtnodejsauthenticationsecuritytypescript

Author Name

Status

Cover Image URL (optional)

Danger Zone

Deleting this post sets its status to "deleted". It can be recovered via the API.