CAS SSO API Reference

Enterprise-grade API documentation for CAS authentication with enhanced security features

reCAPTCHA v3 Protected
Account Lockout System
Rate Limited (5/min)

Base URL & Security

http://localhost:8000/api  # Laravel CAS Server
http://localhost:5000/api  # Express.js CAS Server

All API endpoints are protected by multiple security layers:

Security Requirements

  • • IP Whitelisting: Client IPs must be registered in the system
  • • Rate Limiting: Maximum 5 requests per minute per IP
  • • HMAC Signature: All requests require valid HMAC-SHA256 signatures
  • • Account Lockout: 5 failed attempts = 30-minute lockout
  • • reCAPTCHA: Human verification on login forms

Authentication

POST /sso/token

Generate an SSO token for authenticated users.

Request Headers:

Content-Type: application/json
X-Signature: sha256=HMAC_SHA256_SIGNATURE
X-Timestamp: 1640995200

Request Body:

{
  "email": "[email protected]",
  "password": "SecureP@ss123!",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "client_username": "your_client_username",
  "client_password": "encrypted_client_password",
  "g-recaptcha-response": "recaptcha_token",
  "remember": true
}

Success Response (200):

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "email": "[email protected]",
    "username": "john_doe",
    "first_name": "John",
    "last_name": "Doe",
    "role": "user",
    "is_2fa_enabled": true,
    "last_login": "2025-08-07T10:30:00Z"
  },
  "expires_at": "2025-08-07T22:30:00Z",
  "token_type": "Bearer",
  "security_features": {
    "2fa_enabled": true,
    "account_locked": false,
    "remaining_attempts": 5,
    "lockout_until": null
  }
}

Error Responses:

// 401 - Invalid Credentials
{
  "error": "Invalid credentials",
  "attempts_remaining": 3,
  "lockout_warning": "Account will be locked after 2 more failed attempts"
}

// 423 - Account Locked
{
  "error": "Account temporarily locked due to multiple failed attempts",
  "lockout_until": "2025-08-07T11:00:00Z",
  "remaining_minutes": 25
}

// 429 - Rate Limited
{
  "error": "Too many login attempts. Please try again in 45 seconds.",
  "retry_after": 45
}

POST /sso/validate

Validate an SSO token and get user information.

Request Headers:

Content-Type: application/json
Authorization: Bearer CLIENT_TOKEN
X-Signature: sha256=HMAC_SHA256_SIGNATURE
X-Timestamp: 1640995200

Request Body:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "timestamp": 1640995200
}

Response:

{
  "success": true,
  "user": {
    "id": 1,
    "username": "john_doe",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe",
    "role": "user"
  },
  "expires_at": "2025-01-10T12:00:00Z"
}

User Management

GET /user

Get current authenticated user information.

Headers:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response:

{
  "id": 1,
  "username": "john_doe",
  "email": "[email protected]",
  "first_name": "John",
  "last_name": "Doe",
  "role": "user",
  "is_active": true,
  "created_at": "2025-01-01T00:00:00Z"
}

POST /register

Register a new user account.

Request Body:

{
  "username": "new_user",
  "email": "[email protected]",
  "password": "secure_password",
  "first_name": "New",
  "last_name": "User"
}

Response:

{
  "success": true,
  "user": {
    "id": 2,
    "username": "new_user",
    "email": "[email protected]",
    "first_name": "New",
    "last_name": "User",
    "role": "user",
    "is_active": true,
    "created_at": "2025-01-10T12:00:00Z"
  }
}

Client System Management

GET /client-systems

Get all registered client systems (Admin only).

Response:

{
  "success": true,
  "client_systems": [
    {
      "id": 1,
      "name": "Customer Portal",
      "url": "http://localhost:9000",
      "callback_url": "http://localhost:9000/cas/callback",
      "is_active": true,
      "users_online": 5,
      "sso_version": "v2.1.0",
      "status": "active",
      "icon": "fas fa-users",
      "color": "blue",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ]
}

POST /client-systems

Register a new client system (Admin only).

Request Body:

{
  "name": "New Application",
  "url": "http://localhost:4000",
  "callback_url": "http://localhost:4000/cas/callback",
  "client_secret": "generated_secret_key"
}

Error Responses

HTTP Status Codes

  • 200: Success
  • 201: Created
  • 400: Bad Request
  • 401: Unauthorized
  • 403: Forbidden
  • 404: Not Found
  • 500: Internal Server Error

Error Response Format

{
  "success": false,
  "error": "Authentication failed",
  "message": "Invalid username or password",
  "code": "AUTH_FAILED"
}

Code Examples

JavaScript (Fetch)

// Generate SSO token
async function generateSSOToken(username, password) {
    const response = await fetch('http://localhost:5000/api/sso/token', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            username,
            password,
            client_id: 'your_client_id',
            client_username: 'your_client_username',
            client_password: 'your_client_password'
        })
    });

    const data = await response.json();
    return data;
}

// Validate token
async function validateToken(token) {
    const response = await fetch('http://localhost:5000/api/sso/validate', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            token,
            client_username: 'your_client_username',
            client_password: 'your_client_password'
        })
    });

    const data = await response.json();
    return data;
}

PHP (cURL)

Python (requests)

import requests
import json

# Generate SSO token
def generate_sso_token(username, password):
    url = 'http://localhost:5000/api/sso/token'
    data = {
        'username': username,
        'password': password,
        'client_id': 'your_client_id',
        'client_username': 'your_client_username',
        'client_password': 'your_client_password'
    }

    response = requests.post(url, json=data)
    return response.json()

# Validate token
def validate_token(token):
    url = 'http://localhost:5000/api/sso/validate'
    data = {
        'token': token,
        'client_username': 'your_client_username',
        'client_password': 'your_client_password'
    }

    response = requests.post(url, json=data)
    return response.json()

Rate Limiting

Current Limits

  • Authentication endpoints: 10 requests per minute per IP
  • Token validation: 100 requests per minute per client
  • User management: 50 requests per minute per user

Next Steps