Implement Account Lockout Policies

Your login form works perfectly — until an attacker runs a script that throws thousands of password guesses at it per minute. Without an account lockout policy, every one of those guesses gets a fair shot, and statistically, weak passwords will fall. This lesson teaches you how to implement account lockout policies that stop brute-force attacks cold, locking accounts after a threshold of failed attempts and forcing attackers to move on.

The problem this lesson solves

Brute-force attacks are the bluntest instrument in a hacker's toolkit. An attacker takes a list of usernames and a dictionary of common passwords, then systematically tries every combination. They don't need sophistication — just time and volume. According to Verizon's Data Breach Investigations Report, credential attacks remain one of the top attack vectors year after year.

Consider a typical web application: a login endpoint that accepts a username and password. Without rate limiting or lockouts, an attacker can try thousands of guesses per minute. If any user has a weak password like password123 or Summer2024!, it's only a matter of time before the attacker hits it. The damage? Account takeover, data theft, and a severe breach of trust.

Account lockout policies address this directly: after a defined number of failed attempts, the account (or source IP) is temporarily or permanently locked. This throttles the attacker's throughput, making brute force impractical. It also gives security teams time to detect and respond.

The challenge is balancing security with usability. Lock out too aggressively, and you'll lock out legitimate users who mistyped their password a few times. Lock out too leniently, and attackers still have a viable window. This lesson teaches you how to find that balance and implement it correctly.

Core concept / mental model

Think of a lockout policy as a digital bouncer at a nightclub. The bouncer checks IDs, but if someone fails the ID check five times in a row, the bouncer escorts them out and refuses them entry for 15 minutes. A legitimate guest who left their ID at home might be annoyed, but they can come back later. An attacker with a stack of fake IDs is blocked after a few tries.

In technical terms, an account lockout policy consists of three core parameters:

• Threshold: The number of consecutive failed attempts allowed before lockout triggers (e.g., 5).
• Lockout duration: How long the account stays locked (e.g., 15 minutes).
• Lockout scope: Whether the lock applies to a username, an IP address, or both.

Here's the mental model:

Lockout = threshold + duration + scope

The policy sits between the login request and the credential verification. Every failed attempt increments a counter. When the counter hits the threshold, the account enters a locked state. Subsequent login attempts — even with correct credentials — are rejected until the duration elapses.

This works because it changes the economics of attack. An attacker needs N guesses to crack a password. With lockout, they get only threshold guesses per duration window, so the time to a successful guess grows from minutes to years.

Two common triggers for lockout:

• Failed login attempts: The classic counter. Each wrong password increments the counter.
• Suspicious behavior: Like multiple attempts from different IPs for the same account, or attempts on many accounts from one IP — this is a distributed brute-force pattern.

Key definitions

• Account lockout: A security control that disables an account after repeated failed authentication attempts.
• Threshold: The number of failed attempts allowed before lockout.
• Lockout duration: The time period during which the account remains locked.
• Brute-force attack: An attack that tries many passwords systematically.
• Credential stuffing: Using stolen username/password pairs from one breach to try on other services.

How it works step by step

Implementing an account lockout policy follows a logical sequence. Here's the step-by-step flow, from login request to lockout trigger.

1. Receive login attempt — The application receives a username and password.
2. Check lockout status — Before verifying credentials, check if the account is currently locked. If locked, reject the request immediately (with a generic error message).
3. Verify credentials — If not locked, check the password against the stored hash.
4. On success — Reset the failed-attempt counter to zero and allow access.
5. On failure — Increment the failed-attempt counter. Store the count and the timestamp of the last failure.
6. Check threshold — If the counter exceeds the threshold, lock the account by setting a lockout timestamp (now + duration) and clearing the counter.
7. On lockout expiry — After the duration, the account is automatically unlocked, and the counter resets.

A simple implementation in Python

Here's a minimal in-memory implementation to illustrate the logic:

import time
from collections import defaultdict

