JWT Token Management Implementation

[dinhoSilwa]

Description

Implement a JWT authentication system to protect sensitive API routes, following the project’s layered architecture and established patterns.

Architecture and Principles to Follow

• Layered Architecture: Maintain a clear separation between layers (core, models, schemas, repositories, service, routes)
• Repository Pattern: Preserve the existing data-access pattern
• Dependency Injection: Use the dependency system already implemented
• JOSE Library: Use python-jose for handling JWT tokens
• Consistency: Follow the same naming conventions and module structure already used

---

Tasks to Implement

1. Configuration & Environment

• Add environment variables to .env.example:

  • JWT_SECRET_KEY: Secret key for token signing
  • JWT_ALGORITHM: Encryption algorithm (e.g., HS256)
  • JWT_EXPIRATION_MINUTES: Token expiration time

2. Data Models (models/)

• Create models/jwt_model.py containing:

  • Token: Model for access token
  • TokenData: Model for decoded token data
  • TokenResponse: Model for login response

3. Validation Schemas (schemas/)

• Create schemas/token_schemas.py with Pydantic schemas for:

  • Token responses
  • Authentication input validation

4. Security & JWT (core/security/)

• Create core/security/jwt_manager.py containing:

  • JWTManager: Class for managing JWT tokens
  • Methods to create, validate, and decode tokens
  • Integration with python-jose

5. Authentication Service (service/)

• Update service/auth_service.py:

  • Add generate_token() method to AuthService
  • Integrate JWTManager into the login flow
  • Return the token along with user data on login

6. Authentication Dependencies (dependencies.py)

• Create dependencies for:

  • get_current_user: Extract user from JWT token
  • get_current_active_user: Validate active user
  • Role-based protection (admin/user)

7. Protected Routes (routes/v1/)

• Update routes/v1/certificate_routes.py:

  • Apply authentication dependencies to POST and GET routes
  • Keep some routes public if necessary

• Create a refresh token endpoint if applicable

8. Exception Handling (exceptions/)

• Add specific exceptions for:

  • Expired token
  • Invalid token
  • Unauthenticated user
  • Insufficient permissions

9. API Documentation

• Update Swagger auto-docs:

  • Add JWT authorization button
  • Document protected endpoints
  • Provide token usage examples

---

Proposed Authentication Flow

1. Login → Generate JWT token
2. Protected Routes → Require token in header:
   Authorization: Bearer <token>
3. Validation → Middleware checks token and extracts user
4. Authorization → Dependencies verify role-based permissions

---

Suggested File Structure

api_certify/
├── core/security/
│   ├── hash_manager.py (existing)
│   └── jwt_manager.py (new)
├── models/
│   └── jwt_model.py (new)
├── schemas/
│   └── token_schemas.py (new)
└── dependencies.py (updated)

---

Important Considerations

• Maintain compatibility with the existing password hashing system (bcrypt)
• Follow the existing response pattern (SuccessResponse, ErrorResponse)
• Keep exception handling centralized
• Ensure tokens do not store sensitive data
• Implement logout with blacklist if needed

---

Required Validations

• Token expiration
• Signature validation
• User status checks
• Role-based access control
• Proper error messages

---

Recommended Tests

• Token generation and validation
• Accessing protected routes
• Handling expired/invalid tokens
• Role-based access restrictions

---

Note: This implementation must integrate seamlessly with the existing email/password authentication, adding the JWT layer exclusively for route protection.

---