TinyAuth — Minimal Self-Hosted Authentication & Authorization Proxy

Introduction

TinyAuth is an extremely lightweight authentication and authorization proxy designed for homelab and self-hosted setups. It sits behind your reverse proxy (Nginx, Caddy, Traefik) and protects services with username/password login, optional TOTP two-factor authentication, and OAuth/OIDC single sign-on — all in a single small container.

What TinyAuth Does

• Provides forward authentication for reverse proxies to protect any web service
• Supports local user accounts with bcrypt-hashed passwords
• Enables TOTP-based two-factor authentication for additional security
• Integrates with OAuth2 and OpenID Connect providers like Google and GitHub for SSO
• Controls per-service access with user and group-based authorization rules

Architecture Overview

TinyAuth is a single Go binary that runs an HTTP server handling authentication flows. It works as a forward auth middleware: the reverse proxy sends each incoming request to TinyAuth, which checks for a valid session cookie and returns 200 (allow) or 401 (redirect to login). Sessions are stored in encrypted cookies, so there is no external database dependency. Configuration is entirely through environment variables or a simple YAML file.

Self-Hosting & Configuration

• Deploy as a single Docker container with minimal resource requirements
• Define users via the USERS environment variable in username:bcrypt_hash:role format
• Set SECRET for secure session cookie encryption
• Configure your reverse proxy (Traefik, Nginx, Caddy) to use TinyAuth as forward auth endpoint
• Add OAuth provider credentials with OAUTH_PROVIDERS for Google, GitHub, or custom OIDC

Key Features

• Sub-10 MB container image with instant startup
• Forward auth compatible with Traefik, Nginx, Caddy, and any proxy supporting auth subrequests
• TOTP two-factor authentication with QR code enrollment
• OAuth2/OIDC integration for Google, GitHub, and custom providers
• Per-service access rules with user and group-based policies

Comparison with Similar Tools

• Authelia — Full-featured auth server with regulation and notification; TinyAuth is simpler with near-zero config
• Authentik — Enterprise identity provider; TinyAuth targets homelab setups with minimal overhead
• OAuth2 Proxy — Focused on OAuth proxy; TinyAuth adds local users, TOTP, and group-based authorization
• Keycloak — Heavy Java-based IAM platform; TinyAuth runs in a fraction of the resources
• Caddy Security — Built into Caddy only; TinyAuth works with any reverse proxy

FAQ

Q: How do I generate bcrypt password hashes for users? A: Use htpasswd -nbBC 10 "" yourpassword | cut -d: -f2 or any online bcrypt generator.

Q: Can TinyAuth protect non-web services? A: It works with any service behind a reverse proxy that supports forward auth. Non-HTTP services are not covered.

Q: Where are sessions stored? A: Sessions are stored in encrypted cookies on the client. No server-side database is needed.

Q: Does TinyAuth support multiple domains? A: Yes, configure your reverse proxy to route auth requests from multiple domains to the same TinyAuth instance.

Sources

• https://github.com/steveiliop56/tinyauth
• https://tinyauth.dev