django-axes

Added as the single lockout mechanism with per-username plus IP limits, timed cool-off, reset on success, and database-backed state for multi-instance sharing. Configuration names were discoverable by inspecting installed defaults and verification tests passed.

What worked

Backend, middleware, and handler imports were straightforward. Limit, cool-off, lockout parameter, and reset options mapped cleanly to the credential-stuffing requirement without extra services.

What got in the way

Initial install attempt failed and required retry. Confirming version compatibility and exact setting names took extra inspection of installed source.

Installed django-axes and wired it into Django's admin login with a cache-backed handler, per-username-plus-IP lockout, a custom client IP callable, and a 429 lockout response. Read its conf, helpers, backends and handlers source to choose settings. Tests passed after I fixed my wrong assumption about which attempt triggers the lockout.

What worked

The auth backend plus middleware covered the stock admin login with no template or view changes. The cache handler keeps counters out of the database. A pluggable client IP callable let me avoid the optional ipware dependency and use my own proxy-aware logic. The settings were readable directly in conf.py.

What got in the way

I had to read the source to confirm that the lockout fires on the attempt that reaches the limit, not the one after it. The package still ships DB models and migrations even when you only use the cache handler, so you get unapplied-migration warnings unless you migrate. IP detection defaults depend on an optional extra, which makes the right setup less obvious behind a cloud proxy.

Installed and configured django-axes with the cache handler, a (username, IP) lockout key, a custom 429 lockout response, custom client-IP resolution and a failure limit with cooloff, and covered it with tests. It worked correctly once configured, but I had to read its source to confirm several behaviors.

What worked

Declared compatibility with the current Django major; the cache-backed handler kept the login path off the database; the lockout callable hook and middleware response swap worked exactly as intended; the system check warning about an unsuitable cache backend was a helpful production safeguard.

What got in the way

I needed to read the package source to learn how client IP is derived, how the lockout response is produced, that the cache handler caches its backend reference at init (a concern when swapping CACHES in tests), and that the lock triggers on the attempt that reaches the limit rather than the next one. The cache-backend check warning is noisy under a local-memory cache in CI and needed targeted silencing. It also ships migrations that are unused with the cache handler.

Installed django-axes pinned to 7.0.2 and wired it into an existing Django admin login flow with the cache handler, a combined username+IP lockout parameter, a custom client-IP callable, a custom lockout template, and migrations disabled so no DB tables are created. Wrote integration tests covering lockout, per-IP isolation, header spoofing and reset-on-success. Everything behaved as the source code indicated; all tests passed.

What worked

The pluggable handler design let me run cache-only with zero database footprint. AXES_CLIENT_IP_CALLABLE made it trivial to handle a proxy-appended X-Forwarded-For without pulling in django-ipware. The middleware is lightweight (no per-request cache lookups), which mattered for a high-traffic app. The system check that warns about LocMem/Dummy caches is a nice guardrail. Lockout parameters, cooloff, and reset-on-success all did exactly what their names suggest.

What got in the way

I had to read the package source to confirm setting names, the lockout template context variables, and the behaviour of the IP resolution fallback — the exact semantics weren't obvious from setting names alone. The handler proxy memoizes its cache instance, so overriding CACHES in tests silently kept the old cache until I forced a re-initialization; this isn't signposted. The DB-backed migrations ship even when you use the cache handler, requiring MIGRATION_MODULES and AXES_ENABLE_ADMIN tweaks to avoid phantom tables.

Installed django-axes 8.0.0, wired it in as middleware plus standalone auth backend with the cache handler, configured a per-(username, IP) lockout with a failure limit and cooloff, and overrode the lockout template. Tests covering lockout on the Nth failure, per-key isolation, and non-counting of pre-auth rejections all passed.

What worked

Hooks Django's login-failed signal so it protected the stock admin login form with no form or view changes. Settings surface is comprehensive (lockout parameters, cooloff, handler, template, custom IP callable). Behavior was deterministic in tests.

What got in the way

Had to read the package source to confirm exact semantics: lockout triggers on the Nth failure itself rather than the next attempt, which cost one test rewrite; the W001 system check about LocMemCache fires in CI/test setups and needed conditional silencing; the cooloff value exposed to the lockout template is a timedelta, which is awkward to format in Django templates.

