SecureAuth

SecureAuth is a complete authentication system implementing email-based signup, OTP verification, session-based login, logout, and password recovery using server-side sessions.

What problem it solves

• Replaces stateless JWTs with server-side, revocable authentication sessions
• Implements a complete authentication lifecycle from signup to recovery
• Handles critical auth edge cases like OTP expiry, session invalidation, and password resets

High level archiecture

• client → AuthAPI(backend)
• AuthAPI - Central authentication service handling all auth flows, validation, and security logic.
• PsotgreSQL - Persistent storage for user accounts, hashed passwords, and verification state.
• Redis - Ephemeral storage for OTPs and server-side sessions with TTL-based expiration
• Email Service - Delivers OTPs for email verification and password recovery.

Request flows

• Signup Flow: User registers with email and password, receives an OTP, and verifies the account before login.
• Login Flow: Verified users authenticate with credentials and receive a server-side session ID.
• Session Validation Flow: Authenticated requests validate active sessions stored in Redis.
• Logout Flow: User session is explicitly revoked, immediately invalidating access.
• Password Recovery Flow: Users reset forgotten passwords using OTP-based email verification.

API Endpoints

• POST /signup — Register a new user and send an email verification OTP.
• POST /verify-otp — Verify user email using the OTP and activate the account.
• POST /login — Authenticate user credentials and create a server-side session.
• POST /me — Validate an active session and return user context.
• POST /logout — Revoke the current session and log the user out.
• POST /forgot-password — Initiate password reset by sending an OTP to the user’s email.
• POST /reset-password — Validate OTP and securely update the user’s password.

Tech stack

• Python
• FastAPI
• Streamlit
• PostgreSQL
• Redis

Run locally

1. clone the repository

git clone https://github.com/yshvrd/SecureAuth
cd SecureAuth

2. Create and run a virtual environment

python3 -m venv .venv 
source .venv/bin/activate  #mac

3. install dependencies

pip install -r requirements.txt

4. create and configure a .env file at project root

# .env
SMTP_USER="youremail@gmail.com"
SMTP_EMAIL="youremail@gmail.com"
SMTP_PASSWORD=""      # use app passwords
SMTP_SERVER="smtp.gmail.com"
SMTP_PORT=465

5. Run database container and create table

docker run -d \
  --name secure-auth-db \
  -e POSTGRES_USER=secureauth \
  -e POSTGRES_PASSWORD=secureauth \
  -e POSTGRES_DB=secure-auth-db \
  -p 5432:5432 \
  postgres:16

cd backend 
python -m db.create_table

6. Run redis container

  docker run -d \
  --name secure-auth-redis \
  -p 6379:6379 \
  redis:7 \
  redis-server --requirepass secureauthredis

7. Start backend

cd backend 
uvicorn app:app --reload

8. Start frontend

cd frontend
streamlit run app.py

9. Interact with the app

http://localhost:8501

Limitations and future improvements

• No role-based access control or authorization beyond basic authentication
• Email delivery uses a simple SMTP setup without retry or bounce handling
• Sessions are not bound to device or IP for additional security hardening
• No rate limiting or brute-force protection on auth endpoints

Screenshots