Authentication

Flo supports three authentication flows. All result in a cookie-based session (FloAuth, HttpOnly, Secure, SameSite=Lax).

Auth Flows

1. Password-Based Login

Traditional email/password authentication with brute force protection.

• Lockout: 5 failed attempts triggers a 15-minute lockout
• Password hashing: BCrypt
• Session: Cookie set on successful login

Flow:

User → POST /api/v1/auth/login { email, password }
     → Server validates credentials
     → Server checks lockout counter
     → Cookie set → Redirect to dashboard

2. OTP Email Login

Passwordless login via a 6-digit code sent by email.

• Code length: 6 digits
• Expiry: 10 minutes
• Max attempts: 3 per code
• Cooldown: 30 seconds between OTP requests (per email)

Flow:

User → POST /api/public/v1/otp/request { email }
     → Server generates 6-digit code
     → Email sent with code
     → User enters code
     → POST /api/public/v1/otp/verify { email, code }
     → Cookie set → Redirect to dashboard

3. OIDC/OAuth2 (OpenIddict)

Full OAuth2 server for external clients (e.g., blog CMS, third-party apps).

• Grant type: Authorization Code with PKCE
• Refresh tokens: Supported
• Scopes: openid, profile, email, roles
• Certificate-based: Signing and encryption certs configured per tenant

Flow:

Client → GET /connect/authorize (with PKCE challenge)
       → User authenticates (password or OTP)
       → Authorization code returned
       → POST /connect/token (exchange code for tokens)
       → Access token + Refresh token

Session Management

All auth flows result in the same cookie:

Property	Value
Name	FloAuth
HttpOnly	true
Secure	true
SameSite	Lax
Domain	Configurable via COOKIE_DOMAIN env var

The frontend restores the session on startup via APP_INITIALIZER — it calls GET /api/v1/users/me to check if the cookie is still valid.

Claims

Different auth methods use different claim types for the user ID:

Auth Method	Claim Type
Cookie (password)	ClaimTypes.NameIdentifier
OTP / OpenIddict	Claims.Subject

Backend services handle both claim types when resolving the current user.

Key Files

File	Purpose
Flo.BE/Services/AuthService.cs	Password login with brute force protection
Flo.BE/Services/OtpAuthService.cs	OTP code generation and verification
Flo.BE/Controllers/OAuthController.cs	OIDC authorization and token endpoints
Flo.FE/src/app/guards/auth.guard.ts	Frontend route protection
Flo.FE/src/app/services/global.store.ts	Session restore on app init