Authentication (JWT)

JWT Authentication System

JSON Web Token (JWT) is the core technology for implementing stateless authentication in our application. This document covers the design, workflow, security features, and usage of our JWT system.

The system consists of two parts:

1. Token Generation: Issue a time-limited JWT containing user identity after successful login
2. Token Validation: Verify the JWT in each protected API request and extract user information

---

JWT Structure & Claims

#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct Claims {
    pub uid: i64,           // User ID
    pub token_id: i64,      // Token unique ID for whitelist verification
    pub username: String,
    pub exp: i64,           // Expiration timestamp
}

• token_id is a key security enhancement — it's linked to a record in the sys_white_jwt table for proactive token invalidation (logout).

---

Workflow

1. Token Generation (authorize function)

After successful login:

1. Receive AuthPayload with user info
2. Generate token_id by inserting a record into sys_white_jwt table
3. Calculate expiration time (exp)
4. Create Claims instance
5. Sign with the global secret key (KEYS.encoding)
6. Return AuthBody with token and expiration info

2. Token Validation (UserInfo extractor)

When a handler has user_info: UserInfo as a parameter, Axum automatically:

1. Extracts Bearer Token from Authorization: Bearer <token> header
2. Decodes and validates the token signature and expiration
3. Checks if token_id exists in the whitelist (allows proactive logout)
4. Re-queries user's latest info from the database (ensures role changes take effect immediately)
5. Injects UserInfo into request extensions

---

Security Design

Security Features

1. Balance of Stateless & Stateful:

   • Traditional JWT is fully stateless — once issued, it cannot be revoked before expiry
   • Our system introduces token_id and a whitelist table for a "semi-stateful" mode

2. Real-time Role Changes:

   • By re-querying user info on every request, permission changes take effect immediately

3. Centralized Key Management:

   • All token signing/validation uses a global static KEYS initialized via once_cell::sync::Lazy

4. Clear Error Types (AuthError):

   • AuthError enum defines all authentication failure scenarios with precise HTTP status codes