The Problem

Organizations operating self-hosted application stacks often require a centralized identity gateway to manage authentication, authorization, and user provisioning. Building a production-grade Identity Provider (IdP) with OIDC, LDAP integration, MFA, and password management is resource-intensive. VoidAuth addresses this pain point by providing a ready-deployed SSO layer that sits in front of existing infrastructure.

What This Does

The repository is architected as a full-stack TypeScript application. The backend (server/) is an Express application that handles authentication protocols, database persistence, and API routing. The frontend (frontend/) is an Angular application bootstrapped from frontend/src/main.ts, providing the user portal and admin interface. Key directories include shared/, which likely contains logic abstracted from the framework-specific layers, and migrations/, which manages database schema evolution for the supported Postgres and SQLite backends. Configuration is primarily driven by environment variables defined in compose.yml rather than scattered static config files.

How It Is Wired

Execution begins at server/index.ts, which initializes the Express application and registers routes for OIDC callbacks, LDAP binding, and user management. The server interacts with the database through an ORM layer (implied by the migrations/ directory and Postgres dependency), handling user creation, password hashing, and session management. On the frontend, frontend/src/app/app.routes.ts defines the navigation hierarchy, while guards such as frontend/src/app/guards/is-admin.guard.ts enforce role-based access control at the route level. The system routes user authentication through protocol-specific handlers before establishing a session or redirecting to the application backend.

How To Use It

Setup: The recommended installation method uses Docker Compose. The entry point is the docker compose up -d command, which orchestrates the voidauth service and its database dependency defined in compose.yml.

Configuration: Required environment variables must be set within the compose.yml file or a corresponding .env file. The critical variables are:

  • APP_URL: The public facing URL (e.g., https://auth.example.com).
  • STORAGE_KEY: A required key for data encryption.
  • DB_PASSWORD: Must match the POSTGRES_PASSWORD defined for the voidauth-db service.

Running it: After creating the compose.yml file and populating the environment variables, start the stack with:

docker compose up -d

Visit the APP_URL to access the portal. On first startup, consult the voidauth logs (docker compose logs voidauth) to find the password reset link for the initial admin account.

Real-World Use

In a typical deployment, VoidAuth sits behind a reverse proxy (Caddy, Traefik, or Nginx) at the network edge. It authenticates users against configured OIDC providers or an LDAP directory (docs/LDAP-Guides.md) and issues short-lived tokens. The admin configures these identity sources via the Admin Panel, after which users authenticate once and gain seamless access to the internal self-hosted application mesh without re-entering credentials.

Code Health & Issues

  • Test Coverage (Medium): Static analysis indicates only 5 test files exist across 433 total files, suggesting limited automated test coverage for the core authentication logic.
  • License (Low): The project is licensed under AGPL-3.0. Modifications to the source code require corresponding release of object files under the same license, which is a legal consideration for commercial integration.
  • Configuration (Low): Secrets and connection strings are managed via environment variables in compose.yml. No explicit secret detection or management tools are configured within the .github workflows, though dependabot.yml is present for dependency updates.

The Bottom Line

VoidAuth is a pragmatic, open-source solution for teams needing to add SSO, LDAP integration, and user management to self-hosted applications without building a custom IdP. The trade-off is a codebase with sparse test coverage and a strong copyleft license (AGPL-3.0) that mandates source sharing for modifications. It is well-suited for developers and DevOps teams prioritizing rapid deployment of standard authentication flows over deep customization of the underlying auth logic.