Skip to main content

AuthProxy Documentation

Welcome to the AuthProxy documentation. AuthProxy is a comprehensive security gateway that provides authentication, authorization, reverse proxy functionality, and web server capabilities for the ItBuild ecosystem.

What is AuthProxy?​

AuthProxy serves as the central security gateway for ItBuild applications, providing:

  • Multi-Factor Authentication: FIDO2/WebAuthn, passwords, and social login
  • Reverse Proxy: Secure routing to internal microservices
  • Web Server: PWA hosting and static file serving
  • Session Management: Secure, scalable session handling
  • Admin Interface: Comprehensive administrative tools

Part of ItBuild Platform​

AuthProxy is a core component of the ItBuild Platform - a comprehensive system for building and deploying multi-tenant business applications.

Platform Benefits​

For Platform Operators (ItBuild team):

  • Multi-tenant infrastructure - one codebase, many customers
  • License-based deployment - each build tied to customer domain
  • Automated provisioning - DNS verification, database setup, deployment
  • Centralized monitoring - Uptrace, Grafana, Zabbix

For Customers:

  • Standard modules (AuthProxy, TrexWallet, Chat) - maintained by ItBuild
  • Custom core module - your business logic, you control development
  • DEV environment - hosted on dev.itbuild.app:port
  • PROD deployment - on your infrastructure or with our help

Multi-Tenant Architecture​

Each customer project has:

  • Unique domain (e.g., app.customer.com)
  • Domain-bound modules (each build tied to your verified domain)
  • Separate databases per module (project123_authproxy, project123_wallet, etc.)
  • Isolated deployment (dedicated or shared VM, unique port for DEV)

Example: Customer "Acme Corp" gets:

  • Domain: app.acme.com
  • DEV: https://dev.itbuild.app:<assigned-customer-port> (customer ports run from 8001-8999; the platform team's own dev stand at :8081 is not used for customer testing)
  • ProjectID: 17234567890001 (TimeTick)
  • Databases: project<port>_authproxy, project<port>_wallet, project<port>_core

Domain-Bound Security​

Every AuthProxy deployment is bound to a specific domain. Modules validate the domain on startup - if the request domain doesn't match the licensed domain, authentication fails. This prevents unauthorized deployment.

Two Frontend Systems​

1. PWA Applications (Separate repositories):

  • AuthProxy PWA (Preact, < 200KB) - in /apg.pwa
  • Other Modules PWA (React, < 500KB) - in /trexwallet.pwa, /chat.pwa, etc.
  • Built separately, copied to wwwroot/

2. Admin Pages (Razor Pages):

  • Server-rendered C# pages in /Pages/ProxyAdmin/
  • jQuery + DataTables (minimal frontend)
  • This is backend work, not frontend development

Learn more in PWA Hosting and Platform Overview.

Key Features​

🔐 Authentication Methods

The LoginMethod flags enum (ItBuild.Shared.AuthProxy) defines every distinct login type the platform supports. The exact set enabled on a given AuthProxy deployment is reported by GET /auth/v1/get_info (loginMethods bitmask).

CategoryMethods (LoginMethod flag values)
Hardware / software keysPassKey (1), Fido2Key (2), UserKey (4) — Ed25519 challenge-response or FIDO2/WebAuthn
Cross-app sessionAppLogin (8) — bound to an approved user_app
OTP / magic linkPhone (32) SMS, Email (64) — same flag covers OTP code and magic-link email login
OAuth ProvidersTelegram (16), Google (128), Discord (256), Github (512), Vk (1024), Apple (16384), Facebook (32768)
MCP (programmatic)McpBasic (2048), McpVerified (4096), McpApp (8192) — see MCP Access Model
CardDAVCardDav (131072) — CardDAV-key authentication for /dav
Federation v2AuthProxy (1 << 30) — browser login through a verified partner ItBuild project

Browser login flows use challenge-response with Ed25519 signatures for the strongest paths; OAuth and OTP keep their native protocols. MCP is programmatic only and is not a browser session — see MCP Access Model.

🌐 Gateway Functionality

  • Reverse proxy with dynamic routing
  • Rate limiting and abuse prevention
  • CORS policy management
  • SSL termination

⚡ Horizontal Scaling

DNS Round Robin → p1, p2, p3 subdomains
Frontend probes all → selects fastest
Session locality → no sync overhead
  • Memory-cached static file serving
  • No shared state required (each instance independent)
  • User "sticks" to nearest proxy

🛡️ Security & Audit

  • Rate limiting: Per IP, session, and public key (separate limits)
  • Audit logging (login_log): IP, geolocation, device GUID, screen resolution, timezone, browser language
  • CSP configuration: connect, script, style, frame, font sources
  • IP whitelist/blacklist

Quick Navigation​

Getting Started​

Core Concepts​

Administration​

System Requirements​

  • .NET 10 runtime environment
  • SQL Server 2019+ or Azure SQL Database
  • HTTPS with valid SSL certificates
  • See System Requirements for detailed specifications

Support and Community​

  • Documentation: This comprehensive guide
  • API Reference: Interactive OpenAPI documentation
  • GitHub: Source code and issue tracking
  • Community: Developer forums and discussions

Architecture Overview​

Next Steps​

  1. Install AuthProxy in your environment
  2. Configure basic settings for your domain
  3. Set up authentication methods
  4. Configure applications and routing
  5. Review security settings and best practices

Ready to get started? Begin with the Installation Guide.