OpenCAS - FastAPI CAS Authentication

A FastAPI implementation of IIIT CAS (Central Authentication Service) authentication.

Features

• CAS Authentication: Secure login using IIIT's CAS server
• Authentication API: Provides CAS validation as a service for other applications
• Session Management: User sessions with secure cookies

Project Structure

OpenCAS/
├── main.py                 # Main FastAPI application
├── requirements.txt        # Python dependencies
├── .env                    # Environment variables (not in git)
├── .env.example            # Example environment variables
├── .gitignore              # Git ignore rules
├── README.md               # This file
└── templates/              # HTML templates
    ├── index.html          # Home page
    └── dashboard.html      # Protected dashboard

Installation

Using Docker (Recommended)

The easiest way to run OpenCAS is using Docker:

1. Configure environment variables:

   • Copy .env.example to .env
   • Update the SECRET_KEY with a secure random string

   Copy-Item .env.example .env

2. Build and run with Docker Compose:

   docker-compose up --build

3. Open your browser: Navigate to http://localhost:8000

The application will be running in a container with all dependencies managed by uv.

Manual Installation (Development)

If you prefer to run without Docker:

1. Install uv (if not already installed):

   pip install uv

2. Install dependencies:

   uv sync

3. Configure environment variables:

   • Copy .env.example to .env
   • Update the SECRET_KEY with a secure random string

   Copy-Item .env.example .env

Running the Application

Using Docker

With Docker Compose (recommended):

docker-compose up

Or build and run directly with Docker:

# Build the image
docker build -t opencas .

# Run the container
docker run -p 8000:80 --env-file .env opencas

Using uv (Development)

uv run fastapi dev main.py

Legacy Python/uvicorn

# Using the main script
python main.py

# Or using uvicorn directly
uvicorn main:app --reload

Access the application at http://localhost:8000

How CAS Authentication Works

1. User clicks "Login with CAS":

   • User is redirected to IIIT's CAS server at https://login.iiit.ac.in/cas/login
   • The service URL (your app's URL) is passed as a parameter

2. User authenticates on CAS:

   • User enters their IIIT credentials on the CAS server
   • CAS validates the credentials

3. CAS redirects back with ticket:

   • Upon successful authentication, CAS redirects back to your app with a ticket parameter
   • Example: http://localhost:8000/?ticket=ST-xxxxx-xxxxx

4. Ticket validation:

   • Your app validates the ticket by making a server-to-server request to CAS
   • URL: https://login.iiit.ac.in/cas/serviceValidate?ticket=xxx&service=xxx
   • CAS returns XML with user information

5. Session creation:

   • User information is extracted from the XML response
   • A session is created with user data
   • User is redirected to the dashboard

API Endpoints

Public Routes

• GET / - Home page (login button or user info), also handles CAS callback with ticket
• GET /login - Initiates CAS login flow (redirects to CAS server)
• GET /logout - Clears session and logs out user

Protected Routes

• GET /dashboard - User dashboard (requires authentication)
• GET /api/me - Returns current user information as JSON (requires authentication)

User Information

The following user information is extracted from CAS:

• Username: Unique user identifier
• Email: User's email address
• Name: Full name (first + last name)
• Roll Number: Student roll number
• First Name: User's first name
• Last Name: User's last name

Configuration

Environment Variables

Create a .env file with the following variables:

SECRET_KEY=your-secret-key-change-this-in-production
APP_URL=http://localhost:8000

Important: Change the SECRET_KEY to a secure random string in production!

CAS Server Configuration

The CAS server URLs are configured in main.py:

CAS_SERVER_URL = "https://login.iiit.ac.in/cas"
CAS_LOGIN_URL = f"{CAS_SERVER_URL}/login"
CAS_VALIDATE_URL = f"{CAS_SERVER_URL}/serviceValidate"

Dependencies

• FastAPI: Modern web framework for building APIs
• Uvicorn: ASGI server for running FastAPI
• httpx: Async HTTP client for making requests to CAS
• xmltodict: XML parsing for CAS responses
• python-dotenv: Environment variable management
• Jinja2: Template engine for HTML rendering
• itsdangerous: Secure session cookie signing

Contributing

Feel free to submit issues or pull requests to improve this implementation.