Noureddine RAMDI / VoidAuth: a self-hosted OpenID Connect SSO provider for homelabs

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
1057 Words
github-stars typescript sso openid-connect homelab docker security

voidauth/voidauth

VoidAuth positions itself as a practical single sign-on (SSO) solution tailored specifically for the self-hosted and homelab crowd. It aims to bridge the gap between heavyweight enterprise identity providers like Keycloak or Authentik and the DIY approach of using nginx auth_request or similar reverse proxy scripts. The project bundles an OpenID Connect (OIDC) provider with a ForwardAuth reverse proxy handler, user and group management, multi-factor authentication, and modern security features like passkeys — all wrapped up in a Docker Compose deployment.

what voidauth does and how it works

At its core, VoidAuth is an open-source SSO provider written in TypeScript. It functions as a full OpenID Connect (OIDC) provider, which means it can handle authentication flows compliant with this standard, enabling you to use it as the central identity service for multiple self-hosted applications.

Uniquely, it also acts as a ForwardAuth handler for popular reverse proxies such as Caddy, Traefik, and Nginx. This lets you place VoidAuth in front of your self-hosted apps, intercepting authentication requests and managing access without each app needing its own auth logic.

The platform supports full user and group management, including features tailored for homelab usability: self-registration, invitation-based onboarding, and a clean admin interface for managing users and settings. Security-wise, it offers multi-factor authentication (MFA), passkey support, and even passkey-only accounts for modern passwordless login flows.

For storage, VoidAuth supports encryption-at-rest using either PostgreSQL or SQLite databases, providing flexibility depending on your infrastructure and scale.

Deployment is opinionated towards Docker-first setups with a single compose.yml file for easy spinning up. The admin panel is a polished web UI that lets you customize branding elements like logos, theme colors, and email templates, making it more personal or professional-looking.

technical strengths and design tradeoffs

The first thing to note is the choice of TypeScript for the entire stack. This brings type safety and modern JavaScript features, which improves maintainability and developer experience, especially in a complex authentication system.

VoidAuth’s architecture combines an OIDC provider with a ForwardAuth reverse proxy handler in one service. This is a clever design for the homelab use-case because it simplifies the authentication flow and reduces the number of moving parts you need to manage.

The inclusion of passkeys and passkey-only accounts is notable. Passkeys represent the future of passwordless authentication, and having them integrated early means VoidAuth is aligned with modern security standards. The multi-factor authentication support further solidifies its security posture.

Encryption-at-rest with PostgreSQL or SQLite is a strong feature for a self-hosted project. SQLite support lowers the barrier for smaller setups, while PostgreSQL scales better for larger or more demanding environments.

The tradeoff here is that VoidAuth is not designed to compete with large enterprise IdPs that come with complex federation, policy engines, or extensive plugin ecosystems. It deliberately focuses on simplicity, ease of deployment, and features that matter most in the homelab context.

The codebase is surprisingly clean and idiomatic TypeScript, adhering to modern async/await patterns and modular design. This makes it approachable for contributors and customizers.

One limitation is that the project currently assumes a Docker or containerized deployment model. While this fits the target audience perfectly, it might be less convenient for environments that prefer native installs or different orchestration.

quick start with docker compose

VoidAuth provides a straightforward Docker Compose setup that integrates the SSO service and its PostgreSQL backend. Here is the essential snippet from the recommended compose.yml:

services:
  # ---------------------------------
  # Your reverse-proxy service here:
  # caddy, traefik, nginx, etc.
  # ---------------------------------

  voidauth: 
    image: voidauth/voidauth:latest
    restart: unless-stopped
    volumes:
      - ./voidauth/config:/app/config
    environment:
      # Required environment variables
      # More environment variable options can be found 
      #   on the Getting Started page.
      APP_URL: # required, ex. https://auth.example.com
      STORAGE_KEY: # required
      DB_PASSWORD: # required, same as voidauth-db POSTGRES_PASSWORD
      DB_HOST: voidauth-db # required
    depends_on:
      voidauth-db:
        condition: service_healthy

  voidauth-db:
    image: postgres:18
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: # required, same as voidauth DB_PASSWORD
    volumes:
      - db:/var/lib/postgresql/18/docker
    healthcheck:
      test: "pg_isready -U postgres -h localhost"

volumes:
  db:

After configuring the environment variables (notably the APP_URL, STORAGE_KEY, and DB_PASSWORD), you run docker compose up -d to start the services.

An important note from the documentation: after the first start, look for a password reset link for the initial admin account in the container logs (docker compose logs voidauth). This lets you set a secure password and start managing users.

User onboarding is invitation-based by default, which fits well with private or semi-private homelabs.

verdict

VoidAuth fills a clear niche for the self-hosted community that needs a capable, modern SSO solution without the heavy baggage of enterprise identity providers. The combination of OIDC support, ForwardAuth proxy functionality, passkeys, MFA, and user/group management in a single Docker Compose setup is a solid value proposition.

While it lacks the extensibility and federation features of heavyweight IdPs, this is a conscious tradeoff for simplicity and ease of use.

If you run a homelab or self-hosted environment with multiple apps requiring centralized authentication, and you want modern security features like passkeys out-of-the-box, VoidAuth deserves a close look.

Its TypeScript codebase is clean and accessible for customization if you want to tweak behavior or add features.

The Docker-first deployment means getting up and running is quick and repeatable, but it may not fit every environment.

Overall, VoidAuth is a practical, well-engineered solution that solves a real pain point in the homelab space without overcomplicating the setup.

→ GitHub Repo: voidauth/voidauth ⭐ 2,128 · TypeScript