⬅️ Back to Controller Overview

Security Endpoints Matrix

Authorization Overview

This document maps roles to endpoints across all controllers. Use this matrix to understand who can access what.

Key Principles: - ADMIN = Full access (creation, modification, deletion, reporting) - USER = Read & limited write (own data, standard operations) - PUBLIC = Unauthenticated demo mode (read-only where @appProperties.demoReadonly) - AUTHENTICATED = Any logged-in user (role-agnostic operations)

Role Definitions

Supplier Controller Authorization

Authorization Annotations

// READ (Public allowed in demo mode)
@PreAuthorize("isAuthenticated() or @appProperties.demoReadonly")

// CREATE/UPDATE/DELETE (ADMIN only)
@PreAuthorize("hasRole('ADMIN')")

Inventory Item Controller Authorization

Authorization Pattern

// READ operations
@PreAuthorize("isAuthenticated() or @appProperties.demoReadonly")

// WRITE operations (stock updates, creation)
@PreAuthorize("hasRole('ADMIN')")

Critical: Stock updates (PATCH /api/items/{id}/update-stock) require ADMIN role and create audit trail entries via StockHistory.

Stock History Controller Authorization

Authorization Pattern

// ALL operations (Read-only audit trail)
@PreAuthorize("isAuthenticated() or @appProperties.demoReadonly")

Note: Stock History is immutable read-only audit trail. No write operations exposed.

Authentication Controller Authorization

Authorization Pattern

// User profile & logout (Authenticated only)
@PreAuthorize("isAuthenticated()")

OAuth2 Flow: - GET /api/me triggers auto-authentication if not logged in - POST /api/logout clears cookies and redirects to home

Analytics Controller Authorization

Authorization Pattern

// All analytics endpoints (Read-only)
@PreAuthorize("isAuthenticated() or @appProperties.demoReadonly")

Feature: Analytics are safe for public demo mode (no sensitive data mutation).

Consolidated Access Matrix

╔══════════════════════════════════╦═══════╦══════╦═══════╗
║ Controller Group                 ║ PUBLIC║ USER ║ ADMIN ║
╠══════════════════════════════════╬═══════╬══════╬═══════╣
║ SUPPLIER - List/Get              ║   ✅  ║  ✅  ║  ✅   ║
║ SUPPLIER - Create/Update/Delete  ║   ❌  ║  ❌  ║  ✅   ║
║ INVENTORY - List/Get             ║   ✅  ║  ✅  ║  ✅   ║
║ INVENTORY - Create/Update/Delete ║   ❌  ║  ❌  ║  ✅   ║
║ INVENTORY - Update Stock         ║   ❌  ║  ❌  ║  ✅   ║
║ STOCK HISTORY - All              ║   ✅  ║  ✅  ║  ✅   ║
║ ANALYTICS - All                  ║   ✅  ║  ✅  ║  ✅   ║
║ AUTH - Get Profile/Logout        ║   ❌  ║  ✅  ║  ✅   ║
╚══════════════════════════════════╩═══════╩══════╩═══════╝

Demo Mode Behavior

When appProperties.demoReadonly = true:

// Public reads allowed
@PreAuthorize("isAuthenticated() or @appProperties.demoReadonly")

// Actual behavior:
if (demoReadonly) {
    // ✅ GET requests → Allowed
    // ❌ POST/PUT/PATCH/DELETE → Blocked (throws DemoModeException)
}

Use Cases: - Public dashboards (analytics) - Preview environments - Sandboxes for training

Security Validation Checklist

Before deploying:

☑ ADMIN roles assigned only to trusted users (via APP_ADMIN_EMAILS)
☑ OAuth2 configured (ClientId, ClientSecret in environment)
☑ HTTPS enabled in production (secure cookies)
☑ Session timeout configured (15–30 minutes)
☑ CSRF protection enabled (Spring Security default)
☑ Demo mode disabled in production (@appProperties.demoReadonly = false)
☑ Audit logging enabled (StockHistory captures all writes)
☑ Rate limiting configured (if using Spring Cloud)

Role Assignment Logic

ADMIN Role Assignment

// From AuthController.java
if (APP_ADMIN_EMAILS.contains(user.getEmail())) {
    grantRole("ROLE_ADMIN");
    // Full platform access
} else {
    grantRole("ROLE_USER");
    // Read + limited write access
}

Configuration: Set via environment variable:

APP_ADMIN_EMAILS=admin@company.com,ops@company.com

Summary

Default: Users logged in via OAuth2 get ROLE_USER. Admins require email in APP_ADMIN_EMAILS.

⬅️ Back to Controller Overview