Skip to content

README.md

Latest commit

 

History

History
196 lines (135 loc) · 4.93 KB

README.md

File metadata and controls

196 lines (135 loc) · 4.93 KB
Raw

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.