feat(M2-9998): add multi-factor authentication (MFA) login support #2181

maxto024 · 2025-12-11T06:47:07Z

PR Description - MFA Implementation

🎯 Summary

Implements Multi-Factor Authentication (MFA) for enhanced login security in MindLogger Admin. Users with MFA enabled must provide a 6-digit TOTP code or recovery code after entering their credentials.

Jira Main

Jira Ticket: M2-9998

Sub Tasks Fixed:

Jira Ticket: M2-10194
- Commit: 8d43b3ba2c68fc728bb96150452d197b46723bea
- Fixed: MFA login flow implementation
Jira Ticket: M2-10195
- Commit: 42883a906e9462661696e908c40654e49df9229f
- Fixed: Recovery code flow implementation
Jira Ticket: M2-10196 ✨ NEW
- Commit: 18f00e75d1840e6a33cd469a3df713a53e00668b
- Fixed: Invalid TOTP code now shows inline error instead of redirecting to login
- Issue: After entering invalid 6-digit verification code, user was redirected to login page with no explanation
- Solution:
  - Shows inline "Invalid code" message with red border
  - Error clears when user edits input
  - No automatic redirects on error or session expiry
  - Added "Back to Login" link for manual navigation
  - Session persists to allow retries

🔧 Changes

Core Features

Conditional Login Flow: Automatically detects MFA requirement and shows appropriate UI
TOTP Verification: 6-digit code verification with auto-submit functionality
Recovery Codes: Backup authentication method with proper formatting (XXXXX-XXXXX)
Session Management: 5-minute MFA sessions with graceful expiry handling
Rate Limiting: Maximum 5 attempts with warning after 3 attempts
Error Handling: Inline error messages without redirects, proper internationalization

Technical Implementation

State Management: Separate Redux state for MFA verification (prevents interference with login state)
Custom Hook Pattern: useMFAVerification provides shared logic for both forms
Hybrid State: Local state for UI control, Redux for error display
API Integration: New endpoints for TOTP and recovery code verification
Form Validation: Yup schemas with real-time validation
Auto-submit: Automatic form submission when 6 digits entered
Session Persistence: MFA session preserved until explicit user action

Components Added

AuthFlow: Main authentication flow controller with session tracking
MFAForm: TOTP code entry form with inline error display
RecoveryCodeForm: Recovery code entry form with auto-formatting
useMFAVerification: Custom hook for verification logic
mfa.utils: Error mapping utilities for user-friendly messages

Bug Fixes (M2-10196)

✅ Invalid verification codes show inline errors (no redirect)
✅ Expired verification codes show "Session expired" error (no redirect)
✅ Already used codes show appropriate error (no redirect)
✅ Offline errors handled gracefully (no redirect)
✅ Errors clear when user edits input
✅ After 5 attempts, user can manually go back to login

Video

https://www.loom.com/share/d2bb4f21fdfe46b38b76baaf6c766d46

Screenshots

MFA Flow

|||||

✅ Testing

Unit tests for all components
Custom hook tests (useMFAVerification.test.tsx)
Redux thunk tests for API interactions
Form validation and error display tests
Session expiry and cleanup tests
All tests passing (24 tests, 13 skipped for future enhancements)

🔐 Security Considerations

MFA tokens stored securely in Redux (not localStorage)
Session expires after 5 minutes with graceful handling
Rate limiting prevents brute force attacks (5 attempts max)
No sensitive data logged to console
Proper cleanup on unmount

🌐 Internationalization

Added translations for:

English (app-en.json)
French (app-fr.json)

Key translations:

Error messages: invalidCode, mfaSessionExpired, tooManyAttempts
UI text: confirmYourIdentity, enterVerificationCode, backToLogin

📚 Documentation

docs/MFA_IMPLEMENTATION.md - Complete implementation details
docs/MFA_TEST_SCENARIOS.md - Manual testing guide

🚀 How to Test

Login with MFA-enabled user (e.g., geria.test+mfa08@gmail.com)
Test invalid code → see inline error (no redirect)
Test session expiry (wait 5 min) → see expiry error (no redirect)
Test recovery code with wrong format → see format error
Test "Back to Login" link → returns to login form
Test successful verification → navigates to library

⚡ Performance

Minimal bundle size increase (~15KB gzipped)
No additional API calls unless MFA is enabled
Efficient Redux state updates
Debounced auto-submit to prevent excessive API calls
Local state for UI prevents re-render cascades

🔄 Backwards Compatibility

Non-breaking change
Users without MFA continue to login normally
Existing auth tokens remain valid
Legacy error handling preserved

📝 Checklist

- Add TOTP and recovery code verification flows - Implement MFA session management with 5 minute expiry - Add rate limiting with 5 attempt maximum - Create reusable MFA form components with auto-submit - Add comprehensive error handling and user feedback - Include English and French translations - Add unit tests for all MFA components

aws-amplify-us-east-1 · 2025-12-11T06:51:49Z

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2181.d2ccder08v9rmu.amplifyapp.com

…onents

… expired session

- Create MFA-specific styled components separate from login styles - Fix container dimensions (473px width) and centering - Remove input masks and fix cursor positioning - Update all text to match design requirements - Remove link underlines and reposition Back button - Update tests to match new UI text

