/technical: JWT Implementation Documentation

Author: Rabee Alrahhal

---

Table of Contents

1. Introduction
2. Data Processing
3. Endpoints Requiring JWT Authentication
4. Security Measures
5. Architecture Overview
6. Errors and Troubleshooting

---

Introduction

The JWT (JSON Web Token) implementation in this project enables secure authentication and authorization mechanisms using token-based authentication. It ensures that users can access protected resources by providing a valid token in their requests.

Key Features: - Token generation with HMAC encryption - Token validation and decoding - Authentication filter for request handling

---

Data Processing

The data processing flow for JWT involves generating, validating, and decoding tokens. The primary data being processed includes user identification details such as user IDs.

Data Flow:

1. Token Generation: The generateToken method accepts a user ID and creates a JWT with standard claims such as sub (subject), iat (issued at time), and exp (expiration).
2. Token Validation: The validateToken method checks the token’s signature and expiration to ensure it’s still valid.
3. Token Parsing: The getUserIdFromToken method extracts the user ID from the token’s claims.

Example Code:

public String generateToken(String userId) {
    return Jwts.builder()
            .setSubject(userId)
            .setIssuedAt(new Date())
            .setExpiration(new Date(System.currentTimeMillis() + 3600000)) // 1 hour validity
            .signWith(SignatureAlgorithm.HS512, secretKey)
            .compact();
}

---

Endpoints Requiring JWT Authentication

Method	Endpoint	Description	Authentication Required
GET	/api/secure/resource	Access secure resource	Yes
POST	/api/auth/login	Authenticate and get token	No

Authorization Header Format:

Authorization: Bearer <token>

Sample Response:

{
  "userId": "user123",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

---

Security Measures

The application uses HMAC (Hash-based Message Authentication Code) for token signature to ensure the integrity and authenticity of the JWT tokens.

Key Security Features:

• HMAC-SHA512 Algorithm: Ensures a secure and strong signature.
• Token Expiration: Tokens are valid for a limited time to reduce exposure to attacks.
• Secure Secret Key Management: The secret key is stored securely in environment variables.

---

Architecture Overview

Components:

• Frontend: Communicates with the backend to request tokens and access protected resources.
• Backend: Generates and validates JWT tokens using the JwtUtil class.
• Database: Stores user credentials and related data.

Interaction:

1. User sends login credentials.
2. Backend authenticates user and returns a JWT token.
3. User includes JWT token in the Authorization header of subsequent requests.

---

Errors and Troubleshooting

Common Issues:

1. 401 Unauthorized Error:

   • Verify that the token is correctly included in the Authorization header.
   • Check if the token has expired.

2. ModuleNotFoundError during installation:

   • Ensure all dependencies are properly defined in pom.xml.

3. Deployment Failure due to Environment Variables:

   • Ensure all required environment variables are set before starting the application.

---

Next Section: Continue to the /installation guide for project setup instructions.