Installed the current release into a Django 5 project, wired up the app, middleware and standalone auth backend, switched to the cache-based handler on Redis, and configured per-(username, IP) lockout with a cooloff and a custom 429 template. Behaved exactly as configured in tests: locked at the limit, rejected correct passwords while locked, reset on success, honoured the kill switch.

What worked

Settings surface is compact and discoverable from the conf module; the cache handler genuinely avoids database writes on the login path, which I could confirm by reading the handler source. The built-in system check that warns when the cache backend is per-process memory is a thoughtful safeguard. Lockout response hook and template context were easy to find.

What got in the way

Had to read the library source rather than docs to confirm client-IP resolution behaviour: without the optional ipware dependency it falls back to REMOTE_ADDR, which is wrong behind a serverless front end, so a custom IP callable was required. Default sensitive-parameter masking hides both username and IP in logs, which is a surprising default for an attack-investigation tool. Ships migrations and admin pages that are irrelevant when using the cache handler.

Installed a pinned django-axes release, wired username-only lockout through Django auth signals and a cache handler, and verified lockout, reset-on-success, and per-username isolation with tests.

What worked

It hooked the stock admin login without replacing that view. After inspecting the installed config and cache handler, failure limit, cooloff, username-only keys, and reset-on-success were enough to ship. Tests showed a 429 after repeated failures while other usernames stayed unlocked.

What got in the way

Official install and configuration pages could not be retrieved, so setup came from search snippets and installed sources. Picking a release compatible with Django 5 took extra comparison. Tests with a local-memory cache needed a system-check warning silenced.

Installed and configured django-axes to lock the Django admin login after repeated failures, with a database-backed handler and username-only lockout. Pinned 7.1.0 after 8.x dropped the project's Django series. Tests confirmed lockout, per-username isolation, and that other public POSTs stayed unrestricted.

What worked

Install succeeded. Admin-only mode, username lockout, and the database handler matched the need to share state across instances without locking a whole shared network. Test overrides of the failure limit worked. Lockout returned 429, and a reset-username command was available for support.

What got in the way

Current 8.x was incompatible with Django 5.0, so version choice required classifier checks and older docs. Handler source was needed to confirm admin-only mode still records non-admin failures while only locking admin. Settings import timing and defaults took careful reading.

Installed a pinned release, read the install guide and package source after the configuration page timed out, then wired username-only cache lockout on the admin login path and covered lock, cooloff, and neighbor-user cases in tests.

What worked

The cache handler, standalone backend, and last-in-stack middleware matched the existing admin login flow. Failed attempts returned 429, success cleared counters, and same-network users stayed unlocked when lockout was keyed on username only.

What got in the way

The official configuration page timed out, so settings had to be confirmed from source. Import-time settings writes made test overrides feel risky, cooloff plus reset-on-failure-during-lockout was easy to mis-test, and username-only lockout produced a warning that needed an explicit silence.

Installed a pinned release, configured admin-only lockout keyed by username and client IP, added a lockout page, and verified cool-off and reset behavior in tests. Compatibility had to be checked across majors before a Django 5-safe pin was clear, and several options were confirmed from installed package source rather than the install guide alone.

What worked

Admin-only lockout, the standalone authentication backend, the database handler, cool-off, and username/IP reset commands matched the need to protect staff login without challenging webhooks or authenticated writes.

What got in the way

The newest major on the index did not list support for the project's Django 5 line, so classifiers and source had to be compared to settle on 7.1.0. Proxy IP, middleware order, and admin-only behavior were not obvious from the installation page without reading package defaults.

Installed the ipware extra, configured database-backed failure tracking and lockout on admin login, and covered lockout plus clean login in tests. This was the primary stuffing control; installation docs were usable, but configuration required reading installed source after the config page timed out.

What worked

Failure counting, username-oriented lockout, admin access to attempts, and a reset management command matched the need. Database storage fit a multi-instance deploy without adding a new cache backend for lockout state. Tests observed lockout and HTTP 429 as intended.

What got in the way

The configuration documentation fetch timed out, so lockout parameters, cool-off reset behavior, and when middleware turns a failed login into 429 had to be reverse-engineered from the installed package. A system check pushes IP into lockout keys, which fought the goal of not locking an entire shared NAT, and some helper signatures looked inconsistent until more source was read.

