chatbotgate

ChatbotGate

English | 日本語

ChatbotGate is a lightweight, flexible authentication reverse proxy that sits in front of your upstream applications and provides unified authentication through multiple OAuth2 providers and passwordless email authentication.

Features

🔐 Multiple Authentication Methods

• OAuth2/OIDC: Google, GitHub, Microsoft, and custom OIDC providers
• Passwordless Email: Magic link authentication via SMTP, SendGrid, or sendmail
• Mix and match providers for different user groups

🛡️ Flexible Access Control

• Email and domain-based whitelisting
• Path-based access rules (allow, auth, deny)
• Pattern matching (exact, prefix, regex, minimatch)
• First-match-wins rule evaluation

🔄 Seamless Reverse Proxy

• Transparent proxying of HTTP/WebSocket requests
• Server-Sent Events (SSE) streaming support
• X-Forwarded headers (X-Real-IP, X-Forwarded-For, X-Forwarded-Proto, X-Forwarded-Host)
• Large file handling with 32KB buffer pool
• Configurable authentication path prefix (default: /_auth)
• Host-based routing for multi-tenant deployments
• Automatic upstream secret header injection

📦 Multiple Storage Backends

• Memory: Fast, ephemeral storage for development
• LevelDB: Persistent, embedded database
• Redis: Distributed, scalable storage for production
• Unified KVS interface with namespace isolation

🎨 User-Friendly Interface

• Clean, responsive authentication UI
• Multi-language support (English/Japanese)
• Theme switcher (Auto/Light/Dark)
• Customizable branding (logo, icon, colors)

🔌 User Information Forwarding

• Forward authenticated user data to upstream apps
• Flexible field mapping (email, username, provider, etc.)
• Encryption and compression support (AES-256-GCM, gzip)
• Query parameters and HTTP headers

⚙️ Production-Ready

• Environment variable expansion in config files (${VAR:-default})
• Live configuration reloading (most settings)
• Configuration validation tool (test-config)
• Shell completion (bash, zsh, fish, powershell)
• Health check endpoints (/_auth/health)
• Structured logging with configurable levels
• Email send rate limiting (prevents abuse of magic link emails)
• Comprehensive test coverage
• Docker support with multi-arch images (amd64/arm64)

Quick Start

Installation

From Source:

git clone https://github.com/ideamans/chatbotgate.git
cd chatbotgate
go build -o chatbotgate ./cmd/chatbotgate

Using Docker:

# Pull latest version (multi-arch: amd64/arm64)
docker pull ideamans/chatbotgate:latest

# Or pull specific version
docker pull ideamans/chatbotgate:v1.0.0

Docker images are automatically built and published to Docker Hub on every release.

Basic Configuration

Create a config.yaml file. You can use environment variables with ${VAR} or ${VAR:-default} syntax:

service:
  name: "My App Auth"

server:
  host: "0.0.0.0"
  port: 4180
  # Base URL for OAuth2 callbacks (auto-generated: {base_url}/_auth/oauth2/callback)
  # Set when behind reverse proxy or using HTTPS
  # base_url: "https://your-domain.com"

proxy:
  upstream:
    # Use environment variable with fallback
    url: "${UPSTREAM_URL:-http://localhost:8080}"

session:
  cookie:
    # Use environment variable for secrets (recommended)
    secret: "${COOKIE_SECRET:-CHANGE-THIS-TO-A-RANDOM-SECRET}"
    expire: "168h"

oauth2:
  providers:
    - id: "google"
      type: "google"
      # Credentials from environment variables
      client_id: "${GOOGLE_CLIENT_ID}"
      client_secret: "${GOOGLE_CLIENT_SECRET}"

access_control:
  emails:
    - "@example.com"  # Allow all @example.com emails

Setting environment variables:

export COOKIE_SECRET="$(openssl rand -base64 32)"
export GOOGLE_CLIENT_ID="your-client-id"
export GOOGLE_CLIENT_SECRET="your-client-secret"
export UPSTREAM_URL="http://localhost:8080"

Validate Configuration

Before starting, validate your configuration:

./chatbotgate test-config -c config.yaml

Run the Server

./chatbotgate -config config.yaml

Visit http://localhost:4180 to see the authentication flow in action.

Shell Completion (Optional)

Generate shell completion for easier CLI usage:

# Bash
./chatbotgate completion bash > /etc/bash_completion.d/chatbotgate

# Zsh
./chatbotgate completion zsh > ~/.zsh/completion/_chatbotgate

# Fish
./chatbotgate completion fish > ~/.config/fish/completions/chatbotgate.fish

# PowerShell
./chatbotgate completion powershell > chatbotgate.ps1

Documentation

• User Guide (GUIDE.md) - Complete guide for deploying and configuring ChatbotGate
• Module Guide (MODULE.md) - Developer guide for using ChatbotGate as a Go module
• Examples Directory - Production-ready deployment examples (Docker, systemd, full configurations)

Project Structure

