System Architecture

Architecture Overview

CAS Server

Laravel-based authentication server. Handles user management, token generation, 2FA, and admin panel.

Laravel 11 PHP 8.2

Data Layer

PostgreSQL for persistent data. Redis for session management, caching, and rate limiting counters.

PostgreSQL 16 Redis 7

Client SDKs

6 official client libraries. Each handles SSO token exchange and session management for its platform.

Laravel Node.js Python

Request Flow

1

Client Request

Client app sends credentials + HMAC signature to CAS API

2

Security Middleware

IP whitelist check → Rate limit check → HMAC verification → reCAPTCHA validation

3

Authentication

Credential verification against PostgreSQL → 2FA challenge (if enabled) → Lockout check

4

Token Generation

JWT token created with HMAC-SHA256, stored in Redis, returned to client

5

Audit & Webhooks

Event logged to audit table, webhook dispatched to registered endpoints

Database Schema

Table	Purpose	Key Fields
users	User accounts and profiles	email, password_hash, role, is_2fa_enabled
client_systems	Registered applications	name, url, client_id, client_secret, ip_whitelist
sso_tokens	Active JWT tokens	user_id, token_hash, expires_at, client_system_id
login_attempts	Failed login tracking	email, ip, attempts, locked_until
audit_logs	All auth events	user_id, action, ip, user_agent, timestamp

Technical Documentation

How the CAS codebase is structured and how each layer functions.

Directory Structure

app/
├── Http/
│   ├── Controllers/
│   │   ├── Admin/          # Admin dashboard, users, clients, audit logs
│   │   ├── Auth/           # Login, logout, 2FA verification
│   │   ├── Api/            # SSO token endpoints, health check
│   │   └── Public/         # Documentation, downloads
│   ├── Middleware/
│   │   ├── AdminMiddleware.php        # Role-based admin access
│   │   ├── IpWhitelistMiddleware.php  # IP filtering (fail-open)
│   │   └── HmacMiddleware.php         # HMAC signature verification
│   └── Livewire/           # Real-time admin components
├── Models/
│   ├── User.php            # User accounts with role & 2FA
│   ├── ClientSystem.php    # Registered applications
│   ├── SsoToken.php        # JWT token records
│   ├── AuditLog.php        # Authentication event log
│   └── IpWhitelist.php     # Allowed IP addresses
└── Services/
    └── SsoService.php      # Core SSO logic (token gen/validation)

Middleware Pipeline

Every web request passes through these layers (in order):

1. IP Whitelist Check — blocks unregistered IPs (if whitelist is populated)
2. Session/Auth — verifies the user's session
3. CSRF Protection — validates form tokens
4. Admin Middleware — restricts admin routes to role=admin

API routes use HMAC middleware instead of CSRF/session.

Livewire Components

The admin panel uses Livewire for real-time updates:

Dashboard Stats — live counters for users, tokens, clients
User Management — inline create/edit/delete with instant feedback
Client Systems — credential generation and copy-to-clipboard
Audit Log Viewer — paginated, filterable event log
IP Whitelist — add/remove with instant validation

Models & Relationships

User

→ hasMany SsoToken
→ hasMany AuditLog
→ belongsToMany ClientSystem

ClientSystem

→ hasMany SsoToken
→ belongsToMany User
→ hasMany IpWhitelist

Package Documentation

How each client SDK package works internally to integrate with CAS.

Common SDK Flow

All SDK packages follow the same core authentication pattern:

1

User Visits Protected Route

SDK middleware intercepts the request and checks for a valid CAS session

2

Redirect to CAS Login

If no session exists, user is redirected to CAS login page with a return URL

3

CAS Authenticates & Generates Token

After successful login, CAS generates a JWT token and redirects back with the token

4

SDK Validates Token via API

The SDK sends the token to the CAS /api/sso/validate endpoint with HMAC signature

5

Session Created

SDK stores user data in the local session. User is now authenticated.

Laravel

Composer package with auto-discovery. Provides cas.auth middleware, service provider, and config publishing.

Node.js

Express middleware via npm. Provides casAuth() middleware and CasClient class.

Python

Django middleware via pip. Provides CasAuthMiddleware class and management commands.

Java

Spring Security filter via Maven/Gradle. CasAuthFilter integrates with Spring's filter chain.

.NET / C#

NuGet package with CasAuthFilter action filter and DI-based configuration.

JavaScript

Browser SDK via CDN or npm. Provides CasClient class for SPAs and static sites.

API Documentation

Summary of the CAS API endpoints. View full API Reference →

Method	Endpoint	Purpose	Auth
POST	/api/sso/token	Generate SSO token (authenticate user)	HMAC + Client credentials
POST	/api/sso/validate	Validate an existing token	HMAC
POST	/api/sso/logout	Revoke/invalidate a token	HMAC
GET	/api/health	Health check (server status)	None
GET	/api/sso/user	Get authenticated user details	Bearer token

All API requests (except health check) require HMAC-SHA256 signatures in the X-Signature and X-Timestamp headers. See Security Features for details.