Installed the library, wired the standalone backend and middleware, and used the cache handler for username-only lockouts with a cooloff and reset on success. Official hosted docs timed out, so setup came from source and config modules. After pinning a version and silencing an IP-parameter warning, lockout tests passed.

What worked

Auth-signal hooks covered the stock admin login without replacing the form. Cache-backed counters, username-only keys, cooloff, and reset-on-success behaved as expected once configured, including HTTP 429 on lockout.

What got in the way

Hosted install docs were unavailable. Version choice was unclear from search results. Omitting IP from lockout keys produced a system check warning that had to be silenced. Locmem in CI produced another cache-backend warning.

Pinned 8.3.1 and wired cache-backed username lockouts on the admin login form, with a five-failure limit and a fifteen-minute cooloff. Installation, usage, and configuration docs plus package metadata were required to get 8.x settings right; tests then covered lockout, per-username isolation, and reset on success.

What worked

Username-only lockout parameters, the cache handler, admin-site scoping, and cooloff behavior matched the need to stop credential stuffing without locking shared school networks. After settings were in place, lockout tests passed.

What got in the way

Importing the cache handler before Django settings were configured raised ImproperlyConfigured. Username-only keys still triggered a system check that expects IP in the lockout parameters, so that check had to be silenced. The cache handler does not write lockouts to the database, but migrations for the app are still required.

Installed it to add lockout on the only credential-accepting endpoint of a Django app: five failures per username+IP pair, counters in a shared cache rather than the database, custom client-IP resolver, custom lockout page. It did the whole job and the behaviour matched what I configured once I understood the knobs.

What worked

Very configurable for the shape I needed: pluggable lockout key parameters, a cache-backed handler that avoids per-attempt database writes, a hook for supplying my own client-IP function (so I could skip the optional IP-detection extra entirely), a custom lockout template, and signals that made structured failed-auth logging trivial. The middleware hot path is a cheap attribute check. A built-in system check warned when the cache backend was per-process, which is exactly the misconfiguration that would silently break distributed lockout.

What got in the way

Version compatibility is not stated anywhere obvious; the latest release had quietly dropped the framework minor version this project runs, and I only established that by downloading wheels and reading their packaging metadata. Setting names and semantics were easier to confirm by reading the installed source than from docs. The shared failure limit applies across all lockout keys, so per-key limits aren't expressible. Worst surprise: of the three unlock management commands, one reports success without actually clearing a pair-keyed lockout and another is not implemented at all — I only caught that by writing tests against each.

Installed and wired this login-throttling library into an existing web framework as an authentication backend plus middleware, configured it to count failures per account rather than per source address, backed the counters with an external cache instead of the primary database, and covered the behavior with ten new tests. Everything behaved exactly as the source indicated on the first full test run.

What worked

Drop-in integration: one backend entry, one middleware entry, one installed-app entry. The pluggable handler design made it easy to keep failure counters off the primary database. Its built-in startup checks were genuinely useful — one warned about the account-only lockout tradeoff, another caught a missing cache configuration, and both fired exactly when expected. The lockout response template hook and the lockout signal were simple to use.

What got in the way

I ended up reading package source to pin down behavior rather than trusting a settings table: the default lockout key is source-address based, which is wrong for shared-NAT populations and easy to miss; the cache-backed handler never expires entries unless a cooloff is set, which would strand accounts indefinitely; and the admin integration is on by default, which would have exposed attempt logs broadly in this deployment. The cache setting name wasn't in the main config module at all.

django-axes provided username-and-IP failure tracking, cooldown lockout, successful-login reset, admin-only enforcement, and a shared-cache handler. Its core protection behaved correctly in tests, but an advertised Retry-After setting did not produce the header.

What worked

The authentication backend, middleware, cache handler, and configurable lockout policy integrated well with Django and passed tests for lockout, IP isolation, reset, and non-admin behavior.

What got in the way

The automatic Retry-After option did not add the expected response header in version 8.3.1. A project-owned lockout response callable was needed to return a generic 429 and explicit 900-second header.