chatbotgate/
├── cmd/
│   └── chatbotgate/          # Main entry point and CLI
├── pkg/
│   ├── middleware/           # Authentication middleware
│   │   ├── auth/             # OAuth2 and email auth
│   │   ├── authz/            # Authorization (whitelisting)
│   │   ├── session/          # Session management
│   │   ├── rules/            # Path-based access control
│   │   ├── forwarding/       # User info forwarding
│   │   └── ...
│   ├── proxy/                # Reverse proxy
│   └── shared/               # Shared components
│       ├── kvs/              # Key-value store interface
│       ├── i18n/             # Internationalization
│       └── logging/          # Structured logging
├── web/                      # Web assets (HTML, CSS, JS)
├── email/                    # Email templates
├── e2e/                      # End-to-end tests
├── config.example.yaml       # Example configuration
└── README.md                 # This file

How It Works

┌─────────┐      ┌──────────────┐      ┌──────────┐
│  User   │─────▶│ ChatbotGate  │─────▶│ Upstream │
│ Browser │      │    (Auth)    │      │   App    │
└─────────┘      └──────────────┘      └──────────┘
     ▲                  │
     │                  ▼
     │           ┌─────────────┐
     └───────────│   OAuth2    │
                 │  Provider   │
                 └─────────────┘

1. User Request → ChatbotGate checks authentication
2. Not Authenticated → Redirect to /_auth/login
3. User Chooses → OAuth2 or Email authentication
4. Authentication Success → Session created, redirect to original URL
5. Authenticated Request → Proxied to upstream with user info headers

Development

Prerequisites

• Go 1.21 or later
• Node.js 20+ (for web assets and e2e tests)
• Docker & Docker Compose (optional, for containerized development)
• Redis (optional, for distributed sessions)

Build

# Build everything (web assets + go binary)
make build

# Build only Go binary
make build-go

# Build only web assets
make build-web

Code Quality

# Format code
make fmt

# Check formatting (CI)
make fmt-check

# Run linters
make lint

# Run all CI checks (format + lint + test)
make ci

Running Tests

# Run all unit tests
make test

# Run tests with coverage report
make test-coverage

# Run specific package tests
go test ./pkg/middleware/auth/oauth2

# Run with verbose output
go test -v ./pkg/...

# Run e2e tests (requires Docker)
cd e2e && make test

Docker Build

# Build image
docker build -t chatbotgate .

# Run with docker-compose
docker-compose up

Configuration

ChatbotGate is configured via YAML with support for environment variable expansion (${VAR:-default}).

Basic example:

service:
  name: "My App"

server:
  port: 4180

session:
  cookie:
    secret: "${COOKIE_SECRET}"  # Environment variable
    expire: "168h"

oauth2:
  providers:
    - id: "google"
      type: "google"
      client_id: "${GOOGLE_CLIENT_ID}"
      client_secret: "${GOOGLE_CLIENT_SECRET}"

proxy:
  upstream:
    url: "http://localhost:8080"

For complete configuration:

• See config.example.yaml - Comprehensive example with all options
• See GUIDE.md - Configuration - Detailed configuration guide
• See examples/ - Production-ready deployment examples

Use Cases

• Chatbot Widget Authentication: Protect chatbot interfaces (Dify, Rasa, etc.) with OAuth2 or email authentication
• Internal Tool Access Control: Add authentication to internal tools that lack their own auth system
• Multi-Tenant Applications: Route requests to different upstream backends based on hostname
• API Gateway with Auth: Combine reverse proxy and authentication for microservices

Logging

ChatbotGate supports structured logging with multiple backends:

# systemd/journald (recommended for production)
journalctl -u chatbotgate -f

# Docker logs
docker logs -f chatbotgate

# File logging (for non-systemd environments)
# Configured via logging.file in config.yaml

For complete logging documentation, see GUIDE.md - Logging

Health Checks

ChatbotGate provides health check endpoints for container orchestration:

• Readiness: GET /_auth/health (200 when ready, 503 when starting/draining)
• Liveness: GET /_auth/health?probe=live (200 if process alive)

Example Docker health check:

healthcheck:
  test: ["CMD-SHELL", "curl -fsS http://localhost:4180/_auth/health || exit 1"]
  interval: 5s
  timeout: 2s
  retries: 12

For complete health check documentation, see GUIDE.md - Health Checks

Security Considerations

• Cookie Secret: Use a strong random secret (32+ characters)
• HTTPS: Always use HTTPS in production (set cookie_secure: true)
• Secrets Storage: Use environment variables or secret managers for sensitive data
• Upstream Secret: Protect your upstream from direct access with secret headers
• Whitelisting: Restrict access by email/domain when possible
• Email Rate Limiting: Configure email_auth.limit_per_minute to prevent magic link abuse (default: 5/min)

For comprehensive security guide, see GUIDE.md - Security Best Practices

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow Go best practices and idioms
• Write tests for new features (aim for 80%+ coverage)
• Update documentation for user-facing changes
• Run make ci before committing to ensure all checks pass
• Format code with make fmt
• Keep commits atomic and write clear commit messages

For module development, see MODULE.md - Developer guide for using ChatbotGate as a Go module

CI/CD Pipeline

ChatbotGate uses GitHub Actions for continuous integration and deployment:

• CI (on push/PR): Runs linting, formatting checks, unit tests, and e2e tests
• Release (on tag): Builds binaries with GoReleaser and publishes Docker images to Docker Hub
• Docker Images: Multi-architecture (amd64/arm64) images published to ideamans/chatbotgate

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Acknowledgments

• Inspired by oauth2-proxy
• Built with Go, fsnotify, and many other great libraries

Made with ❤️ for the authentication-challenged web