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.