Secure Authentication System with AWS Cognito MFA

A full-stack web application implementing secure authentication using AWS Cognito with Time-based One-Time Password (TOTP) multi-factor authentication.

Features

• AWS Cognito Authentication: Secure user authentication with your existing Cognito user pool
• TOTP-based MFA: Multi-factor authentication using Google Authenticator or similar apps
• QR Code Setup: Easy MFA setup by scanning QR codes
• Modern UI: Clean, responsive interface built with React and Tailwind CSS
• Session Management: Secure session handling with automatic cleanup

Prerequisites

Before running this application locally, make sure you have:

1. Node.js (version 18 or higher)

   • Download from nodejs.org
   • Verify installation: node --version

2. Git (for cloning the repository)

   • Download from git-scm.com

3. AWS Cognito User Pool (already configured)

   • User Pool ID: us-east-1_x06JPtf0r
   • Client ID: 63r5ue04ggrk1g0tvic031njh
   • Region: us-east-1

Step-by-Step Setup

1. Clone or Download the Project

If you have the project files, skip to step 2. Otherwise:

# Clone the repository (if using Git)
git clone <repository-url>
cd secure-auth-app

# OR download and extract the project files to a folder

2. Open Terminal/Command Prompt

• Windows: Press Win + R, type cmd, press Enter
• Mac: Press Cmd + Space, type terminal, press Enter
• Linux: Press Ctrl + Alt + T

3. Navigate to Project Directory

# Change to your project directory
cd path/to/your/project

# Example:
# cd C:\Users\YourName\Downloads\secure-auth-app
# cd /Users/YourName/Downloads/secure-auth-app
# cd ~/Downloads/secure-auth-app

4. Install Dependencies

# Install all required packages
npm install

This will download and install all necessary dependencies. It may take a few minutes.

5. Set Up Environment Variables

The application uses these AWS Cognito settings (already configured):

• User Pool ID: us-east-1_x06JPtf0r
• Client ID: 63r5ue04ggrk1g0tvic031njh
• Region: us-east-1

These are hardcoded in the application, so no additional setup is needed.

6. Start the Application

# Start the development server
npm run dev

You should see output like:

> rest-express@1.0.0 dev
> NODE_ENV=development tsx server/index.ts
[timestamp] [express] serving on port 5000

7. Open in Browser

1. Open your web browser
2. Go to: http://localhost:5000
3. You should see the login page

How to Test the Application

For New Users (First Time MFA Setup):

1. Login: Enter your email and password
2. QR Code: If MFA setup is required, you'll see a QR code
3. Google Authenticator:
   • Download Google Authenticator from your app store
   • Open the app and tap "Scan QR code"
   • Scan the QR code displayed on screen
4. Enter Code: Type the 6-digit code from Google Authenticator
5. Success: You'll be redirected to the success page

For Existing Users (Already Have MFA):

1. Login: Enter your email and password
2. Enter Code: Type the 6-digit code from your Google Authenticator app
3. Success: You'll be redirected to the success page

Project Structure

secure-auth-app/
├── client/                 # Frontend React application
│   ├── src/
│   │   ├── components/     # UI components
│   │   ├── pages/          # Application pages
│   │   └── lib/           # Utilities and configurations
├── server/                 # Backend Express server
│   ├── index.ts           # Server entry point
│   ├── routes.ts          # API routes
│   └── storage.ts         # Session storage
├── shared/                 # Shared types and schemas
│   └── schema.ts          # Data validation schemas
└── package.json           # Dependencies and scripts

Available Commands

# Start development server
npm run dev

# Build for production
npm run build

# Start production server
npm start

Troubleshooting

Common Issues:

1. Port 5000 is busy:

   Error: listen EADDRINUSE: address already in use :::5000
   

   • Close other applications using port 5000
   • Or kill the process: npx kill-port 5000

2. Node.js not found:

   'node' is not recognized as an internal or external command
   

   • Install Node.js from nodejs.org
   • Restart your terminal after installation

3. Permission errors on Mac/Linux:

   EACCES: permission denied
   

   • Try: sudo npm install (use with caution)
   • Or fix npm permissions: npm docs

4. Login fails with "Invalid credentials":

   • Verify you're using a valid user from the AWS Cognito user pool
   • Check that the user is confirmed (not pending verification)

5. MFA code doesn't work:

   • Ensure your phone's time is synchronized
   • Try generating a new code (they change every 30 seconds)
   • Make sure you scanned the QR code correctly

Getting Help:

If you encounter issues:

1. Check the terminal/console for error messages
2. Verify all prerequisites are installed
3. Make sure port 5000 is available
4. Ensure you have a stable internet connection (for AWS Cognito)

Security Features

• SRP Authentication: Uses Secure Remote Password protocol
• Session Management: Secure session handling with automatic cleanup
• TOTP Verification: Time-based one-time passwords for MFA
• Input Validation: All inputs are validated and sanitized
• Error Handling: Comprehensive error handling and user feedback

Technology Stack

• Frontend: React 18, TypeScript, Tailwind CSS, Wouter (routing)
• Backend: Node.js, Express, TypeScript
• Authentication: AWS Amplify, AWS Cognito
• MFA: Speakeasy (TOTP), QRCode generation
• Build Tools: Vite, tsx

AWS Cognito Configuration

This application works with the pre-configured AWS Cognito user pool:

• Region: us-east-1
• User Pool ID: us-east-1_x06JPtf0r
• Client ID: 63r5ue04ggrk1g0tvic031njh

No additional AWS configuration is required to run the application locally.