OAuth2 & JWT Complete Guide: Everything About Authentication and Authorization for Developers

Airport Security Check:

1. Authentication: Passport verification
   - "Is this person really John Doe?"
   - Identity verified with passport (password)

2. Authorization: Boarding pass check
   - "Can John Doe board this flight?"
   - Access scope determined by boarding pass (permissions)
   - Business lounge access? Economy boarding?

Incorrect: "OAuth2 is an authentication protocol"  (X)
Correct:   "OAuth2 is an authorization framework"   (O)

OAuth2 itself does not answer "Who are you?"
If you need authentication, use OIDC (OpenID Connect) on top of OAuth2.

Flow:
1. User logs in (ID/PW)
2. Server creates session (server memory or Redis)
3. Session ID sent to client as cookie
4. Every request includes session ID via cookie
5. Server looks up user info from session store

// Express + express-session example
const session = require('express-session')
const RedisStore = require('connect-redis').default
const redis = require('redis')

const redisClient = redis.createClient()

app.use(
  session({
    store: new RedisStore({ client: redisClient }),
    secret: process.env.SESSION_SECRET,
    resave: false,
    saveUninitialized: false,
    cookie: {
      secure: true, // HTTPS only
      httpOnly: true, // Block JavaScript access
      maxAge: 24 * 60 * 60 * 1000, // 24 hours
      sameSite: 'lax', // CSRF prevention
    },
  })
)

// Login
app.post('/login', async (req, res) => {
  const user = await authenticateUser(req.body.email, req.body.password)
  if (!user) return res.status(401).json({ error: 'Invalid credentials' })

  req.session.userId = user.id
  req.session.role = user.role
  res.json({ message: 'Logged in successfully' })
})

// Auth middleware
function requireAuth(req, res, next) {
  if (!req.session.userId) {
    return res.status(401).json({ error: 'Authentication required' })
  }
  next()
}

Flow:
1. User logs in (ID/PW)
2. Server creates and signs JWT
3. JWT sent to client
4. Every request includes JWT in Authorization header
5. Server verifies JWT signature (no session store needed)

Use Sessions when:
  - Traditional server-side rendered web apps (MPA)
  - Instant session revocation is critical
  - Single server or few servers

Use Tokens (JWT) when:
  - SPA (React, Vue, Angular)
  - Mobile apps
  - Microservices architecture
  - Third-party API access
  - Serverless environments

1. Resource Owner
   -> The user themselves. "The entity that grants access to my data"

2. Client
   -> The application requesting access. "The app that needs user data"

3. Authorization Server
   -> Authenticates users and issues tokens. "Google, GitHub, Keycloak, etc."

4. Resource Server
   -> Hosts protected resources. "The API server"

Step-by-step flow:

1. Client -> Auth Server (Authorization Request)
   GET /authorize?
     response_type=code&
     client_id=CLIENT_ID&
     redirect_uri=https://app.example.com/callback&
     scope=read write&
     state=random_csrf_token

2. User logs in and consents at Authorization Server

3. Auth Server -> Client (Authorization Code)
   302 Redirect: https://app.example.com/callback?
     code=AUTHORIZATION_CODE&
     state=random_csrf_token

4. Client -> Auth Server (Token Exchange) [back channel, server-to-server]
   POST /token
     grant_type=authorization_code&
     code=AUTHORIZATION_CODE&
     redirect_uri=https://app.example.com/callback&
     client_id=CLIENT_ID&
     client_secret=CLIENT_SECRET

5. Auth Server -> Client (Token Response)
   {
     "access_token": "eyJhbGciOiJSUzI...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "dGhpcyBpcyBhIHJl...",
     "scope": "read write"
   }

Additional PKCE steps:

1. Client generates code_verifier (43-128 char random string)
2. code_challenge = Base64URL(SHA256(code_verifier))
3. Include code_challenge + code_challenge_method=S256 in auth request
4. Send code_verifier during token exchange (server verifies)

// PKCE Implementation (JavaScript)
function generateCodeVerifier() {
  const array = new Uint8Array(32)
  crypto.getRandomValues(array)
  return base64URLEncode(array)
}

