Authentication Guide

Complete guide for CAS authentication flows and security features

Table of Contents

Authentication Overview

The CAS (Central Authentication Service) system provides enterprise-grade authentication with support for multiple client applications, secure token management, and comprehensive audit logging.

Key Features

  • • JWT-based token authentication
  • • Client credential management
  • • IP whitelist security
  • • HMAC-SHA256 signature validation
  • • Comprehensive audit logging

Security Benefits

  • • Single sign-on across applications
  • • Centralized user management
  • • Anti-replay protection
  • • Role-based access control
  • • Secure credential handling

Authentication Flows

1. Traditional SSO Flow

Client systems authenticate directly using client credentials and username.

Flow Steps:

  1. Client system sends POST request to /api/sso/token
  2. Include client_id, client_secret, and username in request
  3. CAS validates credentials and IP whitelist
  4. JWT token returned for authenticated sessions
  5. Client uses token for subsequent API calls

Example Request:

POST /api/sso/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "username": "[email protected]"
}

2. Dashboard SSO Flow

Users link their accounts to client systems through the user dashboard.

Flow Steps:

  1. User logs into CAS user dashboard
  2. User links username to available client systems
  3. One-click SSO login generates secure tokens
  4. Automatic redirect to client application
  5. User authenticated without entering credentials

Benefits:

  • No password storage required
  • Enhanced user experience
  • Centralized account management
  • Reduced security risks

JWT Token Management

Token Structure

CAS generates JWT tokens with enhanced payloads containing user information, client system mapping, and security metadata.

Token Payload:

{
  "user_id": "123",
  "username": "[email protected]",
  "client_id": "client_abc123",
  "client_name": "Customer Portal",
  "roles": ["user", "customer"],
  "ip_address": "192.168.1.100",
  "iat": 1640995200,
  "exp": 1641081600,
  "iss": "cas-system",
  "aud": "client_applications"
}

Token Validation

  • Signature verification
  • Expiration checking
  • Issuer validation
  • Audience verification

Security Features

  • HMAC-SHA256 signing
  • IP address binding
  • Role-based claims
  • Audit trail tracking

Security Features

IP Whitelist Protection

Restrict access to specific IP addresses or ranges for enhanced security.

  • Single IP address filtering
  • CIDR range support
  • Multiple IP configuration
  • Real-time validation

HMAC Signature Validation

Cryptographic signatures prevent replay attacks and ensure data integrity.

  • SHA-256 hash algorithm
  • Timestamp validation
  • Anti-replay protection
  • Request body verification

Audit Logging

Comprehensive logging of all authentication events and system activities.

  • Login/logout tracking
  • Token generation logs
  • Failed attempt monitoring
  • IP address recording

Credential Security

Secure handling of client credentials with one-time display and regeneration.

  • One-time credential display
  • Automatic credential masking
  • Secure regeneration
  • bcrypt/scrypt hashing

Implementation Examples

PHP Laravel Integration

Complete Laravel middleware for CAS authentication. 

// Install the CAS client package
composer require one-system/client

// Configure in config/cas.php
return [
    'cas_url' => env('CAS_URL', 'https://cas.example.com'),
    'client_id' => env('CAS_CLIENT_ID'),
    'client_secret' => env('CAS_CLIENT_SECRET'),
];

// Use middleware in routes
Route::middleware(['cas.auth'])->group(function () {
    Route::get('/dashboard', 'DashboardController@index');
});

// Access user information
$user = Auth::user(); // CAS authenticated user

Node.js Express Integration

Express.js middleware for JWT token validation. 

const jwt = require('jsonwebtoken');
const axios = require('axios');

// CAS authentication middleware
const casAuth = async (req, res, next) => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  
  if (!token) {
    return res.status(401).json({ error: 'No token provided' });
  }

  try {
    // Validate token with CAS
    const response = await axios.post('https://cas.example.com/api/sso/validate', {
      token: token
    });

    req.user = response.data.user;
    next();
  } catch (error) {
    res.status(401).json({ error: 'Invalid token' });
  }
};

// Use middleware
app.use('/protected', casAuth);
app.get('/protected/dashboard', (req, res) => {
  res.json({ user: req.user });
});

JavaScript Frontend Integration

Frontend JavaScript for handling CAS authentication. 

// CAS authentication class
class CASAuth {
  constructor(casUrl, clientId) {
    this.casUrl = casUrl;
    this.clientId = clientId;
    this.token = localStorage.getItem('cas_token');
  }

  async login(username, password) {
    const response = await fetch(`${this.casUrl}/api/login`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ username, password })
    });

    const data = await response.json();
    this.token = data.token;
    localStorage.setItem('cas_token', this.token);
    return data;
  }

  async makeAuthenticatedRequest(url, options = {}) {
    return fetch(url, {
      ...options,
      headers: {
        ...options.headers,
        'Authorization': `Bearer ${this.token}`
      }
    });
  }
}

// Usage
const cas = new CASAuth('https://cas.example.com', 'your_client_id');
cas.login('[email protected]', 'password');

Quick Links

API Reference

Complete API documentation

Code Examples

Implementation examples

Documentation Home

Return to main docs