Skip to content

ADR 012: Multi-Factor Authentication (MFA)

Status: Deferred Type: Feature Created: 2024-07-17 Related-ADRs: 010, 011, 014

Context and Goals

Hop3's authentication model issues JWT tokens after password login (or magic link), protected by bcrypt password hashing and per-IP rate limiting on /auth/login and /auth/magic/{token}. Server-side RPC access is gated by the operator's SSH key on the host, which provides an SSH-backed second factor for operators following the intended deployment pattern (CLI → SSH tunnel → RPC).

Multi-Factor Authentication (MFA) further hardens user accounts against unauthorized access by requiring two or more verification factors, reducing the risk of compromised credentials. This decision specifies the MFA design so it can be adopted directly when MFA becomes a requirement.

Decision

Hop3 secures user accounts with Multi-Factor Authentication (MFA). TOTP (via pyotp or equivalent) is the first mechanism: it requires no hardware, integrates cleanly with the existing JWT flow (TOTP verification gates token issuance), and has a well-understood operator UX. Hardware tokens (U2F / FIDO2) and biometric verification are later options layered on once TOTP is in place.

Key Components

MFA Implementation

  1. One-Time Passwords (OTP):

  2. Time-based OTP (TOTP): Integrate TOTP as a second factor, generated via authenticator apps. TOTP gates JWT issuance in the existing login flow.

  3. Hardware Tokens:

  4. U2F and FIDO2: Support Universal 2nd Factor (U2F) and FIDO2 hardware tokens for strong, phishing-resistant authentication.

  5. Biometric Verification:

  6. Biometric Authentication: Integrate biometric verification methods, such as fingerprint or facial recognition, for platforms that support these features.

User Experience

  1. User Enrollment:

  2. MFA Enrollment Process: Implement a seamless enrollment process for users to set up MFA on their accounts.

  3. Backup Codes: Provide backup codes for users to access their accounts in case their primary MFA method is unavailable.

  4. Flexibility:

  5. Multiple MFA Options: Offer multiple MFA options to cater to different user preferences and capabilities.

  6. MFA Management: Allow users to manage their MFA settings and preferences from their account settings.

Consequences

Benefits

  • Enhanced Security: Provides an additional layer of security to protect user accounts from unauthorized access.
  • User Confidence: Increases user confidence in the platform's security measures.
  • Compliance: Helps meet regulatory requirements for strong authentication mechanisms.

Drawbacks

  • User Convenience: May introduce inconvenience for users who prefer simpler login processes.
  • Implementation Complexity: Integrating and managing multiple MFA methods can be complex.

Risks

  • Adoption Resistance: Some users may resist adopting MFA due to perceived inconvenience. Mitigation involves providing clear instructions and support.
  • Technical Issues: Potential technical issues with MFA implementation. Mitigation includes thorough testing and support.

Alternatives Considered

  • SMS OTP: Delivering one-time passwords over SMS is an explicit non-goal. SIM-swapping and telecom-compromise risks make it unsuitable as a second factor for administrator accounts, so it is rejected despite the added flexibility it would offer to some users.

Related ADRs: ADR 010: Security and Resilience (Umbrella), ADR 011: Data Encryption and Protection, ADR 014: Authentication Bootstrap Process