async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder()
  const data = encoder.encode(verifier)
  const digest = await crypto.subtle.digest('SHA-256', data)
  return base64URLEncode(new Uint8Array(digest))
}

function base64URLEncode(buffer) {
  return btoa(String.fromCharCode(...buffer))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g, '')
}

// Usage
const codeVerifier = generateCodeVerifier()
const codeChallenge = await generateCodeChallenge(codeVerifier)

// Authorization request
const authUrl =
  `https://auth.example.com/authorize?` +
  `response_type=code&` +
  `client_id=CLIENT_ID&` +
  `redirect_uri=https://app.example.com/callback&` +
  `scope=openid profile email&` +
  `code_challenge=${codeChallenge}&` +
  `code_challenge_method=S256&` +
  `state=${generateState()}`

Steps:

1. Client -> Auth Server (Direct Token Request)
   POST /token
     grant_type=client_credentials&
     client_id=SERVICE_A_ID&
     client_secret=SERVICE_A_SECRET&
     scope=api.read

2. Auth Server -> Client (Access Token)
   {
     "access_token": "eyJhbGciOiJSUzI...",
     "token_type": "Bearer",
     "expires_in": 3600
   }
   (No Refresh Token -- request again on expiry)

# Python Client Credentials request
import requests

response = requests.post('https://auth.example.com/token', data={
    'grant_type': 'client_credentials',
    'client_id': 'service-a',
    'client_secret': 'secret-value',
    'scope': 'api.read api.write',
})

token = response.json()['access_token']

Steps:

1. Device -> Auth Server (Device Code Request)
   POST /device/code
     client_id=TV_APP_ID&scope=openid profile

2. Auth Server -> Device (Device Code + User Code)
   {
     "device_code": "DEVICE_CODE_HERE",
     "user_code": "ABCD-1234",
     "verification_uri": "https://auth.example.com/device",
     "expires_in": 1800,
     "interval": 5
   }

3. Device displays: "Go to https://auth.example.com/device and enter ABCD-1234"

4. User visits URL on another device (phone, PC) -> enters code -> logs in -> consents

5. Device polls for token periodically
   POST /token
     grant_type=urn:ietf:params:oauth:grant-type:device_code&
     device_code=DEVICE_CODE_HERE&
     client_id=TV_APP_ID

6. Receives Access Token after authorization

Why Implicit Flow was deprecated:

1. Access Token exposed in URL Fragment (#access_token=...)
2. Token recorded in browser history
3. Token leakage via Referrer headers
4. Vulnerable to token theft attacks
5. Cannot use Refresh Tokens

Alternative: Authorization Code + PKCE
   -> Browser-based apps should use this approach.
   -> Implicit Flow officially removed in OAuth 2.1 draft

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.
eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.
POstGetfAytaZS82wHcjoTyoqhMyxXiWdR7Nn7A29DNSl0EiXLdwJ6xC6AfgZWF1bOsS...

[Header].[Payload].[Signature]

Header (Base64URL):
{
  "alg": "RS256",    // Signing algorithm
  "typ": "JWT",      // Token type
  "kid": "key-id-1"  // Key ID (for key rotation)
}

Payload (Base64URL):
{
  "sub": "1234567890",     // Subject (User ID)
  "name": "John Doe",
  "email": "john@example.com",
  "role": "admin",
  "iss": "https://auth.example.com",  // Issuer
  "aud": "https://api.example.com",   // Audience
  "iat": 1516239022,       // Issued At
  "exp": 1516242622,       // Expiration
  "jti": "unique-token-id" // JWT ID (unique identifier)
}

Signature:
RSASHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  privateKey
)

HS256 vs RS256:

HS256 (Symmetric):
  - Sign: Sign with secretKey
  - Verify: Verify with same secretKey
  - Problem: All services must know secretKey -> leak risk

RS256 (Asymmetric):
  - Sign: Sign with privateKey (only auth server has it)
  - Verify: Verify with publicKey (anyone can)
  - Advantage: Other services can verify tokens without privateKey exposure
  - Recommended: Microservices environments

// Node.js JWT verification (jsonwebtoken)
const jwt = require('jsonwebtoken')
const jwksClient = require('jwks-rsa')

