JWT Usage & Lifecycle

This focused publication documents exactly how SinPluma uses JSON Web Tokens (JWTs) for authentication and session management: why JWTs were chosen, the full lifecycle (request → issuance → client storage → request use → server validation → refresh → revocation), and how Redis-based blacklisting interacts with JWT statelessness. It closes with security notes and recommended best practices.

SinPluma uses JWTs because they provide:

• Compact, self-contained claims (identity, roles, expiry) that services can verify without a DB round-trip.
• Standardized, language-agnostic tokens easy to generate/validate across microservices.
• Decoupled authentication: client holds proof of authentication and sends it with each request (no server session store required for basic validation).

In practice SinPluma uses two token types:

• Access token (short-lived JWT) — sent with each API request to prove identity and rights.
• Refresh token (longer-lived JWT or opaque token) — used only to obtain new access tokens without re-authenticating user credentials.

A standard JWT has three dot-separated parts:

• Header: algorithm (e.g.,HS256) and token typeJWT.
• Payload (claims):sub(subject/user id),exp(expiry),iat(issued at),jti(unique token id), optionalrolesorscopes.
• Signature: HMAC or RSA signature over header+payload using server secret/private key.

Example claim set (conceptual):

SinPluma includes a JTI (JWT ID) claim so tokens can be uniquely identified for revocation.

• Client action: User submits credentials (email/password) to:

• Server checks: validate credentials (bcrypt check), apply any rate limiting.
• If valid: server creates an access token and a refresh token and returns them in the response body (or sets cookie for refresh token).

Server response (conceptual):

• Access token properties:

  • Short TTL (e.g., 10–30 minutes).
  • Contains identity claims and minimal authorization claims (roles,permissions).
  • Signed using server secret (HS256) or private key (RS256).
  • jtiincluded.

• Refresh token properties:

  • Longer TTL (e.g., days/weeks) or managed as opaque token.
  • Can be a JWT (with its ownjti) or an opaque random token stored server-side.
  • If JWT refresh tokens are used, they also includejtifor revocation tracking.

Token creation is typically done with a library such asFlask-JWT-Extended, which abstracts issuance and claim embedding.

Common approaches and SinPluma considerations:

• Access token — in memory or short-lived storage

  • Preferred: store in memory (JS variable / Redux store) to minimize XSS exposure.
  • On page refresh it is lost, but the client can use the refresh token to obtain a new access token.

• Refresh token — HttpOnly cookie (recommended)

  • Best practice: store the refresh token in an HttpOnly, Secure cookie so JavaScript cannot read it (mitigates XSS).
  • Cookies can be protected withSameSiteattributes to reduce CSRF risk.

• Alternative (less secure) approaches

  • Storing tokens inlocalStorageor non-HttpOnly cookies — not recommended for refresh tokens due to XSS risk.

The SinPluma demo environment may store tokens in local storage for simplicity, but production recommendations favor HttpOnly cookies for refresh tokens and short-lived in-memory access tokens.

• Access token: included in each API request:

Typically added automatically via an Axios interceptor.

• Refresh flow: when the access token expires, the client calls:

• If refresh token is in HttpOnly cookie, the request automatically includes it.
• If refresh token is returned to client JS, it is included in the POST body.

When a request arrives withAuthorization: Bearer <jwt>:

1. Parse token (split header.payload.signature).
2. Verify signature using secret or public key. If invalid → reject (401).
3. Validate standard claims:
   • exp(not expired)
   • nbf(not before)
   • iss/audif configured
   • iatsanity checks
4. Check token replay / revocation:
   • Extractjti
   • Query Redis blacklist
   • If found → reject (401/403)
5. Authorize action:
   • Validateroles/scopesagainst endpoint requirements.

Signature validation is local and fast; Redis lookup adds minimal latency.

1. Client detects access token expiry (401 response or client timer).
2. Client calls/api/auth/refresh.
3. Server validates refresh token:
   • Signature
   • Expiry
   • Redis blacklist check
4. If valid:
   • Issue new access token
   • Issue new refresh token (recommended rotation)
   • Blacklist old refresh token JTI in Redis (with TTL)
5. Return new tokens to client.

Refresh-token rotation significantly reduces risk if a refresh token is compromised.

• Client calls:

• Server:
  • Extractsjtifrom access token
  • Extractsjtifrom refresh token
  • Stores both in Redis blacklist with TTL equal to remaining lifetime

Example Redis entry:

Now even if the token has not expired, it is rejected.

On revocation:

On every authenticated request:

If key exists → token rejected.

• Immediate revocation capability.
• Lightweight storage (only JTIs).
• Automatic expiration via TTL.
• Extremely fast lookup.

JWTs are meant to be stateless — validation should not require server storage.

Redis blacklisting introduces state:

• Pro: immediate logout & compromise mitigation.
• Con: every request requires a Redis lookup.

SinPluma accepts this tradeoff because security and immediate revocation outweigh minimal performance cost.

• Short-lived access tokens only + opaque refresh tokens stored server-side.
• OAuth-style token introspection endpoint.
• Session invalidation timestamp comparison (iatvslast_invalidated_at).
• Strict refresh rotation + very short access TTL.

• Store refresh tokens in HttpOnly Secure cookies.
• Keep access tokens short-lived (10–30 minutes).
• Rotate refresh tokens on each use.
• Prefer RS256 if multiple services validate tokens.
• Blacklist JTIs with TTL equal to remaining token lifetime.
• Protect refresh endpoint from CSRF (SameSite + CSRF token).
• Log authentication anomalies.
• Avoid placing sensitive data inside JWT payload.

1. POST/api/auth/login
2. Server validates credentials.
3. Server creates access + refresh tokens.
4. Return tokens (or set refresh cookie).

1. Client sendsAuthorization: Bearer <access_token>
2. Server verifies signature → checks Redis → authorizes → returns data.

1. Client calls/api/auth/refresh
2. Server validates refresh token
3. Server issues new access token (+ new refresh token if rotating)
4. Blacklists old refresh JTI

1. Client calls/api/auth/logout
2. Server blacklists access + refresh JTIs in Redis

SinPluma uses JWTs to provide decentralized, standards-based authentication:

• Short-lived access tokens for per-request authorization.
• Longer-lived refresh tokens for session continuity.
• Redis-backed JTI blacklist for immediate revocation.

This approach balances performance (local signature validation) with security (revocation, rotation, short TTLs), making it suitable for a distributed microservices environment while maintaining strong authentication guarantees.