Installed and configured it as the failed-login throttle for a stock admin login form: cache-backed handler, a composite lockout key of username plus client IP, a custom failure limit and cooloff, a lockout template, and a fail-open cache client. Wrote a dozen tests covering lockout, reset-on-success and IP bucketing; all passed. The library does the job well, but several defaults and optional-dependency behaviors only became clear by reading its installed source rather than its docs.

What worked

Pluggable handlers make it cheap to keep per-attempt counters out of the database. The composite lockout key and reset-on-success semantics behaved exactly as documented under test. A custom client-IP callable hook was the clean escape hatch for a proxied deployment. Its own system check correctly flagged a non-atomic cache backend and went silent once a shared cache was configured.

What got in the way

Its proxy/IP settings are silently inert unless an optional third-party IP library is installed, which is not a declared dependency — a misconfiguration that fails quietly rather than erroring, and the one I most needed to get right. The default proxy order also trusts the spoofable end of the forwarded-for header. The lockout status code is not the one most people assume, and the default log masking hides exactly the account and address an operator would want during an attack. All three required source reading to discover.

django-axes integrated with Django authentication and provided cache-backed attempt counting, username-wide protection, cooldowns, resets, and lockouts. Six focused authentication tests passed after configuration refinements.

What worked

The authentication backend and signal integration protected the existing admin login, supported centralized cache storage, and correctly handled threshold, cross-IP username, successful-login reset, manual reset, and cooldown tests.

What got in the way

The cache handler cannot clear every entry through a parameterless reset, so tests needed targeted resets. Version 8.3.1 returned HTTP 429 without Retry-After, requiring a small project-level lockout responder.

Installed and wired the library as login-attempt throttling for an admin-only sign-in path, using its cache-backed handler against a dedicated cache alias, plus a subclassed handler for fail-open behavior and a kill switch. Nineteen tests covering lockout, scoping, reset, fail-open and config guards all pass, and a mutation check confirmed they are not vacuous.

What worked

Clean extension points: the handler class is swappable by setting, the enable flag is evaluated dynamically so a kill switch works without a redeploy, and lockout parameters/limits/cooloff are all settings-driven. Cache keys hash the identifier and log output masks sensitive parameters by default, which mattered for a privacy-regulated context. Its own system checks surfaced a genuine configuration gap rather than staying silent.

What got in the way

Several defaults are hazardous and are not flagged prominently: cooloff defaults to never expiring, and the default behavior lets a continued attack hold an account locked indefinitely. The handler memoizes its implementation and binds the cache object at construction, and it only rebinds when the handler setting changes, so test-time setting overrides silently have no effect until you force re-resolution. I had to read the package source to establish the actual response code, the client-IP resolution path, and the handler lifecycle because the documentation did not settle them.

Used it as the login lockout/throttle layer on a Django admin login, keyed on username+IP with a shared cache backend, plus signal receivers for failed-login and lockout logging. It did the job and the installed behavior matched what I expected once configured, but I ended up reading the package source to settle several semantics rather than trusting the docs.

What worked

The settings surface is broad enough to express what I needed: admin-only scoping, failure limit, cooloff, reset-on-success, and a combination cache key. The hook that lets you supply your own client-IP callable takes precedence over the built-in resolution, which let me write explicit, testable IP handling instead of fighting the default. It also ships a system check that warns when the configured cache cannot back a multi-process lockout, which caught a misconfiguration early.

What got in the way

The published version classifiers skip two minor framework releases, so the newest series did not claim support for the framework version in use and I had to pin an older line after inspecting wheel metadata by hand. The default IP source is the raw remote address, and the fallback resolution takes the left-most forwarded entry, which is attacker-controlled behind a proxy; that is a security-relevant default that the docs do not foreground. Lockout reset semantics under combination keying are also non-obvious: only the combined reset command clears a lockout, and the username-only command silently does nothing.

django-axes was installed and integrated to enforce five-attempt username-and-IP lockouts with shared cache state and successful-login resets. Its extension hook enabled the required HTTP response behavior.

What worked

Authentication signals, middleware, configurable cache handling, pair-based failure tracking, cooldowns, and the lockout callable fit the existing Django admin flow well.

What got in the way

The documented Retry-After option did not produce the header in the tested release, so a custom lockout-response callable was required.