Token‐Based Authentication and Authorization - sonuprajapati15/Authentication-Authorization GitHub Wiki

Token-Based Authentication and Authorization - System Design (JWT)

High-Level Design (HLD)

token based image url

Overview

JWT (JSON Web Token) based authentication and authorization is a mechanism to securely validate users and control access to resources using cryptographically signed tokens instead of traditional session-based authentication.

Components

  1. Client - The entity (e.g., web, mobile app) requesting access.
  2. Authentication Server - Issues JWT tokens after verifying credentials.
  3. Resource Server - Hosts the protected resources and validates JWT tokens.
  4. Token Storage - Secure storage of JWT tokens (e.g., HTTP-only cookies, local storage, or in-memory).
  5. Revocation Mechanism - Ensures compromised tokens can be invalidated (e.g., using blacklists, token expiration, or refresh tokens).

Workflow

  1. User Login: The client sends user credentials to the authentication server.
  2. JWT Token Generation: Upon successful authentication, the server issues an access token (JWT) and optionally a refresh token.
  3. Token Storage: The client stores the JWT securely (e.g., local storage, HTTP-only cookies, or in-memory).
  4. Authorization Request: The client sends the JWT in the request header (Authorization: Bearer <JWT>) to access protected resources.
  5. JWT Token Verification: The resource server validates the JWT signature, checks claims, and ensures it is not expired.
  6. Token Expiry/Renewal: JWT tokens expire after a predefined period and may be refreshed using a refresh token mechanism.

Low-Level Design (LLD)

Authentication Server

  1. Endpoints:

    • /login: Accepts user credentials and returns JWT access & refresh tokens.
    • /refresh-token: Issues a new access token when the refresh token is valid.
    • /logout: Invalidates refresh tokens.
  2. JWT Token Generation:

    • Use JWT with claims such as user ID, roles, and expiration time.
    • Sign JWT tokens using HMAC (HS256) or RSA (RS256) algorithms.
  3. Token Storage:

    • Access tokens: Stored in HTTP headers (short-lived, stateless).
    • Refresh tokens: Stored in HTTP-only cookies or a secure database (long-lived).

Resource Server

  1. Middleware for JWT Verification:

    • Decodes and verifies the JWT signature.
    • Checks expiration time and claims.
  2. Access Control:

    • Implement role-based or attribute-based access control (RBAC/ABAC).
    • Restrict API endpoints based on user permissions.

JWT Flows

  1. Login Flow:

    • User sends credentials → Authentication server validates → Issues JWT access & refresh tokens → Client stores and uses the token.
  2. Accessing Protected Resources:

    • Client sends JWT token → Resource server validates → Grants or denies access.
  3. Token Refresh Flow:

    • Client sends refresh token → Authentication server validates → Issues new access token.
  4. Logout Flow:

    • Client sends a logout request → Refresh token is invalidated.

Pros and Cons

Pros:

  • Stateless and scalable (JWT does not require server-side session storage).
  • Compact and portable (suitable for web, mobile, and microservices architectures).
  • Secure when properly implemented (signed and optionally encrypted tokens).
  • Supports Single Sign-On (SSO).

Cons:

  • Token management complexity (expiration, storage, and revocation handling).
  • JWT tokens can be stolen if not secured properly.
  • Harder to revoke JWTs compared to session-based authentication (workarounds: token blacklisting, short expiry, refresh tokens).

When to Use JWT?

  • API-based authentication (e.g., mobile apps, microservices, third-party integrations).
  • Single sign-on (SSO) across multiple domains or services.
  • Distributed architectures where scalability is a priority.

When Not to Use JWT?

  • Simple applications without API requirements (session-based auth might be simpler).
  • When token revocation is a critical requirement (JWTs are harder to revoke compared to session-based authentication).

This document provides a structured design approach for implementing JWT-based authentication and authorization in a secure and scalable manner.

⚠️ **GitHub.com Fallback** ⚠️