feat: temporarily lock out local accounts after failed logins

[oc-tmueller]

Fixes OC10-153.

What

Core does not throttle password authentication at all (CWE-307): every entry point which verifies a password against the user backend accepts an unlimited number of attempts, so a local account with a weak password can be brute-forced online at request rate unless an optional app is installed.

This adds a DB backed temporary lockout for accounts of the built-in Database backend. Five failed attempts within 15 minutes lock the account for ten minutes. The lockout always expires on its own — there is no administrative unlock and no account is ever disabled — and a successful login clears the counter immediately. The login form names the remaining time.

External backends are deliberately not tracked: LDAP/AD counts the same attempt itself via badPwdCount, and lockout of an OIDC account belongs to the IdP, so counting here would punish twice.

Where it hooks in

The three places that verify a submitted password, each gated ahead of the credential check so a locked account does not even pay for the password hash:

• Session::loginWithPassword() — web login form, WebDAV and OCS basic auth
• TokenController::generateToken() — app password creation
• OcsController::checkPerson()

Token, auth module and remember-me logins are untouched: they revalidate an existing credential rather than a submitted password, so throttling them would only lock out already authenticated clients.

Configuration

New account_lockout.* parameters, documented in config/config.sample.php:

parameter	default	meaning
account_lockout.enabled	true	master switch
account_lockout.max_attempts	5	failures which trigger the lockout
account_lockout.duration	600	seconds an account stays locked
account_lockout.attempt_window	900	seconds of inactivity after which the counter is forgotten

Notable details

• Lockout keys are lower cased in PHP, so admin, Admin and ADMIN share one budget of attempts regardless of the database collation.
• Login names which do not resolve to an account are tracked in the same key space and produce exactly the same response as a locked existing account, so the lockout cannot be used to probe whether a user name exists. The unlocked read path performs no account lookup at all, so there is no timing difference either.
• Every counter update is a single SQL statement, so requests served by different application servers cannot lose a count; the lockout itself is started by a conditional UPDATE, so concurrent failures cannot extend a running one.
• One request may verify the same credentials twice (login by email is retried with the resolved uid) — that is counted once.
• The login route stays available while an upgrade is pending, so every statement tolerates account_lockouts being absent and simply locks nobody out until the migration has run.
• Deleting an account drops its counter, so a recreated namesake does not inherit it.
• tryBasicAuthLogin() reports a lockout the same way it reports a wrong password, because not every caller of \OC::handleLogin() handles a LoginException. The endpoints which can carry the explanation — the login form and the DAV backend — do not use that method.
• A background job (ExpireLockoutsJob) removes rows which can no longer affect a login decision.

Tests

New tests/lib/Authentication/AccountLockout/AccountLockoutTest.php (13 tests against a real database) covers the threshold, the automatic expiry, the counter decay, the disabled switch, custom thresholds, external backends, the enumeration properties, case variants, the login-by-email double count and concurrent failures. Controller and session level gating is covered in SessionTest, TokenControllerTest, OcsControllerTest and LoginControllerTest.

Verified green locally: tests/lib/User, tests/lib/Authentication, tests/Core, tests/lib/ServerTest.php, tests/lib/SetupTest.php; php-cs-fixer and phpstan clean. The schema migration and the job registration were verified against a real sqlite install.

No acceptance feature needed re-tagging: the scenarios which exceed five failed attempts never follow up with a correct password, and their accounts are deleted per scenario, which clears the counter.

Related

The same change for the master line: #41805

🤖 Generated with Claude Code