JWT Authentication Patterns

1. How JWT Authentication Works

In traditional session-based authentication, the server stores session data and sends the client a session ID cookie. With JWT authentication, the server issues a signed token containing the user's identity and claims. The client stores this token and sends it with each request. The server verifies the token's signature and reads the claims — no database lookup required.

This stateless approach has a significant advantage: any server with the verification key can validate the token independently. This makes JWT ideal for distributed systems, microservices, and horizontally scaled applications where session sharing would add complexity.

Client                          Server
  |                               |
  |  POST /login {credentials}    |
  |------------------------------>|
  |                               |  Validate credentials
  |                               |  Generate JWT
  |  200 OK {access_token, ...}   |
  |<------------------------------|
  |                               |
  |  GET /api/data                |
  |  Authorization: Bearer <JWT>  |
  |------------------------------>|
  |                               |  Verify JWT signature
  |                               |  Read claims
  |  200 OK {data}                |
  |<------------------------------|

2. Access Tokens vs Refresh Tokens

Production JWT authentication systems use two types of tokens with different purposes and lifetimes:

3. The Login Flow Step by Step

1. User submits credentials

   The client sends a POST request with username and password (over HTTPS) to the authentication endpoint.

2. Server validates credentials

   The server checks the credentials against the user database. Passwords are compared using a secure hash function (bcrypt, scrypt, or Argon2).

3. Server generates tokens

   On success, the server creates an access token (short-lived, with user claims) and a refresh token (long-lived, stored server-side with the user record).

4. Tokens are returned to the client

   The access token is returned in the response body. The refresh token is set as an httpOnly, Secure, SameSite cookie.

5. Client stores and uses the access token

   The client includes the access token in the Authorization: Bearer header for all subsequent API requests.

// Example login response
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 900
}

// Refresh token is set as an httpOnly cookie:
// Set-Cookie: refresh_token=eyJ...; HttpOnly; Secure; SameSite=Strict; Path=/auth/refresh

4. Token Refresh Flow

When the access token expires, the client uses the refresh token to get a new one without asking the user to log in again.

Client                          Server
  |                               |
  |  GET /api/data                |
  |  Authorization: Bearer <expired JWT>
  |------------------------------>|
  |  401 Unauthorized             |
  |<------------------------------|
  |                               |
  |  POST /auth/refresh           |
  |  Cookie: refresh_token=<RT>   |
  |------------------------------>|
  |                               |  Validate refresh token
  |                               |  Generate new access token
  |                               |  (Optionally rotate refresh token)
  |  200 OK {access_token}        |
  |<------------------------------|
  |                               |
  |  Retry: GET /api/data         |
  |  Authorization: Bearer <new JWT>
  |------------------------------>|

Refresh Token Rotation

For additional security, issue a new refresh token every time the old one is used. This is called refresh token rotation. If an attacker steals a refresh token and uses it, the legitimate user's next refresh attempt will fail (because the token was already consumed), alerting the system to a potential compromise.

Token families help detect this: assign a family ID when the user logs in. All rotated refresh tokens in a session share the same family ID. If a refresh token from the same family is used twice, invalidate the entire family and force a re-login.

5. JWT in OAuth 2.0 and OpenID Connect

While you can build custom JWT auth, most production systems use OAuth 2.0 and OpenID Connect (OIDC) as standardized frameworks. Here's how JWT fits in:

OAuth 2.0

OAuth 2.0 is an authorization framework. While the spec doesn't require JWTs, most implementations use JWTs as access tokens because they're self-contained and verifiable without calling the authorization server. The token's scope claim defines what API operations are permitted.

OpenID Connect (OIDC)

OIDC is an identity layer built on top of OAuth 2.0. It introduces the ID token — always a JWT — which contains claims about the authenticated user (name, email, etc.). The flow produces three tokens:

• ID Token (JWT) — Proves the user's identity to the client
• Access Token (often a JWT) — Grants API access
• Refresh Token (opaque string) — Used to get new access tokens

JWKS (JSON Web Key Sets)

In OAuth/OIDC systems, the authorization server publishes its public keys at a well-known endpoint (typically /.well-known/jwks.json). Resource servers fetch these keys to verify token signatures. The kid (Key ID) header in the JWT identifies which key was used for signing.

// Example JWKS endpoint response
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key-2024-01",
      "use": "sig",
      "alg": "RS256",
      "n": "0vx7agoebGcQSuu...",
      "e": "AQAB"
    }
  ]
}

6. JWT in Microservices

JWTs are particularly well-suited for microservices architectures where multiple independent services need to authenticate requests. Here's why and how:

API Gateway Pattern

A common pattern is to validate the JWT at the API gateway and then propagate trusted claims to downstream services via internal headers:

Client → API Gateway → Service A → Service B
         (validates JWT)    ↓
                    Propagates claims:
                    X-User-ID: user_123
                    X-User-Roles: editor,reviewer

This way, internal services don't need to re-validate the JWT. They trust the gateway and read claims from headers. The internal network must be secured to prevent header injection.

Service-to-Service Authentication

Services can also issue their own JWTs for internal communication. Each service has its own key pair. The iss claim identifies which service generated the token, and the aud claim specifies the target service.

7. Implementing Logout

Logout with JWTs is more nuanced than with sessions. Since JWTs are stateless, you can't simply "delete" a token server-side. Here are practical approaches, from simplest to most comprehensive:

8. Architecture Recommendations