Skip to main content

Session Management

AuthProxy implements a robust session management system that provides secure, scalable, and flexible user session handling across web applications and APIs.

Session Types​

AuthProxy categorises sessions by authentication method using the LoginMethod enum defined in ItBuild.Shared.AuthProxy. Values are powers of two and can be combined as a [Flags] enum on a user key (the key advertises which methods it can be used for); on a live session a single LoginMethod value is recorded.

Key-Based Authentication​

  • PassKey (1) — session derived from a password-protected key (legacy / dev environments).
  • Fido2Key (2) — session created using FIDO2 / WebAuthn hardware security key.
  • UserKey (4) — session created using an Ed25519 software passkey (challenge-response browser login).

Application Integration​

  • AppLogin (8) — cross-application login bound to a verified user_app, restricted API surface.
  • AuthProxy (1 << 30) — federation login through a verified partner ItBuild project; see Federation v2 — Browser Login.

Social Authentication​

  • Telegram (16) — Telegram Bot / Mini App authentication.
  • Google (128), Discord (256), Github (512), Vk (1024), Apple (16384), Facebook (32768) — reuse the same login-log machinery and are documented in OAuth Providers.

OTP Methods​

  • Phone (32) — OTP code sent to phone number (via Chat module SMS).
  • Email (64) — OTP code sent to email address (via Chat module). The same flag is used by magic-link email login.

Machine Access​

  • McpBasic (2048) — public key only (read-only access to a curated subset of platform tools, via mcp_login).
  • McpVerified (4096) — public key + signed timestamp (full personal access).
  • McpApp (8192) — delegated app access for AI agents, scoped to an approved user_app.
  • CardDav (131072) — CardDAV-key authentication for /dav (not a normal browser session).
MCP sessions are not browser sessions

MCP sessions do not produce the standard sid cookie and modules may refuse to perform side-effecting operations on them. See MCP Access Model for what each MCP login type is allowed to do and the threat model behind the split.

Session Type Storage​

The login event is recorded in the login_log table for audit purposes. Note that the active session carries the LoginMethod (bitmask, surfaced as X-KeyType), while the login_log.login_type column persists the sequential LoginType enum (e.g. 7 = Email). Audit tracking helps with:

  • Authentication method usage patterns
  • Security level of different sessions
  • Compliance and audit requirements
  • User behavior analytics

Each session type has different security implications and access levels within the AuthProxy system.

Session Type Propagation​

When AuthProxy forwards requests to internal ItBuild services through the reverse proxy, it includes the session type information in the request headers:

X-KeyType Header​

AuthProxy automatically adds the X-KeyType header to proxied requests, containing the numeric value of the LoginMethod enum that produced the active session:

X-KeyType: 1      // PassKey authentication
X-KeyType: 2      // Fido2Key authentication
X-KeyType: 4      // UserKey (Ed25519 challenge-response)
X-KeyType: 32     // Phone OTP
X-KeyType: 64     // Email OTP / magic link
X-KeyType: 128    // Google OAuth

The header is paired with X-Crm (CRM identifier of the authenticated user) and, for app-bound sessions, X-AppId. AuthProxy does not emit X-User-Id or X-UserId — read identity from X-Crm.

Internal Service Integration​

This header allows internal ItBuild services to:

  • Apply Different Security Policies: Services can enforce stricter rules for certain authentication types
  • Audit and Logging: Track which authentication methods are used for specific operations
  • Feature Access Control: Enable/disable features based on authentication strength
  • Compliance Requirements: Meet security standards that require stronger authentication for sensitive operations

Example Usage in Internal Services​

Internal services can read the authentication-strength header and require a stronger method for sensitive operations. For example, a payout, secret export, or admin-only mutation can require a hardware key or Ed25519 challenge-response session instead of a weaker browser login.

This enables a unified security model across all ItBuild modules while maintaining the flexibility to handle different authentication strengths appropriately.

Session Storage & Performance​

Sessions are stored in-memory using a lock-free ConcurrentDictionary<string, ApgSession>. Key characteristics:

  • O(1) lookup — session resolution by Bearer token or cookie is a single hash lookup
  • Lock-free reads — FindSessionById and FindSessionCookie require no locking
  • Write lock — only Add/Remove/Cleanup operations take a lightweight lock
  • Fixed-window rate limiting — per-session rate counter uses Interlocked atomic operations and a fixed time window. See Rate Limiting for the canonical scope/window semantics.
  • Sliding expiration — cookie expiry extended automatically on access (benign race, no lock needed)

Session Limits​

Configurable via Settings admin panel (SettingType 20-22):

SettingDefaultDescription
SessionMaxPerUser4Max active sessions per user (oldest evicted)
SessionMaxTotal10,000Max total sessions per instance
SessionCreationRate60Max new sessions per user per hour