Feature: Temporarily lock a local account after repeated incorrect password attempts

[branch1337]

Description

A wrong password on /login only costs one request against the existing per-IP limit of 10 per minute. That limit resets every minute, and without RATELIMIT_STORAGE_URI each gunicorn worker counts separately, so a patient client or several source addresses can try passwords against one account all day.

The operator cannot stop that without blocking the IP, and cannot see or clear a locked account from the user list. An account with a local password has no failed-attempt counter and no lock time.

Affected Version

v0.10.17-alpha

Requested Feature

After five wrong passwords on one local account, further password sign-ins for that account fail for 60 minutes, including a later correct password. Both numbers are integer system settings, login_max_failed_attempts (default 5) and login_lockout_minutes (default 60). Setting the attempt count to 0 turns this lock off. The login page keeps the flash loginFailed. It does not say that the account exists, that it is locked, or how long remains.

The per-IP limit of 10 requests per minute on /login stays as it is. SSO sign-in, forgot-password, reset-password, and change_password keep their current responses. A correct password before the fifth failure signs in as today and clears the counter. A correct password on an unverified account still shows the check-email page and also clears the counter, because the password was right.

While login_locked_until is in the future, the admin user list shows a small lock icon beside that username and the Edit User modal shows an Unlock button. Both are absent when the account is not locked, including when a few failures have not yet reached the maximum. The button sends the existing user update with only unlock_login: true. It does not submit the rest of the form. Saving a new password from that modal, or finishing the email reset, also clears the lock so the owner can sign in immediately.

Proposed Implementation

login() in src/api/auth.py:272-322 is the only unauthenticated password check. The new branch belongs inside if user and user.password at src/api/auth.py:288-313. Unknown email (src/api/auth.py:312-313), an account with no local password (src/api/auth.py:310-311), and password login disabled for a non-admin (src/api/auth.py:290-291) stay on their current flashes and do not write the counter. change_password at src/api/auth.py:1057-1115 already requires a session. SSO login_user at src/api/auth.py:427 does not check a local password. Leave both alone.

flowchart TD
  post[Valid login POST]
  lookup[Account with a local password]
  off[Attempts set to 0]
  hash[bcrypt]
  locked{locked_until in the future}
  ok{Hash matches}
  inc[SQL increment and commit]
  trip{Count reaches the maximum}
  setlock[Set locked_until and zero the count]
  clear[Zero the count and locked_until]
  session[Current path: email check or login_user]
  fail[Flash loginFailed]
  post --> lookup
  lookup --> off
  off -->|yes| session
  off -->|no| hash
  hash --> locked
  locked -->|yes| fail
  locked -->|no| ok
  ok -->|yes| clear --> session
  ok -->|no| inc --> trip
  trip -->|yes| setlock --> fail
  trip -->|no| fail

Loading

When the attempt setting is 0, session is the current branch at src/api/auth.py:290-307, which still checks the password. When the account is locked, the hash still runs so the response is not faster than a wrong password, and the result is then discarded.

Add clear_login_lock(user) in src/api/auth.py. It sets failed_login_count to 0 and login_locked_until to None. Call it from three places that already commit a password or a sign-in: a matching hash in login() before the email check at src/api/auth.py:294, reset_password where it assigns user.password at src/api/auth.py:652, and admin_update_user when it sets a password at src/api/admin.py:297-300 or when the JSON contains unlock_login: true.

On a mismatch, and only when the attempt setting is at least 1, increment in SQL so two workers cannot both read the same count:

def clear_login_lock(user):
    user.failed_login_count = 0
    user.login_locked_until = None


def record_failed_login(user, max_attempts, lock_minutes):
    db.session.query(User).filter_by(id=user.id).update(
        {User.failed_login_count: User.failed_login_count + 1},
        synchronize_session=False,
    )
    db.session.commit()
    db.session.refresh(user)
    if user.failed_login_count >= max_attempts:
        user.login_locked_until = datetime.utcnow() + timedelta(minutes=lock_minutes)
        user.failed_login_count = 0
        db.session.commit()
        current_app.logger.warning("Login locked for user id %s", user.id)

