feature symfony#16835 [Security] Add Guard authenticator <supports> method (Amo, chalasr)

This PR was merged into the 3.4 branch.

Discussion
----------

[Security] Add Guard authenticator <supports> method

This method will be called before starting an authentication against a guard authenticator.
The authentication will be tried only if the supports method returned `true`
This improves understanding of code, increase consistency and removes responsability for `getCredentials` method to decide if the current request should be supported or not.

| Q | A |
| --- | --- |
| Bug fix? | no |
| New feature? | yes |
| BC breaks? | yes |
| Deprecations? | yes |
| Tests pass? | yes |
| Fixed tickets | none |
| License | MIT |
| Doc PR |  |

Commits
-------

78eecba Fix BC layer
a7a6f8a [Security] Add Guard authenticator <supports> method

Author: fabpot

UPGRADE-3.4.md

@@ -305,6 +305,9 @@ Security
  * Deprecated the HTTP digest authentication: `NonceExpiredException`,
    `DigestAuthenticationListener` and `DigestAuthenticationEntryPoint` will be
    removed in 4.0. Use another authentication system like `http_basic` instead.
+   
+ * The `GuardAuthenticatorInterface` has been deprecated and will be removed in 4.0.
+   Use `AuthenticatorInterface` instead.
 
 SecurityBundle
 --------------

UPGRADE-4.0.md

@@ -679,6 +679,9 @@ Security
    `DigestAuthenticationListener` and `DigestAuthenticationEntryPoint` classes
    have been removed. Use another authentication system like `http_basic` instead.
 
+ * The `GuardAuthenticatorInterface` interface has been removed.
+   Use `AuthenticatorInterface` instead.
+
 SecurityBundle
 --------------
 

src/Symfony/Component/Security/CHANGELOG.md

@@ -15,6 +15,7 @@ CHANGELOG
    requests.
  * deprecated HTTP digest authentication
  * Added a new password encoder for the Argon2i hashing algorithm
+ * deprecated `GuardAuthenticatorInterface` in favor of `AuthenticatorInterface`
 
 3.3.0
 -----

src/Symfony/Component/Security/Guard/AbstractGuardAuthenticator.php

@@ -11,6 +11,7 @@
 
 namespace Symfony\Component\Security\Guard;
 
+use Symfony\Component\HttpFoundation\Request;
 use Symfony\Component\Security\Core\User\UserInterface;
 use Symfony\Component\Security\Guard\Token\PostAuthenticationGuardToken;
 
@@ -19,8 +20,20 @@
  *
  * @author Ryan Weaver <[email protected]>
  */
-abstract class AbstractGuardAuthenticator implements GuardAuthenticatorInterface
+abstract class AbstractGuardAuthenticator implements AuthenticatorInterface
 {
+    /**
+     * {@inheritdoc}
+     *
+     * @deprecated since version 3.4, to be removed in 4.0
+     */
+    public function supports(Request $request)
+    {
+        @trigger_error(sprintf('The "%s()" method is deprecated since version 3.4 and will be removed in 4.0. Implement the "%s::supports()" method in class "%s" instead.', __METHOD__, AuthenticatorInterface::class, get_class($this)), E_USER_DEPRECATED);
+
+        return true;
+    }
+
     /**
      * Shortcut to create a PostAuthenticationGuardToken for you, if you don't really
      * care about which authenticated token you're using.

src/Symfony/Component/Security/Guard/AuthenticatorInterface.php

@@ -0,0 +1,63 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Guard;
+
+use Symfony\Component\HttpFoundation\Request;
+
+/**
+ * The interface for all "guard" authenticators.
+ *
+ * The methods on this interface are called throughout the guard authentication
+ * process to give you the power to control most parts of the process from
+ * one location.
+ *
+ * @author Ryan Weaver <[email protected]>
+ * @author Amaury Leroux de Lens <[email protected]>
+ */
+interface AuthenticatorInterface extends GuardAuthenticatorInterface
+{
+    /**
+     * Does the authenticator support the given Request?
+     *
+     * If this returns false, the authenticator will be skipped.
+     *
+     * @param Request $request
+     *
+     * @return bool
+     */
+    public function supports(Request $request);
+
+    /**
+     * Get the authentication credentials from the request and return them
+     * as any type (e.g. an associate array).
+     *
+     * Whatever value you return here will be passed to getUser() and checkCredentials()
+     *
+     * For example, for a form login, you might:
+     *
+     *      return array(
+     *          'username' => $request->request->get('_username'),
+     *          'password' => $request->request->get('_password'),
+     *      );
+     *
+     * Or for an API token that's on a header, you might use:
+     *
+     *      return array('api_key' => $request->headers->get('X-API-TOKEN'));
+     *
+     * @param Request $request
+     *
+     * @return mixed Any non-null value
+     *
+     * @throws \UnexpectedValueException If null is returned
+     */
+    public function getCredentials(Request $request);
+}

src/Symfony/Component/Security/Guard/Firewall/GuardAuthenticationListener.php

@@ -15,9 +15,10 @@
 use Symfony\Component\HttpFoundation\Response;
 use Symfony\Component\HttpKernel\Event\GetResponseEvent;
 use Symfony\Component\Security\Guard\GuardAuthenticatorHandler;
+use Symfony\Component\Security\Guard\GuardAuthenticatorInterface;
 use Symfony\Component\Security\Guard\Token\PreAuthenticationGuardToken;
 use Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface;
-use Symfony\Component\Security\Guard\GuardAuthenticatorInterface;
+use Symfony\Component\Security\Guard\AuthenticatorInterface;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
 use Symfony\Component\Security\Core\Exception\AuthenticationException;
@@ -28,6 +29,7 @@
  * Authentication listener for the "guard" system.
  *
  * @author Ryan Weaver <[email protected]>
+ * @author Amaury Leroux de Lens <[email protected]>
  */
 class GuardAuthenticationListener implements ListenerInterface
 {
@@ -39,11 +41,11 @@ class GuardAuthenticationListener implements ListenerInterface
     private $rememberMeServices;
 
     /**
-     * @param GuardAuthenticatorHandler              $guardHandler          The Guard handler
-     * @param AuthenticationManagerInterface         $authenticationManager An AuthenticationManagerInterface instance
-     * @param string                                 $providerKey           The provider (i.e. firewall) key
-     * @param iterable|GuardAuthenticatorInterface[] $guardAuthenticators   The authenticators, with keys that match what's passed to GuardAuthenticationProvider
-     * @param LoggerInterface                        $logger                A LoggerInterface instance
+     * @param GuardAuthenticatorHandler         $guardHandler          The Guard handler
+     * @param AuthenticationManagerInterface    $authenticationManager An AuthenticationManagerInterface instance
+     * @param string                            $providerKey           The provider (i.e. firewall) key
+     * @param iterable|AuthenticatorInterface[] $guardAuthenticators   The authenticators, with keys that match what's passed to GuardAuthenticationProvider
+     * @param LoggerInterface                   $logger                A LoggerInterface instance
      */
     public function __construct(GuardAuthenticatorHandler $guardHandler, AuthenticationManagerInterface $authenticationManager, $providerKey, $guardAuthenticators, LoggerInterface $logger = null)
     {
@@ -100,12 +102,29 @@ private function executeGuardAuthenticator($uniqueGuardKey, GuardAuthenticatorIn
                 $this->logger->debug('Calling getCredentials() on guard configurator.', array('firewall_key' => $this->providerKey, 'authenticator' => get_class($guardAuthenticator)));
             }
 
+            // abort the execution of the authenticator if it doesn't support the request
+            if ($guardAuthenticator instanceof AuthenticatorInterface) {
+                if (!$guardAuthenticator->supports($request)) {
+                    return;
+                }
+                // as there was a support for given request,
+                // authenticator is expected to give not-null credentials.
+                $credentialsCanBeNull = false;
+            } else {
+                // deprecated since version 3.4, to be removed in 4.0
+                $credentialsCanBeNull = true;
+            }
+
             // allow the authenticator to fetch authentication info from the request
             $credentials = $guardAuthenticator->getCredentials($request);
 
-            // allow null to be returned to skip authentication
             if (null === $credentials) {
-                return;
+                // deprecated since version 3.4, to be removed in 4.0
+                if ($credentialsCanBeNull) {
+                    return;
+                }
+
+                throw new \UnexpectedValueException(sprintf('The return value of "%s::getCredentials()" must not be null. Return false from "%s::supports()" instead.', get_class($guardAuthenticator), get_class($guardAuthenticator)));
             }
 
             // create a token with the unique key, so that the provider knows which authenticator to use
@@ -172,10 +191,10 @@ public function setRememberMeServices(RememberMeServicesInterface $rememberMeSer
      * Checks to see if remember me is supported in the authenticator and
      * on the firewall. If it is, the RememberMeServicesInterface is notified.
      *
-     * @param GuardAuthenticatorInterface $guardAuthenticator
-     * @param Request                     $request
-     * @param TokenInterface              $token
-     * @param Response                    $response
+     * @param AuthenticatorInterface $guardAuthenticator
+     * @param Request                $request
+     * @param TokenInterface         $token
+     * @param Response               $response
      */
     private function triggerRememberMe(GuardAuthenticatorInterface $guardAuthenticator, Request $request, TokenInterface $token, Response $response = null)
     {

src/Symfony/Component/Security/Guard/GuardAuthenticatorHandler.php

@@ -29,6 +29,8 @@
  * can be called directly (e.g. for manual authentication) or overridden.
  *
  * @author Ryan Weaver <[email protected]>
+ *
+ * @final since version 3.4
  */
 class GuardAuthenticatorHandler
 {
@@ -61,10 +63,10 @@ public function authenticateWithToken(TokenInterface $token, Request $request)
     /**
      * Returns the "on success" response for the given GuardAuthenticator.
      *
-     * @param TokenInterface              $token
-     * @param Request                     $request
-     * @param GuardAuthenticatorInterface $guardAuthenticator
-     * @param string                      $providerKey        The provider (i.e. firewall) key
+     * @param TokenInterface         $token
+     * @param Request                $request
+     * @param AuthenticatorInterface $guardAuthenticator
+     * @param string                 $providerKey        The provider (i.e. firewall) key
      *
      * @return null|Response
      */
@@ -88,10 +90,10 @@ public function handleAuthenticationSuccess(TokenInterface $token, Request $requ
      * Convenience method for authenticating the user and returning the
      * Response *if any* for success.
      *
-     * @param UserInterface               $user
-     * @param Request                     $request
-     * @param GuardAuthenticatorInterface $authenticator
-     * @param string                      $providerKey   The provider (i.e. firewall) key
+     * @param UserInterface          $user
+     * @param Request                $request
+     * @param AuthenticatorInterface $authenticator
+     * @param string                 $providerKey   The provider (i.e. firewall) key
      *
      * @return Response|null
      */
@@ -110,10 +112,10 @@ public function authenticateUserAndHandleSuccess(UserInterface $user, Request $r
      * Handles an authentication failure and returns the Response for the
      * GuardAuthenticator.
      *
-     * @param AuthenticationException     $authenticationException
-     * @param Request                     $request
-     * @param GuardAuthenticatorInterface $guardAuthenticator
-     * @param string                      $providerKey             The key of the firewall
+     * @param AuthenticationException $authenticationException
+     * @param Request                 $request
+     * @param AuthenticatorInterface  $guardAuthenticator
+     * @param string                  $providerKey             The key of the firewall
      *
      * @return null|Response
      */

src/Symfony/Component/Security/Guard/GuardAuthenticatorInterface.php

@@ -28,6 +28,8 @@
  * one location.
  *
  * @author Ryan Weaver <[email protected]>
+ *
+ * @deprecated since version 3.4, to be removed in 4.0. Use AuthenticatorInterface instead
  */
 interface GuardAuthenticatorInterface extends AuthenticationEntryPointInterface
 {

src/Symfony/Component/Security/Guard/Provider/GuardAuthenticationProvider.php

@@ -14,7 +14,7 @@
 use Symfony\Component\Security\Core\Authentication\Provider\AuthenticationProviderInterface;
 use Symfony\Component\Security\Core\Exception\BadCredentialsException;
 use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
-use Symfony\Component\Security\Guard\GuardAuthenticatorInterface;
+use Symfony\Component\Security\Guard\AuthenticatorInterface;
 use Symfony\Component\Security\Guard\Token\GuardTokenInterface;
 use Symfony\Component\Security\Guard\Token\PreAuthenticationGuardToken;
 use Symfony\Component\Security\Core\User\UserCheckerInterface;
@@ -32,18 +32,18 @@
 class GuardAuthenticationProvider implements AuthenticationProviderInterface
 {
     /**
-     * @var GuardAuthenticatorInterface[]
+     * @var AuthenticatorInterface[]
      */
     private $guardAuthenticators;
     private $userProvider;
     private $providerKey;
     private $userChecker;
 
     /**
-     * @param iterable|GuardAuthenticatorInterface[] $guardAuthenticators The authenticators, with keys that match what's passed to GuardAuthenticationListener
-     * @param UserProviderInterface                  $userProvider        The user provider
-     * @param string                                 $providerKey         The provider (i.e. firewall) key
-     * @param UserCheckerInterface                   $userChecker
+     * @param iterable|AuthenticatorInterface[] $guardAuthenticators The authenticators, with keys that match what's passed to GuardAuthenticationListener
+     * @param UserProviderInterface             $userProvider        The user provider
+     * @param string                            $providerKey         The provider (i.e. firewall) key
+     * @param UserCheckerInterface              $userChecker
      */
     public function __construct($guardAuthenticators, UserProviderInterface $userProvider, $providerKey, UserCheckerInterface $userChecker)
     {
@@ -101,7 +101,7 @@ public function authenticate(TokenInterface $token)
         // instances that will be checked if you have multiple firewalls.
     }
 
-    private function authenticateViaGuard(GuardAuthenticatorInterface $guardAuthenticator, PreAuthenticationGuardToken $token)
+    private function authenticateViaGuard($guardAuthenticator, PreAuthenticationGuardToken $token)
     {
         // get the user from the GuardAuthenticator
         $user = $guardAuthenticator->getUser($token->getCredentials(), $this->userProvider);