AuthProxy

The authentication gateway, reverse proxy, and web server for all ItBuild projects. AuthProxy is the only module that faces the internet directly — all other modules are behind it.

Key Features

• 14 authentication methods — FIDO2/WebAuthn, Ed25519 keys, OAuth (Google, Apple, Microsoft, GitHub, Facebook, VK, Discord, Telegram), Phone/Email OTP, Magic Links.
• Federation v2 — Browser Login — manual provider picker (Form0) backed by /auth/v1/federated/{providers,start,return}; partners go live without a PWA rebuild.
• Reverse proxy — routes authenticated requests to backend modules with user context headers (X-Crm, X-Scopes, X-KeyType, X-AppId, X-Pkey-Crm, X-Country, X-Project). No X-User-Id header is forwarded — read identity from X-Crm.
• CORS app × route gating — cross-origin calls require AppFlag.AppAuthAndCORS on the calling user_app AND RouteFlags.AppAuthAndCORS on the matching route.
• PWA web server — serves frontend applications with in-memory caching and compression.
• File service — chunked uploads with CRC32 integrity verification; local disk or external HTTP backend.
• SSE real-time events (capability mode) — Server-Sent Events with subject-based scoping (/auth/v1/subscribe, /private/v1/events?subjects=).
• Web Push notifications — browser push subscriptions for background delivery.
• Webhooks — outbound HTTP notifications to registered applications.
• MCP protocol — JSON-RPC 2.0 interface for AI assistant integration with whitelist access model.
• Embedded STUN responder — UDP STUN on the same port as HTTPS for WebRTC NAT traversal without external dependency.
• Inbound email bridge — SMTP listener on port 25 turns inbound mail into chat messages (DKIM + SPF + strict From:-alignment).
• Admin panel — user management, route configuration, settings, audit logs, STUN monitor.
• Rate limiting — fixed-window protection per scope (connection, session, API key, bandwidth).

Customer Admin Note: Single-Proxy File Storage

For a single-proxy deployment, AuthProxy can store attachment bytes directly on local disk. Configure LocalFileStoragePath in the AuthProxy deployment config:

{
  "LocalFileStoragePath": "/var/lib/authproxy/files"
}

Important:

• This is a deploy-time setting in appsettings.json or environment variables.
• This is not configured in ProxyAdmin.
• This mode is the recommended setup for mono-proxy deployments.
• AuthProxy still uses the Chat module for file metadata and attachment lifecycle operations.

If you do not want local disk storage, AuthProxy can also use external HTTP storage backends. Full storage details are documented in the AuthProxy File Service page.

Customer Admin Note: Browser Push Notifications

AuthProxy supports two notification transports at the same time:

• SSE for live tabs and in-app refresh
• Web Push for browser notification center / tray delivery when the app is in the background

For customer admins this means Web Push is not “just a frontend switch”. The deployment must include:

1. WebPush configuration in AuthProxy (Enabled, VAPID public/private key pair, Subject).
2. PushSending enabled on exactly one AuthProxy node in phase 1 multi-proxy deployments.
3. One canonical root sw.js on the same origin as the customer PWA.
4. Frontend apps that call GET /auth/v1/notifications/public_key and POST /auth/v1/notifications/subscribe after notification permission is granted.
5. Operational diagnostics through /ProxyAdmin/PushSubscriptions when validating real subscriptions on a stand.

Important flat-merge rule:

• apg.pwa is the canonical owner of root sw.js
• chat.pwa and trexwallet.pwa may register /sw.js, but should not ship competing root worker files
• customer Core.pwa should not overwrite /sw.js unless the deployment intentionally replaces the platform worker contract

Recommended operational model:

• keep SSE enabled for all normal app sessions
• use Web Push as the background transport
• do not disable /auth/v1/subscribe after enabling Web Push, because active tabs still rely on SSE for live state updates and cursor-based recovery

Important operational caveats:

• POST /auth/v1/notifications/test and the Test action in /ProxyAdmin/PushSubscriptions validate the sender transport itself, not the full business-event pipeline.
• Real production push delivery still depends on module events reaching AuthProxy through GET /private/v1/events and being mapped by PushDispatcher.
• Web Push is best-effort background delivery. A fully terminated browser process may still prevent wakeup depending on browser/OS settings.

For the full operator-facing setup and troubleshooting guide, see Browser Push Notifications.

Documentation

Full documentation: docs.authproxy.tech

Section	Description
Getting Started	Installation, configuration, quick start
Authentication	Session management, FIDO2, OAuth, MFA
API Gateway	Reverse proxy, routing, file service
Security	Encryption, rate limiting, user scopes
Deployment	Docker, versioning, monitoring
API Reference	Complete endpoint documentation