Skip to content

ACCOUNT_LOCKOUT_IMPLEMENTATION.md

Latest commit

 

History

History
164 lines (127 loc) · 4.81 KB

ACCOUNT_LOCKOUT_IMPLEMENTATION.md

File metadata and controls

164 lines (127 loc) · 4.81 KB
Raw

Account Lockout Implementation

Overview

This document describes the account lockout mechanism implemented to address the security vulnerability where accounts were not being locked after failed login attempts.

Features Implemented

1. Database Schema Updates

  • Added failed_login_attempts column to track consecutive failed attempts
  • Added last_failed_login column to timestamp the last failed attempt
  • Added locked_until column to store when the lockout expires

2. Account Lockout Logic

  • Threshold: Account locks after 5 consecutive failed login attempts
  • Lock Duration: 30 minutes by default (configurable)
  • Automatic Reset: Failed attempts reset to 0 on successful login
  • Expiration: Lockouts automatically expire after the duration

3. Security Features

  • Rate Limiting: Existing IP-based rate limiting maintained
  • Account Locking: User-specific lockout mechanism
  • Information Disclosure Prevention: Generic error messages for invalid credentials
  • Automatic Cleanup: Expired lockouts are automatically reset

API Endpoints

POST /api/users/login

Enhanced with account lockout checking:

  • Returns 423 (Locked) status if account is locked
  • Includes lockedUntil timestamp in response
  • Tracks failed attempts and locks account after threshold

GET /api/users/lockout-status?username={username}

New endpoint to check account lockout status:

  • Returns lockout status, failed attempts count, and lock expiration
  • Useful for admin monitoring and user feedback

Middleware

checkAccountLockout

Applied to protected routes:

  • /api/auctions (POST) - Auction creation
  • /api/auctions/:id/bid (POST) - Bid placement
  • Prevents locked users from performing actions

Database Methods

New Methods Added

  • incrementFailedLoginAttempts(username) - Increments failed attempt counter
  • lockAccount(username, duration) - Locks account for specified duration
  • resetFailedLoginAttempts(username) - Resets failed attempts and unlocks
  • isAccountLocked(username) - Checks if account is currently locked
  • resetExpiredLockouts() - Mass reset of expired lockouts

Automatic Processes

Lockout Cleanup

  • Runs every 5 minutes
  • Automatically resets expired lockouts
  • Logs cleanup activity

Integration with Existing Security

  • Works alongside existing rate limiting
  • Maintains JWT token security
  • Preserves existing validation middleware

Configuration

Constants

const MAX_FAILED_ATTEMPTS = 5;  // Lock after 5 failed attempts
const LOCK_DURATION_MINUTES = 30;  // Lock for 30 minutes

These can be easily modified based on security requirements.

Testing

Test Script

Run the test script to verify the implementation:

node test-account-lockout.js

The test covers:

  • User registration
  • Failed login attempts tracking
  • Account locking after threshold
  • Lockout status checking
  • Prevention of login while locked

Security Considerations

Brute Force Protection

  • Account-specific lockout prevents targeted attacks
  • IP-based rate limiting provides additional protection
  • Failed attempts are logged for security monitoring

User Experience

  • Clear error messages inform users about lockout status
  • Automatic unlock prevents permanent lockout
  • Successful login resets failed attempt counter

Monitoring

  • Security warnings logged when accounts are locked
  • Lockout status endpoint enables admin monitoring
  • Failed login attempts tracked for security analysis

Implementation Files

Modified Files

  • server.js - Enhanced login endpoint, added middleware and endpoints
  • database.js - Updated schema and added lockout methods

New Files

  • test-account-lockout.js - Comprehensive test suite
  • ACCOUNT_LOCKOUT_IMPLEMENTATION.md - This documentation

Usage Examples

Checking Account Lockout Status

curl "http://localhost:3001/api/users/lockout-status?username=testuser"

Response When Locked

{
  "username": "testuser",
  "isLocked": true,
  "failedLoginAttempts": 5,
  "lastFailedLogin": "2024-03-28T12:00:00.000Z",
  "lockedUntil": "2024-03-28T12:30:00.000Z"
}

Response When Not Locked

{
  "username": "testuser",
  "isLocked": false,
  "failedLoginAttempts": 0,
  "lastFailedLogin": null,
  "lockedUntil": null
}

Future Enhancements

Potential Improvements

  • Configurable lockout thresholds per user role
  • Email notifications for account lockouts
  • Admin override capabilities
  • Progressive lockout durations
  • Geographic-based lockout policies

Monitoring Dashboard

  • Real-time lockout monitoring
  • Failed login attempt analytics
  • Security event logging
  • Automated alerting for suspicious activity

This implementation provides a robust account lockout mechanism that significantly improves the security posture of the application while maintaining a good user experience.