class AccountLockout:
    def __init__(self, threshold=5, lockout_seconds=900):
        self.threshold = threshold
        self.lockout_seconds = lockout_seconds
        self.failed_attempts = defaultdict(int)
        self.lockout_until = {}

    def is_locked(self, username):
        lockout_time = self.lockout_until.get(username, 0)
        if lockout_time > time.time():
            return True
        # Clear expired lockout
        if lockout_time:
            del self.lockout_until[username]
            self.failed_attempts[username] = 0
        return False

    def record_failure(self, username):
        self.failed_attempts[username] += 1
        if self.failed_attempts[username] >= self.threshold:
            self.lockout_until[username] = time.time() + self.lockout_seconds
            self.failed_attempts[username] = 0
            return True  # lockout triggered
        return False

    def record_success(self, username):
        self.failed_attempts[username] = 0
        self.lockout_until.pop(username, None)

# Usage
lockout = AccountLockout(threshold=3, lockout_seconds=60)
user = "alice"
for i in range(4):
    locked = lockout.is_locked(user)
    if locked:
        print(f"Attempt {i+1}: Locked out")
        break
    success = False  # simulate wrong password
    if not success:
        triggered = lockout.record_failure(user)
        print(f"Attempt {i+1}: Failed. Triggered lockout: {triggered}")

Expected output:

Attempt 1: Failed. Triggered lockout: False
Attempt 2: Failed. Triggered lockout: False
Attempt 3: Failed. Triggered lockout: True
Attempt 4: Locked out

Hands-on walkthrough

Now let's implement a more realistic version using a database (SQLite) to persist lockout state across application restarts. This is what you'd do in a production system.

Setting up the database

Create a table to track failed attempts:

CREATE TABLE login_attempts (
    username TEXT PRIMARY KEY,
    failed_count INTEGER DEFAULT 0,
    last_failure_time TIMESTAMP,
    locked_until TIMESTAMP
);

Python implementation with SQLite

import sqlite3
import time
from datetime import datetime, timedelta

DB_NAME = 'app.db'

def get_db():
    conn = sqlite3.connect(DB_NAME)
    conn.row_factory = sqlite3.Row
    return conn

def init_db():
    with get_db() as conn:
        conn.execute('''CREATE TABLE IF NOT EXISTS login_attempts (
            username TEXT PRIMARY KEY,
            failed_count INTEGER DEFAULT 0,
            last_failure_time TIMESTAMP,
            locked_until TIMESTAMP
        )''')

def is_account_locked(username):
    with get_db() as conn:
        row = conn.execute('SELECT locked_until FROM login_attempts WHERE username = ?', (username,)).fetchone()
        if row and row['locked_until']:
            locked_until = datetime.fromisoformat(row['locked_until'])
            if locked_until > datetime.now():
                return True
            # Lock expired: reset
            conn.execute('UPDATE login_attempts SET locked_until = NULL, failed_count = 0 WHERE username = ?', (username,))
    return False

def record_failed_attempt(username):
    threshold = 5
    with get_db() as conn:
        row = conn.execute('SELECT failed_count FROM login_attempts WHERE username = ?', (username,)).fetchone()
        if row:
            new_count = row['failed_count'] + 1
        else:
            new_count = 1
            conn.execute('INSERT INTO login_attempts (username, failed_count, last_failure_time) VALUES (?, ?, ?)',
                         (username, new_count, datetime.now().isoformat()))
        if row:
            conn.execute('UPDATE login_attempts SET failed_count = ?, last_failure_time = ? WHERE username = ?',
                         (new_count, datetime.now().isoformat(), username))
        if new_count >= threshold:
            lock_until = (datetime.now() + timedelta(minutes=15)).isoformat()
            conn.execute('UPDATE login_attempts SET locked_until = ?, failed_count = 0 WHERE username = ?',
                         (lock_until, username))
            return True  # triggered
    return False

def reset_attempts(username):
    with get_db() as conn:
        conn.execute('DELETE FROM login_attempts WHERE username = ?', (username,))