Read login_max_failed_attempts (default 5) and login_lockout_minutes (default 60) with SystemSetting.get_setting on that request. get_setting already returns an int for setting_type='integer' (src/models/system.py:45-47). A lock duration below 1 is treated as 60, so an empty value cannot lock the account forever. Further failures while login_locked_until is in the future do not add to the count and do not move the timestamp. When the timestamp is in the past, the next mismatch starts again from 1.

Columns on User, next to the password-reset fields at src/models/user.py:65-67:

failed_login_count = db.Column(db.Integer, nullable=False, default=0)
login_locked_until = db.Column(db.DateTime, nullable=True)

src/init_db.py:529 adds session_version with add_column_if_not_exists. Add failed_login_count as INTEGER DEFAULT 0 and login_locked_until as DATETIME in that same block. src/init_db.py:1008-1014 seeds max_file_size_mb only when the row is missing. Seed the two integer settings the same way, with descriptions that say 0 attempts disables the lock and that the duration is minutes. POST /admin/settings already rejects a non-integer (src/api/admin.py:917-920). The settings modal already renders input type=number for an integer with no per-key widget (templates/admin.html:1596-1599). Keys absent from settingOrder already sort to the end (templates/admin.html:2458-2460), so that array stays as it is.

admin_get_users builds each row at src/api/admin.py:171-188. Add login_locked, true only when login_locked_until is in the future. Do not add the raw count. admin_update_user at src/api/admin.py:266-277 already requires a site admin (403 otherwise), loads the user (404 otherwise), and applies only the keys present in the JSON. Handle unlock_login there. src/api/admin.py:341 only signs the admin back into their own session after they change their own password. It is not a password guess, so it does not record a failure.

In templates/admin.html:254, after the username, show <i class="fas fa-lock"> when user.login_locked is true, with :title="t('adminDashboard.loginLocked')". In the modal footer at templates/admin.html:1454-1456, add a type="button" that is visible when editingUser.login_locked is true, labeled t('adminDashboard.unlockLogin'). Its click handler PUTs /admin/users/${id} with {"unlock_login": true} and the same CSRF header updateUser already sends (templates/admin.html:2941-2956). On 200 it sets login_locked false on the open user and on the list row. It does not close the modal and does not send username, email, or password.

Add adminDashboard.loginLocked ("Login locked") and adminDashboard.unlockLogin ("Unlock login") beside updateUser in static/locales/en.json:560, and the same two keys in es.json, fr.json, de.json, zh.json, ru.json, and pt-BR.json.

Add a short "Login lock" section to docs/admin-guide/system-settings.md, whose introduction at lines 1-7 is the page that lists instance-wide settings. Name both keys, the defaults, and that 0 attempts disables the lock. State that the login page text does not change.

Tests, added beside the ones that already pass. Do not rewrite test_login_wrong_password_no_session (tests/test_cov_auth.py:136-142) or test_update_user_toggles_can_share (tests/test_cov_admin.py:286-292).

• test_login_fifth_failure_rejects_correct_password in tests/test_cov_auth.py: five wrong passwords, then the right one, still 200 with no _user_id, and login_locked_until set.
• test_login_fourth_success_clears_count in tests/test_cov_auth.py: four wrong passwords, then the right one, 302, and both columns clear.
• test_login_after_lock_expiry_succeeds in tests/test_cov_auth.py: login_locked_until in the past, right password, 302, columns clear.
• test_login_lockout_off_when_max_attempts_zero in tests/test_cov_auth.py: setting 0, six wrong passwords, then the right one still signs in.
• test_admin_unlock_login in tests/test_cov_admin.py: PUT /admin/users/<id> with {"unlock_login": true} returns 200, both columns clear, and login_locked on GET /admin/users is false.
• test_admin_unlock_login_requires_site_admin in tests/test_cov_admin.py: a signed-in non-admin receives 403 and the columns stay.

Run them with:

