WWW-Authenticate header does not match failed authenticator

[orez-rj]

Similar issue has been raised before issue 3800 but I think it should be reconsidered.
DRF’s behavior is technically compliant with RFC 7235, but misleading in practice.

When multiple authentication_classes are used, DRF always returns the WWW-Authenticate header from the first class, even if a later authenticator is the one that rejected the request.

While RFC 7235 §4.1 allows a response to include “at least one challenge,” it expects that challenge to be applicable to the request, and in the current DRF behavior, this leads to misleading responses.

Example:

authentication_classes = [BearerAuthentication, TokenAuthentication]

If the client sends Authorization: Token abc123 (which fails), DRF still returns:

WWW-Authenticate: Bearer

This is confusing for clients, misrepresents the actual failure, and makes debugging harder.

The expected behavior is to return the challenge from the authenticator that raised the exception.
This would:

• Better reflect the RFC’s intent
• Match behaviors of other frameworks
• Improve client-side UX and debugging

Developers could still choose between "browsers should/should not respond with an authentication dialog" by implementing the authenticate_header method.

Would you be open to a PR that corrects this?

[itzzdev09]

Reproduced on DRF 3.18.0. Two authenticators, the second one actively rejecting the credentials:

class V(APIView):
    authentication_classes = [BearerAuth, TokenishAuth]   # TokenishAuth raises AuthenticationFailed
    permission_classes = [IsAuthenticated]

Authorization=Token abc123   -> 401  WWW-Authenticate='Bearer realm="api"'
Authorization=Bearer xyz     -> 401  WWW-Authenticate='Bearer realm="api"'
Authorization=<none>         -> 401  WWW-Authenticate='Bearer realm="api"'

So the challenge is identical in all three cases, including the one where TokenishAuth is what actually failed — matching what you describe.

One detail that shapes any fix: DRF sends a single challenge, from the first authenticator, whereas RFC 7235 §4.1 defines WWW-Authenticate as a list of challenges. So "return the challenge from the authenticator that failed" isn't the only option — emitting all applicable challenges is arguably the more standards-aligned change, and it's also the safer one, since dropping schemes a client could legitimately retry with would be a behavioural regression for anyone relying on the current header.

There's also a case where "the authenticator that failed" is ambiguous: when no Authorization header is sent at all, nothing fails — every authenticator abstains by returning None, and the 401 comes from the permission check rather than from authentication. There's no failing authenticator to attribute the challenge to, so that path needs an answer regardless of which approach is taken.

Worth splitting the two in the proposal, since the multi-challenge version needs no rule for picking a winner.