Authentication System
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication System in the Outmanage Backend is a JWT-based security framework designed to regulate access to logistics management resources. It implements a dual-token strategy involving short-lived access tokens and longer-lived refresh tokens to balance security and user experience. The system is tightly integrated with a Role-Based Access Control (RBAC) model to ensure that authenticated users only perform actions permitted by their assigned roles.
Sources: CLAUDE.md:14-15, src/controllers/authController.ts:44-55
Core Architecture
The system utilizes JSON Web Tokens (JWT) transmitted via a custom header rather than the standard Authorization header. This custom header, x-outmanage-token, is used for both initial authentication and token refreshing operations.
Token Strategy
The architecture employs two distinct types of tokens:
- Access Token: A short-lived token (30 seconds) used for authorizing immediate API requests.
- Refresh Token: A longer-lived token (6 hours) stored in the database, used to obtain new access tokens without requiring re-authentication.
Sources: src/controllers/authController.ts:44-55, CLAUDE.md:38, comprehensive-swagger-api.json:34-38
Authentication Flow
The following sequence diagram illustrates the login and token generation process.
Authentication Components
Middleware Logic
The authenticateToken middleware acts as the primary gatekeeper for protected routes. It extracts the token from the x-outmanage-token header, verifies it against the server's JWT_SECRET, and attaches the decoded payload to the request object for use in downstream controllers.
Sources: src/middlewares/authentication.ts:7-34
User Identity and RBAC
Identity is tied to the User model, which includes a roleId linking to the RBAC system. During the seeding process, a default "Pemilik" (Owner) role is created with full permissions across all system resources including users, warehouses, and shipments.
Sources: prisma/seed.ts:33-40, comprehensive-swagger-api.json:141-180
| Component | Logic Reference | Source File |
|---|---|---|
| Token Verification | jwt.verifyToken(token) | src/middlewares/authentication.ts:25 |
| Password Hashing | bcrypt.comparePassword | src/controllers/authController.ts:37 |
| Token Header | x-outmanage-token | src/middlewares/authentication.ts:8 |
| Database Sync | userService.updateUserRefreshToken | src/controllers/authController.ts:65 |
API Endpoints
The system exposes specific endpoints for managing the session lifecycle.
Authentication Endpoints
Sources: comprehensive-swagger-api.json:441-525, src/controllers/authController.ts:14-173
| Endpoint | Method | Description | Security |
|---|---|---|---|
/api/auth/login | POST | Exchanges credentials for access and refresh tokens. | Public |
/api/auth/refresh-token | GET | Generates a new access token using the x-outmanage-token header. | Public (Internal Check) |
/api/auth/logout | POST | Invalidates the current refresh token in the database. | Authenticated |
Token Refresh Flow
The refresh mechanism allows the client to maintain a session even after the 30-second access token expires, provided the 6-hour refresh window is still active.
Configuration and Security
The system uses environment-specific configurations and follows strict security protocols for token handling:
- Timezone Consistency: The system forces the
Asia/Jakarta(GMT+7) timezone for all token expiry calculations to prevent synchronization issues between the application server and the database. - Database Integration: Refresh tokens are stored in the MySQL database with an
expiresAttimestamp. - Error Handling: Specific error codes like
TOKEN_REFRESH_KADALUARSA(Expired) orFORMAT_TOKEN_TIDAK_VALIDare returned to guide the frontend client.
Sources: src/index.ts:77-80, src/controllers/authController.ts:60-65, src/controllers/authController.ts:119-130, CLAUDE.md:76-78
Summary
The Authentication System provides a secure foundation for the Outmanage Backend by implementing a robust JWT lifecycle. By utilizing custom headers, short-lived access tokens, and a database-backed refresh mechanism, it ensures that logistics operations remain protected while allowing for the granular permission control required by the project's multi-warehouse and role-based operational model.