Fix #1159: Fallback to USERNAME_FIELD when AXES_USERNAME_FORM_FIELD not in credentials

[Dzhud]

Fix #1159: Fallback to USERNAME_FIELD when AXES_USERNAME_FORM_FIELD not in credentials

Summary

When AXES_USERNAME_FORM_FIELD is set to a custom value (e.g., "auth-username"), the AccessAttempt record wasn't getting the username populated because Django's user_login_failed signal sends credentials using USERNAME_FIELD (typically "username"), not the custom field name.

Changes

• Modified get_client_username() in axes/helpers.py to add fallback logic:
  • First tries the configured AXES_USERNAME_FORM_FIELD
  • Falls back to Django's get_user_model().USERNAME_FIELD if not found
• Updated documentation in docs/4_configuration.rst to describe the fallback behavior

How it works

# Before: Would return None
credentials = {"username": "john"}  # From Django's signal
settings.AXES_USERNAME_FORM_FIELD = "auth-username"
get_client_username(request, credentials)  # → None

# After: Falls back to USERNAME_FIELD
get_client_username(request, credentials)  # → "john"

Tests

Wrote 3 new tests to cover this fix:

Test	Description
test_get_client_username_fallback_to_username_field_from_credentials	Verifies fallback works when credentials use Django's USERNAME_FIELD
test_get_client_username_fallback_to_username_field_from_request	Verifies fallback works for request.POST data
test_get_client_username_custom_field_takes_priority	Ensures custom field is still preferred when present

Verification

• ✅ All existing tests pass (354 tests)
• ✅ All new tests pass (3 tests)
• ✅ mypy passes with no errors
• ✅ Documentation updated

Fixes #1159

[aleksihakli]

This code is 100% duplicated and could be written as a function, could you refactor this and add a unit test for fetching the username?

[Dzhud]

Ah, thanks for the feedback! You're absolutely right about the duplication.
I've refactored the code to extract the username lookup logic into a new get_username_from_data(data: dict) -> Optional[str] helper function. Now get_client_username() calls this helper for both credentials and request data lookups, eliminating the duplication.

Changes in this update:

1. New get_username_from_data() function in helpers.py
2. Added 5 unit tests in GetUsernameFromDataTestCase:
   2.1 test_get_username_from_data_with_matching_field
   2.2 test_get_username_from_data_fallback_to_username_field
   2.3 test_get_username_from_data_custom_field_takes_priority
   2.4 test_get_username_from_data_returns_none_when_not_found
   2.5 test_get_username_from_data_with_empty_dict

All tests pass (18 total for username handling) and mypy reports no issues.