Skip to content

Protect logins through the Web Services API too - #265

Merged
codeling merged 3 commits into
mainfrom
ccr-f557f83f-uk6a4f
Nov 8, 2026
Merged

codeling merged 3 commits into
mainfrom
ccr-f557f83f-uk6a4f

Conversation

@codeling

@codeling codeling commented Nov 7, 2026 •

Copy link
Copy Markdown
Owner

Joomla has a third application besides the frontend and the backend: the Web Services API (api/index.php, client id 3). BFStop never looked at it. Failed API logins, with an API token or HTTP Basic authentication, weren't counted, so passwords could be tried there freely. Blocked addresses could also keep using the API. The component half is codeling/com_bfstop#33 (branch of the same name); CI picks it up automatically.

What changes

Setting.

  • "Active for" gets the API as a third part. The settings page shows a checkbox per part (see com_bfstop#33). The value is still stored as a bitmask: 1 frontend, 2 backend, 4 API.
  • Bfstop::originMask() and originList() convert between the bitmask and the list of ticked boxes. The plugin also understands a stored list.
  • The default is now all three (7), so an installation that never saved its settings is protected too.
  • The option strings now name the parts ("Frontend", "Backend", "Web Services API"). The strings for the combinations are gone.

Which part a request belongs to is now decided by the application's name (isClient('site'|'administrator'|'api')), not by getClientId() + 1. Joomla's client ids are:

id client
0 site
1 administrator
2 installation
3 api
4 cli

+1 only gives the right bits for 0, 1 and 3. The installation would have come out as frontend+backend and the console as frontend+API, and ConsoleApplication doesn't even have getClientId(). Neither has logins to protect, so the plugin isn't active there.

Counting failed logins (onUserLoginFailure).

  • Joomla calls login() for every API request to an endpoint that isn't public, even one with no credentials. Neither authentication plugin passes the attempted username on: the response username is always ''.
  • So a failed API login is only counted if the request actually carries credentials (ApiHelper::credentialsUsername()). A request without credentials guesses nothing, and counting it would get clients blocked just for calling a protected endpoint anonymously.
  • The username comes from HTTP Basic authentication (PHP_AUTH_USER, or the Authorization: Basic header under CGI/FPM). A token only names its user by id, so token failures are recorded with an empty username.
  • Their origin shows as "API" in the log, the mails and the component.
  • No "attempts left" or password-reset messages are queued for API clients.

Blocking.

  • The API never fires onAfterRoute, so blocks are now also enforced in onAfterApiRoute, which runs before the API logs the request in.
  • A blocked address gets an error in the API's own format: {"errors":[{"title":"<blocked message>","code":403}]}, sent as application/vnd.api+json with the same status and no-cache headers as the block page.
  • In "Login Only" mode, every API request carrying credentials counts as a login attempt. Public endpoints stay reachable without credentials.

Update from 1.x.

  • update() adds the API bit to a saved enabledForOrigin, so "frontend and backend" becomes all three and "backend only" becomes "backend and API". A setting that was never saved gets the new default anyway.
  • postflight() shows a second warning next to the existing "configuration has moved" hint, in the same way that hint points out the load balancer section: PLG_SYSTEM_BFSTOP_UPDATE_2_0_0_API_HINT. It says the API is now protected and was switched on, and links to the settings.
  • Both only happen for updates from before 2.0.0. A later update leaves the choice alone.

Description of "Active for". It now mentions the API. It also no longer claims that "a block always affects the whole site, no matter what is entered here". Blocks have only ever been enforced in the parts the plugin is active for, as already in 1.5.2; blocking through .htaccess is the exception.

The strings (ENABLED_FOR_FRONTEND, _BACKEND, _API, UPDATE_2_0_0_API_HINT) and the reworded description are in all 10 languages.

Note

Every successful API login also runs onUserLogin now: it marks earlier failed logins of that user as handled and records the known IP. That is a few small queries per authenticated API request, the same as for each frontend or backend login.

Testing

Run locally against Joomla 5.4.10 on PostgreSQL 16, with both branches deployed into the site:

  • phpunit --testsuite unit,integration: 405 tests OK, 3 skipped for environment reasons.

  • The new tests fail on main and pass here. They cover:

    • blocking through the API (JSON error and status);
    • switching the API off and on, unsaved settings protecting the API, and a stored list of bits;
    • Login Only mode with token and Basic credentials;
    • counting only API failures that carry credentials, with username and origin;
    • the update migration ("backend only" becomes 6) and its notice;
    • the bitmask/list conversion and the origin names.

    tests/Unit/ApiHelperTest.php covers the credentials detection.

  • The request and failed-login fixtures can now run as API requests (--api, --server=NAME=VALUE).

  • tests/Upgrade (CI, MySQL/MariaDB): the 1.5.2 seed saves 1.x's default "frontend and backend" (3), which the update must turn into 7, and the notice must appear in the update log.

  • check-versions, check-language, check-zip, php -l and xmllint all pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AFJFMPv7CSqgJJ93QJvYfL

Joomla's third application besides frontend and backend, the Web
Services API (api/index.php, client id 3), was never covered by
"enabledForOrigin" (1 frontend, 2 backend): failed logins there (API
token or HTTP Basic authentication) weren't counted, and blocked
addresses could keep using the API.

- "Active for" gets the API as bit 4 (client id + 1, like the other
  two), and the plugin's default becomes all three (7).
- Failed API logins are counted if the request carries credentials
  (ApiHelper). Joomla calls login() for every request to an endpoint
  which isn't public, also without credentials, and the authentication
  plugins don't pass on the username - it is taken from HTTP Basic
  authentication, a token names no username.
- Blocks are enforced in onAfterApiRoute (the API has no onAfterRoute),
  before Joomla logs the request in, with an error in the API's JSON:API
  format. In "Login Only" mode, every API request with credentials is a
  login. No reminder messages for API clients.
- Failed logins from the API show "API" as their origin.
- Updating from 1.x adds the API to a saved "enabledForOrigin" (one
  never saved gets the new default) and shows a notice next to the
  "configuration has moved" one (PLG_SYSTEM_BFSTOP_UPDATE_2_0_0_API_HINT).
- The description of "Active for" mentions the API and no longer claims
  that a block always affects the whole site: blocks have only been
  enforced in the parts the plugin is active for (as in 1.x), except
  with blocking through .htaccess.

Strings in all languages. Tests for counting, blocking, Login Only mode,
the setting, the update migration and notice, and the upgrade from 1.5.2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AFJFMPv7CSqgJJ93QJvYfL
The seed saved "backend only", which the update turns into backend
and API - and testFirstRequestConvertsTheStoredAddresses makes a site
request, which the plugin then doesn't act on, so the stored addresses
weren't converted. Frontend and backend (3, what 1.x sites have) must
become 7; backend only -> backend and API stays covered by
InstallerScriptTest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AFJFMPv7CSqgJJ93QJvYfL
- The settings form gets a checkbox per part (see com_bfstop) instead of
  a list of every combination; the stored value stays the bitmask the
  plugin reads (and 1.x stored). Bfstop::originMask() and originList()
  convert between the two. The option strings name the parts
  ("Frontend", "Backend", "Web Services API"); the strings of the
  combinations are gone.
- isEnabledForCurrentOrigin() goes by the application's name instead of
  getClientId() + 1. Joomla's client ids are 0 site, 1 administrator,
  2 installation, 3 api and 4 cli: +1 gave the bits only for 0, 1 and 3,
  the installation would have been frontend+backend and the console
  frontend+API (ConsoleApplication hasn't even got getClientId()). Other
  applications have no logins to protect; the plugin isn't active there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AFJFMPv7CSqgJJ93QJvYfL
@codeling
codeling merged commit cd14d60 into main Nov 8, 2026
18 checks passed
@codeling
codeling deleted the ccr-f557f83f-uk6a4f branch November 8, 2026 10:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants