Implement per-API authentication

[weierophinney]

This patch provides the mechanics necessary to implement per-API authentication.

First, I've changed the priority at which each of the authentication and authentication.post events occur. Prior to these changes, they happened at 500 and 499, respectively; they now happen at -25 and -26 (i.e., after routing, but prior to other Apigility-related listeners).

Second, you can now create a "map" key in the "authentication" configuration. The value of this should be a set of API/module + version / authentication type pairs. As an example:

return [
    'authentication' => [
        'map' => [
            'Status\V2' => 'oauth2',
            'Ping\V1' => 'basic',
            'Images\V3' => 'digest',
        ],
    ],
];

In the above, v2 of the "Status" module/API would use the configured OAuth2 authentication, v1 of the "Ping" module/API would use the configured HTTP Basic authentication, and v3 of the "Images" module/API woulduse the configured HTTP Digest authentication.

In order to retain backwards compatibility, the following rules apply:

• if
  • no authentication schemes are defined
  • then do not perform authentication
• if
  • a single authentication scheme is defined
  • and no map is present
  • then use the defined authentication
• if
  • multiple authentication schemes are defined
  • and no map is present
  • then do not perform authentication
• if
  • one or more authentication schemes are defined
  • and a map is present
  • and the current API/module does not have an entry in the map
  • then do not perform authentication
• if
  • one or more authentication schemes are defined
  • and a map is present
  • and the current API/module has an entry in the map
  • and the entry does not match one of the authentication schemes
  • then do not perform authentication
• if
  • one or more authentication schemes are defined
  • and a map is present
  • and the current API/module has an entry in the map
  • and that entry matches one of the authentication schemes
  • then use the defined authentication

All existing tests continue to pass, and tests were added for each of the above scenarios.

Allowing user-configured authentication types

One place this falls down is if a user has a custom authentication type, as currently that means they will not be able to specify their custom authentication type for an API/module. While we likely will not want to allow configuring custom adapters via the UI, having the UI aware of the type does make sense, as it allows mapping APIs to those types.

The best way to make this happen is to refactor the DefaultAuthenticationListener to be aware of authentication adapters. This approach would do the following:

• Separate the implementation specific details into their own adapters, slimming down the code in the listener.
• Provide a clean, simple, and documented API for providing additional authentication adapters other than writing an event listener.
• Provide a mechanism for exposing authentication types for purposes of mapping authentication to APIs.

The proposed authentication adapter interface is:

namespace ZF\MvcAuth\Authentication;

use Zend\Http\Request;
use Zend\Http\Response;
use ZF\MvcAuth\Identity\IdentityInterface;

interface AdapterInterface
{
    /**
     * @return array Array of types this adapter can handle
     */
    public function provides();

    /**
     * Attempt to retrieve the authentication type based on the request.
     *
     * Allows an adapter to have custom logic for detecting if a request
     * might be providing credentials it's interested in.
     *
     * @param Request $request
     * @return false|string
     */
    public function getTypeFromRequest(Request $request);

    /**
     * Perform pre-flight authentication operations.
     *
     * Use case would be for providing authentication challenge headers.
     *
     * @param Request $request
     * @param Response $response
     * @return void|Response
     */
    public function preAuth(Request $request, Response $response);

    /**
     * Attempt to authenticate the current request.
     *
     * @param Request $request
     * @param Response $response
     * @return false|IdentityInterface False on failure, IdentityInterface
     *     otherwise
     */
    public function authenticate(Request $request, Response $response);
}

The current logic specific to HTTP and OAuth2 authentication would be moved into discrete adapter implementations, and the DefaultAuthenticationListenerFactory would be updated to selectively create these adapters and attach them to the listener.

For those wanting to use custom authentication event listeners, we will provide a configuration key for specifying type names that these listeners support; however, the logic will be such that if no adapter can satisfy the type, a GuestIdentity will be returned; it will be up to the custom listener to perform the appropriate checks to see if it should be used, and to return an identity following the authentication check.

The DefaultAuthenticationListener will be updated to add the following methods:

/**
 * @return array
 */
public function attach(AdapterInterface $adapter);

/**
 * @return array Array of all supported authentication types, including both
 *     those provided by adapters and those provided via configuration.
 */
public function getAuthenticationTypes();

Tasklist

• Implement authentication maps (API/Module -> authentication type)
• Implement custom authentication awareness
  • Create authentication adapter interface
  • Modify DefaultAuthenticationListener logic to delegate to adapters
    • getTypeFromRequest() to delegate to adapters for type, if none in authorization header
    • Call preAuth() on all adapters if no type found
    • Retrieve adapter by type and use it to authenticate
• Create functionality for determining configured types
  • Pull from configured adapters (delegator factories can be used to add more adapters, so pulling the service will allow querying adapters)
  • Pull from a special configuration key

[weierophinney]

@ezimuel This patch is now ready for review; includes tests and documentation!