# Example flow
init_db()
username = "bob"
for attempt in range(6):
    if is_account_locked(username):
        print(f"Attempt {attempt+1}: Account locked. Try later.")
        break
    # Simulate failed login
    triggered = record_failed_attempt(username)
    if triggered:
        print(f"Attempt {attempt+1}: Failed. Lockout triggered.")
    else:
        print(f"Attempt {attempt+1}: Failed. Attempts remaining: {5 - (attempt)}")
print("Check locked status:", is_account_locked(username))

Expected output (approximately):

Attempt 1: Failed. Attempts remaining: 4
Attempt 2: Failed. Attempts remaining: 3
Attempt 3: Failed. Attempts remaining: 2
Attempt 4: Failed. Attempts remaining: 1
Attempt 5: Failed. Lockout triggered.
Attempt 6: Account locked. Try later.
Check locked status: True

What this demonstrates

• Persistence across restarts
• Timestamp-based expiration
• Resetting counters on success
• Realistic threshold/duration configuration

Compare options / when to choose what

There's more than one way to implement account lockout. Here's a comparison of common approaches.

When to choose what

• Account-level lockout is the baseline. Use it when you have user accounts and want to prevent password guessing on a specific username.
• IP-based lockout is a good addition, especially for protecting admin endpoints or API keys.
• Progressive delays (e.g., 1s, 5s, 15s after each failure) reduce attack speed without a hard lockout, preserving user experience.
• CAPTCHA is a compromise: after 3 failures, show a CAPTCHA instead of locking the account.

For most applications, a combination of account-level lockout (e.g., 5 attempts, 15-minute lockout) plus IP-level rate limiting (e.g., 100 attempts per minute per IP) is a solid start.

Troubleshooting & edge cases

Even well-intentioned lockout implementations can misfire. Here are common pitfalls and fixes.

1. Locking out legitimate users

Symptom: Users get locked out after a single typo. Cause: Threshold too low or shared IPs (e.g., NAT). Fix: Set a reasonable threshold (5–10) and combine with progressive delays instead of hard lockout.

2. Attackers bypass by spreading attempts across accounts

Symptom: One account never hits the threshold, but many accounts get one attempt each. Cause: Only account-level lockout implemented. Fix: Add IP-based rate limiting or detect distributed brute-force patterns (e.g., many failures on different usernames from same IP).

3. Lockout state lost on server restart

Symptom: Lockout doesn't persist across redeploys. Cause: Storing lockout state in memory only. Fix: Use a database or Redis for persistent state.

4. Timing attacks from lockout messages

Symptom: Attackers can distinguish "wrong password" from "account locked". Cause: Different error messages. Fix: Return the same generic message, like "Invalid credentials or account locked."

5. Race conditions in the counter

Symptom: Multiple concurrent requests inflate the counter incorrectly. Cause: Non-atomic updates. Fix: Use atomic SQL operations (UPDATE ... SET failed_count = failed_count + 1) or a transaction.

6. Lockout never resets on success

Symptom: Users who later log in correctly remain locked out. Cause: Forgot to reset counter on successful login. Fix: Always reset failed attempts and lockout status upon successful authentication.

What you learned & what's next

You now understand how to implement account lockout policies — from the problem they solve (brute-force defense) to the core concepts (threshold, duration, scope) and the step-by-step implementation. You've seen a hands-on example with SQLite persistence and compared options like account-level vs. IP-based lockout. You also learned troubleshooting techniques for common edge cases.

Key takeaways: - Account lockout policies throttle brute-force attacks by limiting the number of failed attempts. - Choose the right parameters (threshold, duration, scope) to balance security and usability. - Persist lockout state in a database or Redis, not just memory. - Reset the failure counter on successful login. - Use generic error messages to avoid leaking account status.

Next lesson: In the next part of the Secure development track, you'll explore rate limiting for APIs — a complementary technique that prevents abuse across all endpoints, not just login. This will build on your understanding of throttling attacks. You'll learn to use libraries like Flask-Limiter or Django Ratelimit to apply rate limits globally.

Keep practicing: try modifying the threshold and duration in the hands-on example, and test with a fake login flow. The better you understand lockout policies, the more robust your applications will be against credential brute force.