Add test coverage to prove controller is called *after* authentication validation

Problem/Motivation

Authentication provider validation happens AFTER calling the controller — this was the title I was originally going to use for this issue, and was the bug I was going to report, but it turns out to be wrong! :)

First, you must know that Basic Auth's 401s are generated by converting AccessDeniedHttpExceptions (403s) to a 401.

While working on #2737719: EntityResource: Provide comprehensive test coverage: for every entity type, every format, every method, I noticed that it's possible when POSTing to receive a 400 response for an empty body (i.e. a missing entity), before you'd get a 401 response for forgetting Basic Auth headers. This very much looks like a security hole, because that 400 is generated by the REST resource's controller code. Which means the controller code is executed before authentication mechanism validation. This means that data could be mutated before access is denied!

And this is only happening for EntityResource routes, because those routes actually grant access to all users (_access: 'TRUE' as a route requirement), consciously so, to rely on entity access checking in the controller.
(That could theoretically be improved by specifying a _entity_access route requirement. However, that was already explored in #2664780: Remove REST's resource- and verb-specific permissions for EntityResource, but provide BC and document why it's necessary for other resources and deemed unfeasible. Also, it does not really matter, this works fine too, and must also be supported.)

For all other REST resources, we do have route requirements that restrict access at the routing level (before calling the controller): each REST resource gets a permission by default. EntityResource opts out from that, because those extra permissions would be pointless: entities already have the Entity Access API. Consequently, the access checking for entity resources happens inside the controller, which is how you can get that 400 response before getting a 401.

In other words, what's special about EntityResource is:

1. It overrides ResourceBase::permissions()
2. Its controller code does the necessary access checking, but only after checking certain other things
   

     public function post(EntityInterface $entity = NULL) {
       if ($entity == NULL) {
         throw new BadRequestHttpException('No entity content received.');
       }
   
       // We need an $entity object to determine whether creating it is allowed. 
       if (!$entity->access('create')) {
         throw new AccessDeniedHttpException();
       }
   
       …
   

My fear was that this applied to all REST resources (in which case permissions being required by default would be a hugely mitigating factor), but it does not: it only applies to the entity REST resource, because that one wants to rely on Entity Access checking in the controller, rather than permission checking during routing.

Proposed resolution

Add test coverage to document this expectation, and ensure this expectation is never violated.

This was the original analysis I wrote, which is wrong. The subsequent more detailed analysis is also wrong, but it does point out weaknesses/peculiarities in the current implementation, which make this implementation so hard to understand, and allowed me to be mislead for a long while:

The root cause is that routes that require a particular authentication provider to be used have to specify it as the _auth route option. That should be a route requirement.

The way authentication providers are implemented is fairly fascinating. It was introduced at #1890878: Add modular authentication system, including Http Basic; deprecate global $user. We already had the new routing system then (but it probably wasn't very well understood yet). Nobody ever objected or even questioned why it added the _auth route option rather than requirement. Ironically, #1890878-29: Add modular authentication system, including Http Basic; deprecate global $user did propose to introduce an access check to validate the used authentication provider. And #1890878-36: Add modular authentication system, including Http Basic; deprecate global $user even added it! Damien Tournoud rightfully raised the question in #1890878-49: Add modular authentication system, including Http Basic; deprecate global $user why we were introducing our own framework/API for this rather than just reusing Symfony's Security component — it was shot down by others at the time (May 2013), because "code freeze was near".

Then Crell removed the access check in #1890878-101: Add modular authentication system, including Http Basic; deprecate global $user, with the following explanation:

I also moved the “were you authenticated by the RIGHT authenticator” check to its own route enhancer, since it’s going to fire all the time anyway and what it actually does is not deny access but change the active user.

This sounds sane. Unfortunately, it's not quite truthful. The enhancer he added would never result in a 403 (when using an authentication provider that is not global nor in the route's _auth option). But the access check did do that.

He didn't notice this resulted in a big gap. Of course, there was no test coverage to tell him this was now broken. Nor did anybody notice in the subsequent 57 comments until commit.

The only major changes since then were in #2286971: Remove dependency of current_user on request and authentication manager — that removed AuthenticationEnhancer in favor of AuthenticationSubscriber.

Remaining tasks

Write test coverage for this, to ensure maintainers/developers see that this is the intentional behavior and don't waste hours figuring out why it's misbehaving when it's actually behaving correctly.

User interface changes

None.

API changes

None.

Data model changes

None.