// Get public key from JWKS (JSON Web Key Set)
const client = jwksClient({
  jwksUri: 'https://auth.example.com/.well-known/jwks.json',
  cache: true,
  rateLimit: true,
})

function getSigningKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    if (err) return callback(err)
    callback(null, key.getPublicKey())
  })
}

// JWT verification middleware
function verifyToken(req, res, next) {
  const authHeader = req.headers.authorization
  if (!authHeader?.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Missing token' })
  }

  const token = authHeader.substring(7)

  jwt.verify(
    token,
    getSigningKey,
    {
      algorithms: ['RS256'],
      issuer: 'https://auth.example.com',
      audience: 'https://api.example.com',
    },
    (err, decoded) => {
      if (err) {
        if (err.name === 'TokenExpiredError') {
          return res.status(401).json({ error: 'Token expired' })
        }
        return res.status(401).json({ error: 'Invalid token' })
      }
      req.user = decoded
      next()
    }
  )
}

Never do:
  1. Store passwords or PII in JWT payload (Base64 is NOT encryption!)
  2. Allow "alg": "none" (accept unsigned tokens)
  3. Ignore algorithm confusion attacks (RS256 -> HS256 downgrade)
  4. Issue tokens without exp claim (eternally valid tokens)
  5. Grow token size indefinitely (sent with every request)

Always do:
  1. Always verify signatures (fix algorithm)
  2. Validate exp, iss, aud claims
  3. Use HTTPS only
  4. Set appropriate expiration times
  5. Include only minimum necessary claims

Access Token:
  - Short lifespan: 15 min to 1 hour
  - Used for every API request
  - Renewed with Refresh Token when expired

Refresh Token:
  - Long lifespan: 7 days to 30 days
  - Used only to renew Access Tokens
  - Protected more strictly

1. Client makes API request with Access Token
2. Server returns 401 (token expired)
3. Client requests new Access Token with Refresh Token
   POST /token
     grant_type=refresh_token&
     refresh_token=REFRESH_TOKEN_VALUE&
     client_id=CLIENT_ID
4. Server returns new Access Token (+ new Refresh Token)
5. Client retries with new Access Token

// Recommended: Store tokens in httpOnly cookies (server-side)
res.cookie('access_token', accessToken, {
  httpOnly: true, // No JavaScript access
  secure: true, // HTTPS only
  sameSite: 'lax', // CSRF prevention
  maxAge: 15 * 60 * 1000, // 15 minutes
  path: '/',
})

res.cookie('refresh_token', refreshToken, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
  path: '/api/auth/refresh', // Only sent to refresh endpoint
})

Standard approach:
  Refresh Token A -> New Access Token issued (Refresh Token A kept)
  Problem: If Refresh Token is stolen, attacker can keep using it

Rotation approach:
  Refresh Token A -> New Access Token + New Refresh Token B issued
                     (Refresh Token A invalidated)
  Benefit: Immediate detection if stolen Refresh Token is used

Detection mechanism:
  1. Request comes with already-used Refresh Token A
  2. Server: "This token was already rotated -> possible theft!"
  3. Invalidate ALL Refresh Tokens for that user
  4. Require user to re-login

// Refresh Token Rotation implementation
async function refreshTokenHandler(req, res) {
  const { refresh_token } = req.body

  // Look up Refresh Token in DB
  const storedToken = await db.refreshTokens.findOne({ token: refresh_token })

  if (!storedToken) {
    return res.status(401).json({ error: 'Invalid refresh token' })
  }

  // Check if token was already used (Reuse Detection)
  if (storedToken.used) {
    // Possible theft -> invalidate all tokens for user
    await db.refreshTokens.deleteMany({ userId: storedToken.userId })
    return res.status(401).json({ error: 'Token reuse detected. All sessions revoked.' })
  }

  // Mark existing token as used
  await db.refreshTokens.updateOne({ token: refresh_token }, { used: true, usedAt: new Date() })

  // Issue new tokens
  const newAccessToken = generateAccessToken(storedToken.userId)
  const newRefreshToken = generateRefreshToken()

  await db.refreshTokens.insertOne({
    token: newRefreshToken,
    userId: storedToken.userId,
    parentToken: refresh_token,
    used: false,
    expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
  })

  res.json({
    access_token: newAccessToken,
    refresh_token: newRefreshToken,
  })
}

