User Rules & Authentication Logic

Back to Home

This document outlines the specific rules and scenarios handled by the authentication system, particularly focusing on the interaction between Magic Link login, OTP login, and Two-Factor Authentication (2FA).

Definitions

Before reviewing the scenarios, please understand the two key settings that control the flow:

1. Client 2FA Enforcement (Organization Level)

Controlled by: The Organization Admin.
Setting: enforce_2fa (Boolean).
Meaning:
- Enforced (ON): The organization mandates that ALL users must use Two-Factor Authentication. User preference is ignored; security is prioritized.
- Flexible (OFF): The organization allows users to decide whether they want to use 2FA or not.

2. User 2FA Preference (User Level)

Controlled by: The Individual User (via Profile).
Setting: enable_2fa (Boolean).
Meaning:
- Enabled (ON): The user has explicitly opted to secure their account with 2FA.
- Disabled (OFF): The user has not set up 2FA or has disabled it.

Authentication Scenarios & Logic

The following table describes how the system behaves based on the combination of these two settings and the chosen login method.

Client 2FA Enforcement	User 2FA Preference	Login Method	Expected Outcome	Logic Description
Enforced (ON)	Enabled (ON)	Magic Link	2FA Challenge	Client enforcement is strict. Even though Magic Link is secure, the system demands the second factor (OTP) because the client requires it.
Enforced (ON)	Disabled (OFF)	Magic Link	2FA Challenge	Client enforcement requires 2FA for all users. The user will be prompted to set up 2FA if not configured, or challenged if configured.
Enforced (ON)	Enabled (ON)	Password	2FA Challenge	Standard flow. Password verified -> 2FA required.
Enforced (ON)	Disabled (OFF)	Password	2FA Challenge	Standard flow. Password verified -> 2FA required (or setup).
Flexible (OFF)	Enabled (ON)	Magic Link	Login Success (Bypasses 2FA)	Magic Link is a secure possession factor. If client is flexible, we trust the user's choice to use it.
Flexible (OFF)	Disabled (OFF)	Magic Link	Login Success	Single factor (Magic Link) is sufficient.
Flexible (OFF)	Enabled (ON)	Password	2FA Challenge	User entered password, but has 2FA enabled. We must challenge for 2FA to ensure security.
Flexible (OFF)	Disabled (OFF)	Password	Login Success	Standard password-only login.
Enforced (ON)	Enabled (ON)	OTP Login	Blocked	Security Restriction: If 2FA is enabled, the user must use Password + 2FA. OTP-only login is disabled to prevent bypassing the knowledge factor (password).
Enforced (ON)	Disabled (OFF)	OTP Login	Login Success	(Loophole/Fallback): Since the user has not set up 2FA yet, they are allowed to login via OTP (Possession). Note: Ideally, enforced clients should disable OTP-only login or force 2FA setup immediately.
Flexible (OFF)	Enabled (ON)	OTP Login	Blocked	Security Restriction: If 2FA is enabled, the user must use Password + 2FA. OTP-only login is disabled.
Flexible (OFF)	Disabled (OFF)	OTP Login	Login Success	Single-factor authentication via OTP (Possession). Allowed if 2FA is not active for the user.

Passwordless Enforcement

If a user enables "Disable Password Login" in their profile (only available if Magic Link is enabled):

Password Login: Blocked (Error: "Password login is disabled for your account. Please use Magic Link.")
Magic Link Login: Allowed (Subject to 2FA rules above).
OTP Login: Allowed (Subject to 2FA rules above).
- Note: If a user has 2FA Enabled, OTP login is blocked and they are instructed to use their password. If Password Login is also disabled, they must use Magic Link.

Implementation Details

1. Magic Link Flow

Request: User requests a Magic Link via the login page.
Generation: System generates a secure, time-limited token (magic_link_token) and emails a link.
Verification: User clicks the link. System validates token and expiry.
Decision Logic:
- If Client Enforces 2FA: Redirect to OTP entry page. User is not logged in yet.
- If Client is Flexible: Log the user in immediately, bypassing 2FA checks.

2. Password Flow

Request: User enters email and password.
Verification: System verifies the password hash.
Decision Logic:
- If Client Enforces 2FA: Trigger 2FA Challenge.
- If User has 2FA Enabled: Trigger 2FA Challenge.
- Otherwise: Login Success.

3. OTP Login Flow (Mobile/Email)

Request: User enters mobile number or email (without password).
Pre-Check:
- If User has 2FA Enabled: Request is rejected. User instructed to use password.
- If User has 2FA Disabled: System generates and sends OTP.
Verification: User enters OTP.
Login: If valid, user is logged in (Single Factor).