stargate

README

Stargate - Forward Auth Service

🚀 Your Gateway to Secure Microservices

Stargate is a production-ready, lightweight Forward Auth Service designed to be the single point of authentication for your entire infrastructure. Built with Go and optimized for performance, Stargate seamlessly integrates with Traefik and other reverse proxies to protect your backend services—without writing a single line of auth code in your applications.

🌐 Multi-language Documentation

• English | 中文 | Français | Italiano | 日本語 | Deutsch | 한국어

🎯 Why Stargate?

Tired of implementing authentication logic in every service? Stargate solves this by centralizing authentication at the edge, allowing you to:

• ✅ Protect multiple services with a single authentication layer
• ✅ Reduce code complexity by removing auth logic from your applications
• ✅ Deploy in minutes with Docker and simple configuration
• ✅ Scale effortlessly with minimal resource footprint
• ✅ Maintain security with multiple encryption algorithms and secure session management

💼 Use Cases

Stargate is perfect for:

• Microservices Architecture: Protect multiple backend services without modifying application code
• Multi-Domain Applications: Share authentication sessions across different domains and subdomains
• Internal Tools & Dashboards: Quickly add authentication to internal services and admin panels
• API Gateway Integration: Use with Traefik, Nginx, or other reverse proxies as a unified auth layer
• Development & Testing: Simple password-based auth for development environments
• Enterprise Authentication: Integration with Warden (user whitelist) and Herald (OTP/verification codes) for production-grade authentication

✨ Features

🔐 Enterprise-Grade Security

• Multiple Password Encryption Algorithms: Choose from plaintext (testing), bcrypt, MD5, SHA512, and more
• Secure Session Management: Cookie-based sessions with customizable domain and expiration
• Flexible Authentication: Support for both password-based and session-based authentication
• OTP/Verification Code Support: Integration with Herald service for SMS/Email verification codes
• User Whitelist Management: Integration with Warden service for user access control

🌐 Advanced Capabilities

• Cross-Domain Session Sharing: Seamlessly share authentication sessions across different domains/subdomains
• Multi-Language Support: Built-in English and Chinese interfaces, easily extensible for more languages
• Customizable UI: Brand your login page with custom titles and footer text

🚀 Performance & Reliability

• Lightweight & Fast: Built on Go and Fiber framework for exceptional performance
• Minimal Resource Usage: Low memory footprint, perfect for containerized environments
• Production Ready: Battle-tested architecture designed for reliability

📦 Developer Experience

• Docker First: Complete Docker image and docker-compose configuration out of the box
• Traefik Native: Zero-configuration Traefik Forward Auth middleware integration
• Simple Configuration: Environment variable-based configuration, no complex files needed

📋 Table of Contents

• Quick Start
• Documentation
• Basic Configuration
• Optional Service Integration
• Production Checklist
• License

🚀 Quick Start

Get Stargate up and running in under 2 minutes!

Using Docker Compose (Recommended)

Step 1: Clone the repository

git clone <repository-url>
cd stargate

Step 2: Configure your authentication (edit docker-compose.yml)

Option A: Password Authentication (Simple)

services:
  stargate:
    environment:
      - AUTH_HOST=auth.example.com
      - PASSWORDS=plaintext:yourpassword1|yourpassword2

Option B: Warden + Herald OTP Authentication (Production)

services:
  stargate:
    environment:
      - AUTH_HOST=auth.example.com
      - WARDEN_ENABLED=true
      - WARDEN_URL=http://warden:8080
      - WARDEN_API_KEY=your-warden-api-key
      - HERALD_ENABLED=true
      - HERALD_URL=http://herald:8080
      - HERALD_HMAC_SECRET=your-herald-hmac-secret

Step 3: Start the service

docker-compose up -d

That's it! Your authentication service is now running. 🎉

Local Development

For local development, ensure Go 1.26+ is installed, then:

chmod +x start-local.sh
./start-local.sh

Access the login page at http://localhost:8080/_login?callback=localhost

📚 Documentation

Comprehensive documentation is available to help you get the most out of Stargate:

Core Documents

• 📐 Architecture Document - Deep dive into technical architecture and design decisions
• 🔌 API Document - Complete API endpoint reference with examples
• ⚙️ Configuration Reference - Detailed configuration options and best practices
• 🚀 Deployment Guide - Production deployment strategies and recommendations

Quick Reference