…he MFA flow

- Move error formatting logic from component to Redux state to persist through re-renders - Add displayError field to MFAVerificationState for pre-formatted error messages - Fix race condition when clearing input after failed verification attempts - Handle "MFA session not found or expired" error for recovery codes - Show attempt count after 3 failed TOTP attempts (e.g., "2 attempts remaining") - Update tests to match new error handling approach - Update MFA implementation documentation

…tion validation, attempt warnings, and session-expiry errors

…account settings)

…how Back to Log In on recovery

divbzero

Overall looks good! Follows our general MFA design as well as OWASP recommendations.

Please see comments for a few requested changes around:

Deduping hasValidResult and formatRecoveryCode functions
Reusing components when possible instead of defining new styled components
Removing custom letter-spacing on recovery code <input> for consistency
Removing console.log debug statement

src/modules/Auth/features/Login/MFAForm/MFAForm.tsx

src/modules/Auth/state/Auth.thunk.ts

src/modules/Auth/features/Login/MFAForm/MFAForm.tsx

src/modules/Auth/features/Login/MFAForm/RecoveryCodeForm.tsx

src/modules/Auth/features/Login/MFAForm/MFAForm.styles.ts

src/modules/Auth/features/Login/MFAForm/MFAForm.tsx

src/modules/Auth/features/Login/MFAForm/RecoveryCodeForm.tsx

src/modules/Auth/state/Auth.reducer.ts

divbzero

Looks good!

maxto024 · 2026-01-05T17:48:18Z

Looks good!

Thank you so much, going to merge now.

fix(M2-9988): resolve TypeScript errors and test failures in MFA comp…

6be9131

…onents

maxto024 marked this pull request as ready for review December 12, 2025 15:54

maxto024 requested review from divbzero and sricharan-varanasi December 12, 2025 15:55

fix(M2-988): fix entering code MFA Form

f74bc6c

maxto024 closed this Dec 16, 2025

maxto024 reopened this Dec 16, 2025

maxto024 added 3 commits December 17, 2025 09:10

fix(M2-10194): resolve blank page issue when switching MFA forms with…

8d43b3b

… expired session

fix(M2-101994): fix linting useMFASessionExpiry.ts

e93f300

jodybrookover closed this Dec 17, 2025

jodybrookover reopened this Dec 17, 2025

maxto024 added 7 commits December 17, 2025 16:58

fix(M2-10196): keep MFA errors inline, stop redirects, and document t…

18f00e7

…he MFA flow

fix(M2-10196):fix linting

3bf59ed

fix(M2-10221): added back the back button in MFA Form

8fa81d2

fix(M2-10197,M2-10198,M2-10199,M2-10221): align MFA recovery/verifica…

d247c06

…tion validation, attempt warnings, and session-expiry errors

fix(M2-10199): sanitize MFA verification input to digits-only (match …

d1efb86

…account settings)

fix(M2-10238): make MFA session-expired sticky, disable inputs, and s…

3f595ad

…how Back to Log In on recovery

divbzero self-assigned this Dec 24, 2025

fix(M2-10238): fix test

e0e4f58

maxto024 requested review from sricharan-varanasi and removed request for sricharan-varanasi December 29, 2025 22:23

maxto024 added 2 commits December 30, 2025 07:21

fix(M2-10264): when session expire placeholder should be empty

64d97bd

fix(M2-10265): Fixed UI Position of i cant access code button

785916c

divbzero requested changes Dec 30, 2025

View reviewed changes

divbzero removed their assignment Dec 31, 2025

divbzero self-requested a review December 31, 2025 16:11

fix: All comments and failed test

27b7870

divbzero approved these changes Jan 5, 2026

View reviewed changes

maxto024 merged commit e1368ef into develop Jan 5, 2026
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(M2-9998): add multi-factor authentication (MFA) login support #2181

feat(M2-9998): add multi-factor authentication (MFA) login support #2181

Uh oh!

maxto024 commented Dec 11, 2025 •

edited

Loading

Uh oh!

aws-amplify-us-east-1 bot commented Dec 11, 2025

Uh oh!

divbzero left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

divbzero left a comment

Uh oh!

maxto024 commented Jan 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

feat(M2-9998): add multi-factor authentication (MFA) login support #2181

feat(M2-9998): add multi-factor authentication (MFA) login support #2181

Uh oh!

Conversation

maxto024 commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Description - MFA Implementation

🎯 Summary

Jira Main

Sub Tasks Fixed:

🔧 Changes

Core Features

Technical Implementation

Components Added

Bug Fixes (M2-10196)

Video

Screenshots

MFA Flow

✅ Testing

🔐 Security Considerations

🌐 Internationalization

📚 Documentation

🚀 How to Test

⚡ Performance

🔄 Backwards Compatibility

📝 Checklist

Uh oh!

aws-amplify-us-east-1 bot commented Dec 11, 2025

Uh oh!

divbzero left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

divbzero left a comment

Choose a reason for hiding this comment

Uh oh!

maxto024 commented Jan 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

maxto024 commented Dec 11, 2025 •

edited

Loading