# Oauth2 JWT

> Implements OAuth 2.0 authentication and JWT-based authorization with refresh tokens. Use for secure API access.

- Skill: `ssrjkk/oauth2-jwt` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ssrjkk/oauth2-jwt`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ssrjkk/oauth2-jwt/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: ssrjkk (https://skillmd.com/u/ssrjkk)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/ssrjkk/oauth2-jwt

---

# OAuth2 & JWT

> Secure API authentication with OAuth 2.0 and JSON Web Tokens.

## Quick Start
```typescript
import jwt from 'jsonwebtoken';
import bcrypt from 'bcrypt';

// Login
const user = await db.user.findUnique({ where: { email } });
const valid = await bcrypt.compare(password, user.password);
if (!valid) throw new Error('Invalid credentials');

// Generate tokens
const accessToken = jwt.sign(
  { userId: user.id, role: user.role },
  process.env.JWT_SECRET!,
  { expiresIn: '15m' }
);
const refreshToken = jwt.sign(
  { userId: user.id },
  process.env.JWT_REFRESH_SECRET!,
  { expiresIn: '7d' }
);

// Middleware
function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.split(' ')[1];
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET!);
    req.user = decoded;
    next();
  } catch {
    res.status(401).json({ error: 'Invalid token' });
  }
}
```

## When to Use
- API authentication and authorization
- Single sign-on (SSO) with OAuth providers
- Not for server-to-server with API keys

## Step-by-Step Instructions
1. Install packages: `npm install jsonwebtoken bcrypt`
2. Set up user model with hashed passwords
3. Create login endpoint returning access + refresh tokens
4. Add auth middleware to protected routes

## Dependencies
```bash
npm install jsonwebtoken bcrypt
# For OAuth providers: passport, passport-google-oauth20, etc.
```

## Examples
Input: Login with email/password → Output: `{ accessToken, refreshToken, expiresIn }`

## Resources
- [JWT.io](https://jwt.io/)
- [OAuth 2.0 Spec](https://oauth.net/2/)
- [Examples](./examples/)

## Troubleshooting
- **JWT `kid` mismatch** — the signing key rotated but the client cached
  the old JWKS. Refresh the key set and honor `cache-control` on the JWKS.
- **`exp` claims rejected after a clock skew** — allow leeway (~30s) on
  verification and compare with the issuer's `nbf`/`iat`, not wall time.
- **Audience leaks cross-app** — tokens minted for one audience validate
  elsewhere. Pin `aud` per client and reject tokens without an `aud` claim.
- **Refresh tokens stolen in localStorage** — never store them in the
  browser. Use httpOnly, SameSite cookies or a backend session.

## Validation
1. Tokens sign and verify correctly
2. Expired tokens are rejected
3. Refresh tokens issue new access tokens