KwestKarz Security System Specification - wwestlake/KwestKarz GitHub Wiki
KwestKarz Security System Specification
Overview
This document outlines the authentication and authorization system used within the KwestKarz Internal Management System (IMS). The design focuses on secure access, role-based permissions, and token-based session management.
Authentication Flow
Account Registration
- New users can register by providing an email address and password.
- Passwords are hashed using BCrypt before being stored.
- Upon registration:
- The account is created as inactive.
- No roles are assigned.
- A verification email is sent to the user.
Email Verification
- The system sends a verification link to the user's email.
- Clicking the link marks the user as email-verified.
- Email verification is required before login is allowed.
Authorization Flow
Role Assignment
- Initial role assignment is done manually by an administrator.
- Until a role is assigned, verified users only have access to a limited informational page within the app.
Available Roles
- Employee
- Maintenance
- Admin
Each role provides access to specific application features and API endpoints.
Token Generation
JWT Tokens
- The system uses JSON Web Tokens (JWT) for session management.
- Tokens are signed with a symmetric key.
Token Claims
Tokens include:
sub
(User ID)email
(User Email Address)roles
(Comma-separated list of assigned roles)iat
(Issued At)exp
(Expiration Time)
Token Expiration
- Tokens are valid for 1 hour.
- If the user remains active, tokens will automatically renew for up to 24 hours.
- After 24 hours, users must log in again.
Access Control
API endpoints enforce role-based access using attributes like:
[Authorize(Roles = "Maintenance")]
Endpoints that require general authentication without role restrictions use:
[Authorize]
Public or registration-related endpoints do not require authentication.
Summary
This security system balances ease-of-use with security best practices. Email verification, manual role assignment, and role-based token claims ensure that only authorized users have access to sensitive business functions.