pytest tests/test_cov_auth.py tests/test_cov_admin.py

Expected Behavior

• One wrong password still re-renders the login form with loginFailed and no session, as test_login_wrong_password_no_session already asserts (tests/test_cov_auth.py:136-142). The fifth wrong password does the same, and the next correct password does too, until the 60 minutes pass.
• The fourth failure followed by the correct password still redirects away from /login with _user_id set, as test_login_success_sets_session_and_redirects does (tests/test_cov_auth.py:126-133), and the counter is 0.
• An unknown email and an SSO-only account keep loginFailed and useSsoLogin. Their rows gain no lock. GET /login does not increment anything.
• With login_max_failed_attempts at 0, wrong passwords never set login_locked_until.
• /forgot-password still accepts a request during a lock. Completing reset_password clears the columns in the same commit that stores the new hash (src/api/auth.py:652-662), and the following sign-in works.
• The user list shows the lock icon only for an account whose login_locked_until is still in the future. The Unlock button is the same condition. After a successful unlock PUT, both disappear without a full save of the edit form.
• A signed-in user who is not a site admin receives 403 from the existing check at src/api/admin.py:268-269. The 10 per minute IP limit on login() (src/api/auth.py:273) still applies together with the account lock.
• change_password with a wrong current password still flashes currentPasswordIncorrect (src/api/auth.py:1113-1115) and does not change failed_login_count.

Root Cause Analysis

login() decides a password sign-in at src/api/auth.py:292-309. A mismatch flashes loginFailed and returns the form. Nothing on User stores the failure: the model fields around the password stop at the reset token (src/models/user.py:20 and src/models/user.py:65-67).

The nearby control is rate_limit("10 per minute") on that route (src/api/auth.py:81-104 and src/api/auth.py:273). The limiter key is the client address (src/app.py:175-180). Its default storage is per process (src/app.py:584-592). That is a speed limit on one address, not a hold on one account. A window of "5 per hour" would also be the wrong shape: it starts at the first hit and forgets old hits, and a successful sign-in does not clear it. deduct_when only sees the finished response, and a wrong password and an unknown email both render the same loginFailed page (src/api/auth.py:309 and src/api/auth.py:313), so the decorator cannot count real accounts only.

admin_get_users (src/api/admin.py:171-188) has nowhere to read a lock from, and admin_update_user (src/api/admin.py:297-300) can replace a password without clearing a counter that does not exist yet.

Additional Context

No new dependency. requirements.txt:4-7 already pins Flask-Login 0.6.3, Flask-Bcrypt 1.0.1, and Flask-Limiter 4.1.1. Flask-Login stores the session. Flask-Limiter stays the IP limit. Flask-Security 5.8 can signal a failed authentication and ask whether a user is locked, but only on its own login endpoints, and the application still stores the counter. Adopting it would replace this login, the forms, the reset, and SSO.

This request does not add a route, does not change login copy, does not show the remaining time or the failure count in the admin UI, does not lock SSO, and does not count failures from change_password. The account row is shared by every worker, so the count stays exact without RATELIMIT_STORAGE_URI.

[murtaza-nasir]

Thank you for the suggestion. I implemented the lock per account and client address. A lock per account alone would allow anyone who knows a username, including the administrator's, to keep that account locked with a few wrong guesses.

After login_max_failed_attempts wrong passwords (default 5) for one account from one address, password sign-in for that account from that address is refused for login_lockout_minutes (default 15), even with the correct password. Sign-ins from other addresses are not affected. The login page shows the same message as for a wrong password. Setting the attempt count to 0 turns the lock off.

A locked account has a lock icon in User Management, and Unlock login in the Edit User dialog ends the lock. A correct password before the limit resets the count, and a new password set by an administrator or through a reset email ends the lock. IPv6 addresses are counted by their /64 network. As with the existing per-address limit, the client address is read from the reverse proxy's X-Forwarded-For header. Setting TRUSTED_PROXIES keeps clients that connect to Speakr directly from choosing their own address. This will be included in the next release.