Chapter 03 of 12
Authentication Failures
API2:2023 covers what breaks after the method is chosen correctly, from tokens accepted without a valid signature to a login endpoint that answers a thousand guesses.
The authentication guide covers choosing a method and wiring it up. This chapter is about what still breaks when that part went well, which is the subject of API2:2023 Broken Authentication.
Its OWASP references name CWE-307, Improper Restriction of Excessive Authentication Attempts, and CWE-204, Observable Response Discrepancy.
Validating a token means deciding what you accept
A token is a claim about identity that you chose to believe. Everything in this section is about the conditions under which you believe it.
The algorithm is your decision, not the token's. A JSON Web Token declares its own signing algorithm in its header, and a verifier that reads that field from the token can be handed one that declares no signature at all. Pin the accepted algorithms in the verifying configuration, so the token gets no say in how it is checked.
Check the claims that bound the token. Expiry, issuer and audience each exist to stop a perfectly valid token being used somewhere it was never meant for. A token minted for your staging tenant should not open production, and that is an audience check rather than a signature check.
Know what revocation you have. A self-contained token is valid until it expires, so short lifetimes and refresh are what limit the damage of a leak. If you need immediate revocation, you need a check against state, and that is a design decision rather than a configuration flag. The bearer tokens chapter covers the trade-off in full.
The endpoints that hand out credentials need their own rules
Login, token exchange, password reset and multi-factor verification are not ordinary endpoints, because a caller who fails them repeatedly is telling you something.
Limit attempts on both axes. A per-address limit is defeated by an attacker who spreads a single common password across ten thousand accounts, and a per-account limit is defeated by an attacker with a large address pool. Counting both is what closes the gap. The rate limiting chapter covers how a limit is communicated once you have one.
Answer failures identically. A response that distinguishes an unknown account from a wrong password confirms which addresses are registered, which is the observable discrepancy CWE-204 describes. One message and one status code for both cases.
Ask again before a sensitive change. Changing the email address, changing the password, disabling second-factor authentication and minting an API key all convert a session into permanent access. Each of them should require the current password or a fresh factor.
Where this shows up in the contract
Some of this is visible before anything runs, because the specification says which scheme protects which operation.
An API with no security scheme declared at all is a document that has not been asked the question. An operation with no security requirement, in a specification where other operations have one, is either deliberately public or an oversight, and it is worth being deliberate about which. An API key carried in a query parameter is a credential written into access logs, proxy logs and browser history, and moving it to a header costs nothing.
In Routebase
api2-broken-auth is a passive scanner and needs no personas. It runs two probes.
The first sends GET endpoints a bearer token whose header declares that no signature algorithm was used. A 2xx response means the signature was not verified, and that raises a Critical finding at medium confidence. The second finds a login-shaped POST endpoint, matching paths such as login, signin, authenticate and oauth/token, then makes a short series of failed attempts and reports when no 429 Too Many Requests ever appears. That one raises High at low confidence, because a gateway rate-limiting above the probe's threshold produces the same silence as no limit at all.
Three style guide rules cover the contract side while you are still editing it. must-define-security-scheme asks that the specification declares at least one scheme. must-have-auth-on-endpoints flags an operation with no security requirement once other operations have one, and no-api-key-in-query-param objects to an API key scheme whose location is the query string. All three sit in the security category of the style guide with a severity you set.
For the identity side, meaning schemes, grants and how each one is declared, see the API authentication guide and Components in the product documentation. The scanner behaviour is in the Scanner Reference.
Frequently asked questions
What is broken authentication in an API?
Broken authentication is an identity check that can be bypassed, replayed or worn down. OWASP lists it as API2:2023, and its references name CWE-307, Improper Restriction of Excessive Authentication Attempts, and CWE-204, Observable Response Discrepancy. The common cases are tokens accepted without proper validation, login endpoints with no attempt limit and sensitive account changes that never ask for the password again.
What is the alg none JWT vulnerability?
A JSON Web Token carries an algorithm field in its own header, and a library that trusts that field will accept a token whose header says no signature was used. The attacker then writes any claims they like. The fix is to pin the accepted algorithms in the verifying code rather than reading them from the token, which every current library supports.
Should a login endpoint be rate limited?
Yes, and it needs a stricter limit than the rest of the API, because an unlimited login endpoint turns a leaked password list into an account takeover campaign. OWASP names credential stuffing and brute force as the first scenario under API2:2023. Count failures per account as well as per address, since an attacker spreading one guess across many accounts stays under a per-address limit.
Does a password change need the current password?
It does, because otherwise a stolen session is permanently upgraded into ownership of the account. The same applies to changing the email address, disabling two-factor authentication and adding an API key. OWASP's second scenario for API2:2023 is exactly this, meaning an account takeover through an email change that asked for no confirmation.
Last reviewed by The Routebase Team.