• API Endpoints: GET /_auth (auth check), GET /_login (login page), POST /_login (login), POST /_send_verify_code (send OTP), GET /_logout (logout), GET /_session_exchange (cross-domain), GET /totp/enroll, POST /totp/enroll/confirm, GET /totp/revoke, POST /totp/revoke (TOTP when Herald TOTP enabled), GET /health (health check), GET /metrics (Prometheus)
• Deployment: Docker Compose recommended for quick start. See DEPLOYMENT.md for production deployment.
• Development: For development-related documentation, see ARCHITECTURE.md

⚙️ Basic Configuration

Stargate uses environment variables for configuration. Here are the most common settings:

Required Configuration

• AUTH_HOST: Hostname of the authentication service (e.g., auth.example.com)
• PASSWORDS: Password configuration in format algorithm:password1|password2|password3

Common Configuration Examples

# Simple password authentication
AUTH_HOST=auth.example.com
PASSWORDS=plaintext:test123|admin456

# Using BCrypt hash
PASSWORDS=bcrypt:$2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy

# Cross-domain session sharing
COOKIE_DOMAIN=.example.com

# Customize login page
LOGIN_PAGE_TITLE=My Auth Service
LANGUAGE=zh  # or 'en'

Supported password algorithms: plaintext (testing only), bcrypt, md5, sha512

For complete configuration reference, see: docs/enUS/CONFIG.md

🔗 Optional Service Integration

Stargate can be used completely independently, or optionally integrate with the following services:

Warden Integration (User Whitelist)

Provides user whitelist management and user information. When enabled, Stargate queries Warden to verify if a user is in the allowed list.

WARDEN_ENABLED=true
WARDEN_URL=http://warden:8080
WARDEN_API_KEY=your-api-key

Herald Integration (OTP/Verification Codes)

Provides OTP/verification code services. When enabled, Stargate calls Herald to create, send, and verify verification codes (SMS/Email).

HERALD_ENABLED=true
HERALD_URL=http://herald:8080
HERALD_HMAC_SECRET=your-hmac-secret  # Production
# or
HERALD_API_KEY=your-api-key  # Development

Authenticator QR Bind + Account + 6-digit TOTP (Already Supported)

The target flow "bind Authenticator with a dynamic QR code, then sign in with account + 6-digit TOTP" is already available in current Stargate and does not require new feature development. Configure and use it as follows:

# Stargate
WARDEN_ENABLED=true
WARDEN_URL=http://warden:8080
HERALD_ENABLED=true
HERALD_URL=http://herald:8080
HERALD_TOTP_ENABLED=true
HERALD_API_KEY=your-herald-api-key               # Development
# or
HERALD_HMAC_SECRET=your-herald-hmac-secret       # Production

• Warden: ensure lookup by phone/email returns user_id and contact fields (phone/mail).
• Herald: configure Herald to proxy TOTP to herald-totp (HERALD_TOTP_ENABLED, HERALD_TOTP_BASE_URL, etc. on Herald). herald-totp needs HERALD_TOTP_ENCRYPTION_KEY (32 bytes) and service auth (API_KEY or HMAC_SECRET).
• Login UX: users not yet bound sign in with verification code first, then bind at /totp/enroll; bound users check Use TOTP and submit a 6-digit code.

Note: Both integrations are optional. Stargate can be used independently with password authentication.

For complete integration guide, see: docs/enUS/ARCHITECTURE.md

⚠️ Production Checklist

Before deploying to production:

• ✅ Use strong password algorithms (bcrypt or sha512, avoid plaintext)
• ✅ Enable HTTPS via Traefik or your reverse proxy
• ✅ Set COOKIE_DOMAIN for proper session management across subdomains
• ✅ For advanced features, optionally integrate Warden + Herald for OTP authentication
• ✅ Use HMAC signatures or mTLS for Stargate ↔ Herald/Warden communication
• ✅ Set up appropriate logging and monitoring
• ✅ Keep Stargate updated to the latest version

🎯 Design Principles

Stargate is designed to be used independently:

• Standalone Usage: Can run independently using password authentication mode without any external dependencies
• Optional Integration: Can optionally integrate with Warden (user whitelist) and Herald (OTP/verification codes) services
• High Performance: forwardAuth main path only verifies sessions, ensuring fast response
• Flexibility: Supports multiple authentication modes, choose according to your needs

📝 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

🤝 Contributing

We welcome contributions! Whether it's bug reports, feature suggestions, documentation improvements, or code contributions, please feel free to open an Issue or submit a Pull Request.