{
  "iss": "https://accounts.google.com",
  "sub": "110169484474386276334",
  "aud": "my-client-id",
  "exp": 1678886400,
  "iat": 1678882800,
  "nonce": "random-nonce-value",
  "name": "John Doe",
  "email": "john@gmail.com",
  "email_verified": true,
  "picture": "https://lh3.googleusercontent.com/photo.jpg"
}

All OIDC providers serve a Discovery document:

GET https://accounts.google.com/.well-known/openid-configuration

Included information:
  - issuer: Provider identifier
  - authorization_endpoint: Authorization endpoint
  - token_endpoint: Token endpoint
  - userinfo_endpoint: User info endpoint
  - jwks_uri: Public key set URL
  - scopes_supported: Supported scopes
  - response_types_supported: Supported response types

// Spring Boot 3 + Spring Security 6 Configuration
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/api/public/**").permitAll()
                .requestMatchers("/api/admin/**").hasRole("ADMIN")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwtAuthenticationConverter(jwtAuthenticationConverter())
                )
            )
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)
            );

        return http.build();
    }

    @Bean
    public JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter converter = new JwtGrantedAuthoritiesConverter();
        converter.setAuthoritiesClaimName("roles");
        converter.setAuthorityPrefix("ROLE_");

        JwtAuthenticationConverter jwtConverter = new JwtAuthenticationConverter();
        jwtConverter.setJwtGrantedAuthoritiesConverter(converter);
        return jwtConverter;
    }

    @Bean
    public JwtDecoder jwtDecoder() {
        return NimbusJwtDecoder.withJwkSetUri(
            "https://auth.example.com/.well-known/jwks.json"
        ).build();
    }
}

# application.yml
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com
          jwk-set-uri: https://auth.example.com/.well-known/jwks.json

// auth.ts (Auth.js v5 configuration)
import NextAuth from 'next-auth'
import GitHub from 'next-auth/providers/github'
import Google from 'next-auth/providers/google'
import Credentials from 'next-auth/providers/credentials'

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [
    GitHub({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET,
    }),
    Google({
      clientId: process.env.GOOGLE_ID,
      clientSecret: process.env.GOOGLE_SECRET,
    }),
    Credentials({
      name: 'credentials',
      credentials: {
        email: { label: 'Email', type: 'email' },
        password: { label: 'Password', type: 'password' },
      },
      async authorize(credentials) {
        const user = await verifyCredentials(
          credentials.email as string,
          credentials.password as string
        )
        return user || null
      },
    }),
  ],
  callbacks: {
    async jwt({ token, user, account }) {
      if (user) {
        token.id = user.id
        token.role = user.role
      }
      if (account) {
        token.accessToken = account.access_token
      }
      return token
    },
    async session({ session, token }) {
      session.user.id = token.id as string
      session.user.role = token.role as string
      return session
    },
  },
  pages: {
    signIn: '/login',
    error: '/auth/error',
  },
  session: {
    strategy: 'jwt',
    maxAge: 24 * 60 * 60, // 24 hours
  },
})

// middleware.ts
import { auth } from './auth'

export default auth((req) => {
  const isLoggedIn = !!req.auth
  const isProtected = req.nextUrl.pathname.startsWith('/dashboard')

  if (isProtected && !isLoggedIn) {
    return Response.redirect(new URL('/login', req.nextUrl))
  }
})

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*'],
}

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "net/http"

    "github.com/coreos/go-oidc/v3/oidc"
    "golang.org/x/oauth2"
)

var (
    oauth2Config *oauth2.Config
    oidcVerifier *oidc.IDTokenVerifier
)

func init() {
    ctx := context.Background()
    provider, _ := oidc.NewProvider(ctx, "https://accounts.google.com")

    oauth2Config = &oauth2.Config{
        ClientID:     "CLIENT_ID",
        ClientSecret: "CLIENT_SECRET",
        RedirectURL:  "http://localhost:8080/callback",
        Endpoint:     provider.Endpoint(),
        Scopes:       []string{oidc.ScopeOpenID, "profile", "email"},
    }

    oidcVerifier = provider.Verifier(&oidc.Config{
        ClientID: "CLIENT_ID",
    })
}

func handleLogin(w http.ResponseWriter, r *http.Request) {
    state := generateState()
    http.Redirect(w, r, oauth2Config.AuthCodeURL(state), http.StatusFound)
}

func handleCallback(w http.ResponseWriter, r *http.Request) {
    ctx := r.Context()
    code := r.URL.Query().Get("code")

    // Token exchange
    token, err := oauth2Config.Exchange(ctx, code)
    if err != nil {
        http.Error(w, "Token exchange failed", http.StatusInternalServerError)
        return
    }

    // Extract and verify ID Token
    rawIDToken, ok := token.Extra("id_token").(string)
    if !ok {
        http.Error(w, "No ID token", http.StatusInternalServerError)
        return
    }

    idToken, err := oidcVerifier.Verify(ctx, rawIDToken)
    if err != nil {
        http.Error(w, "ID token verification failed", http.StatusInternalServerError)
        return
    }

    // Extract claims
    var claims struct {
        Email   string `json:"email"`
        Name    string `json:"name"`
        Picture string `json:"picture"`
    }
    idToken.Claims(&claims)

    json.NewEncoder(w).Encode(claims)
}

func main() {
    http.HandleFunc("/login", handleLogin)
    http.HandleFunc("/callback", handleCallback)
    fmt.Println("Server running on :8080")
    http.ListenAndServe(":8080", nil)
}

Attack:
  User visits malicious site while logged in
  -> Malicious site uses user cookies to make API requests

Defense:
  1. Set SameSite cookie attribute (Lax or Strict)
  2. Use CSRF tokens
  3. Validate Origin/Referer headers
  4. Use Authorization header (instead of cookies)

Attack:
  Execute JavaScript through XSS vulnerability
  -> Steal tokens from localStorage

Defense:
  1. Store tokens in httpOnly cookies (no JavaScript access)
  2. Set CSP (Content Security Policy) headers
  3. Sanitize input values
  4. Use XSS prevention libraries like DOMPurify

Attack:
  Include token in URL parameters
  -> Leaked via Referrer headers, browser history, server logs

Defense:
  1. Never include tokens in URLs
  2. Use Authorization header or httpOnly cookies
  3. Set Referrer-Policy header

Attack:
  Intercept a valid token and reuse it

Defense:
  1. Short token expiration time
  2. Use jti (JWT ID) claim for one-time verification
  3. Use nonce (OIDC)
  4. Token binding (DPoP -- Demonstration of Proof-of-Possession)

Attack:
  In RS256 environment, attacker changes alg to HS256
  -> Uses public key as HS256 secret to forge signatures

Defense:
  1. Fix allowed algorithms on server (algorithms: ['RS256'])
  2. Never trust the alg claim
  3. Use latest JWT libraries

A07:2021 -- Identification and Authentication Failures

Checklist:
  1. Don't allow weak passwords
  2. Prevent brute force attacks (account lockout, Rate Limiting)
  3. Support Multi-Factor Authentication (MFA)
  4. Prevent session fixation (change session ID on login)
  5. Secure password storage (bcrypt, Argon2)
  6. Implement token/session expiration
  7. Fully invalidate tokens/sessions on logout

Security Basics:
  [ ] HTTPS required (HTTP redirect)
  [ ] Appropriate token expiration (Access: 15min, Refresh: 7 days)
  [ ] httpOnly + Secure + SameSite cookies
  [ ] CORS correctly configured

Token Management:
  [ ] Refresh Token Rotation applied
  [ ] Token blacklist/revocation mechanism
  [ ] JWT signing algorithm fixed (RS256/ES256)
  [ ] Key rotation plan established

Input Validation:
  [ ] redirect_uri whitelist validation
  [ ] state parameter for CSRF prevention
  [ ] PKCE applied (SPA, mobile)
  [ ] Input sanitization

Monitoring:
  [ ] Login failure monitoring and alerts
  [ ] Anomalous token usage pattern detection
  [ ] Rate Limiting applied
  [ ] Audit logging

Infrastructure:
  [ ] Secret management (AWS Secrets Manager, Vault)
  [ ] Sensitive info in environment variables
  [ ] Regular security audits