feature #14673 New Guard Authentication System (e.g. putting the joy back into security) (weaverryan)

This PR was merged into the 2.8 branch.

Discussion
----------

New Guard Authentication System (e.g. putting the joy back into security)

| Q             | A
| ------------- | ---
| Bug fix?      | no
| New feature?  | yes
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | yes
| Fixed tickets | at least partially: #14300, #11158, #11451, #10035, #10463, #8606, probably more
| License       | MIT
| Doc PR        | symfony/symfony-docs#5265

Hi guys!

Though it got much easier in 2.4 with `pre_auth`, authentication is a pain in Symfony. This introduces a new authentication provider called guard, with one goal in mind: put everything you need for *any* authentication system into one spot.

### How it works

With guard, you can perform custom authentication just by implementing the [GuardAuthenticatorInterface](https://github.com/weaverryan/symfony/blob/guard/src/Symfony/Component/Security/Guard/GuardAuthenticatorInterface.php) and registering it as a service. It has methods for every part of a custom authentication flow I can think of.

For a working example, see https://github.com/weaverryan/symfony-demo/tree/guard-auth. This uses 2 authenticators simultaneously, creating a system that handles [form login](https://github.com/weaverryan/symfony-demo/blob/guard-auth/src/AppBundle/Security/FormLoginAuthenticator.php) and [api token auth](https://github.com/weaverryan/symfony-demo/blob/guard-auth/src/AppBundle/Security/TokenAuthenticator.php) with a respectable amount of code. The [security.yml](https://github.com/weaverryan/symfony-demo/blob/guard-auth/app/config/security.yml) is also quite simple.

This also supports "manual login" without jumping through hoops: https://github.com/weaverryan/symfony-demo/blob/guard-auth/src/AppBundle/Controller/SecurityController.php#L45

I've also tested with "remember me" and "switch user" - no problems with either.

I hope you like it :).

### What's Needed

1) **Other Use-Cases?**: Please think about the code and try it. What use-cases are we *not* covering? I want Guard to be simple, but cover the 99.9% use-cases.

2) **Remember me** functionality cannot be triggered via manual login. That's true now, and it's not fixed, and it's tricky.

### Deprecations?

This is a new feature, so no deprecations. But, creating a login form with a guard authenticator is a whole heck of a lot easier to understand than `form_login` or even `simple_form`. In a perfect world, we'd either deprecate those or make them use "guard" internally so that we have just **one** way of performing authentication.

Thanks!

Commits
-------

a01ed35 Adding the necessary files so that Guard can be its own installable component
d763134 Removing unnecessary override
e353833 fabbot
dd485f4 Adding a new exception and throwing it when the User changes
302235e Fixing a bug where having an authentication failure would log you out.
396a162 Tweaks thanks to Wouter
c9d9430 Adding logging  on this step and switching the order - not for any huge reason
31f9cae Adding a base class to assist with form login authentication
0501761 Allowing for other authenticators to be checked
293c8a1 meaningless author and license changes
81432f9 Adding missing factory registration
7a94994 Thanks again fabbot!
7de05be A few more changes thanks to @iltar
ffdbc66 Splitting the getting of the user and checking credentials into two steps
6edb9e1 Tweaking docblock on interface thanks to @iltar
d693721 Adding periods at the end of exceptions, and changing one class name to LogicException thanks to @iltar
eb158cb Updating interface method per suggestion - makes sense to me, Request is redundant
c73c32e Thanks fabbot!
6c180c7 Adding an edge case - this should not happen anyways
180e2c7 Properly handles "post auth" tokens that have become not authenticated
873ed28 Renaming the tokens to be clear they are "post" and "pre" auth - also adding an interface
a0bceb4 adding Guard tests
05af97c Initial commit (but after some polished work) of the new Guard authentication system
330aa7f Improving phpdoc on AuthenticationEntryPointInterface so people that implement this understand it

Author: fabpot

Core/Exception/AuthenticationExpiredException.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\Exception;
+
+/**
+ * AuthenticationServiceException is thrown when an authenticated token becomes un-authentcated between requests.
+ *
+ * In practice, this is due to the User changing between requests (e.g. password changes),
+ * causes the token to become un-authenticated.
+ *
+ * @author Ryan Weaver <ryan@knpuniversity.com>
+ */
+class AuthenticationExpiredException extends AccountStatusException
+{
+    /**
+     * {@inheritdoc}
+     */
+    public function getMessageKey()
+    {
+        return 'Authentication expired because your account information has changed.';
+    }
+}

Guard/.gitignore

@@ -0,0 +1,3 @@
+vendor/
+composer.lock
+phpunit.xml

Guard/AbstractGuardAuthenticator.php

@@ -0,0 +1,41 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * 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\Security\Core\User\UserInterface;
+use Symfony\Component\Security\Guard\Token\PostAuthenticationGuardToken;
+
+/**
+ * An optional base class that creates a PostAuthenticationGuardToken for you.
+ *
+ * @author Ryan Weaver <ryan@knpuniversity.com>
+ */
+abstract class AbstractGuardAuthenticator implements GuardAuthenticatorInterface
+{
+    /**
+     * Shortcut to create a PostAuthenticationGuardToken for you, if you don't really
+     * care about which authenticated token you're using.
+     *
+     * @param UserInterface $user
+     * @param string        $providerKey
+     *
+     * @return PostAuthenticationGuardToken
+     */
+    public function createAuthenticatedToken(UserInterface $user, $providerKey)
+    {
+        return new PostAuthenticationGuardToken(
+            $user,
+            $providerKey,
+            $user->getRoles()
+        );
+    }
+}

Guard/Authenticator/AbstractFormLoginAuthenticator.php

@@ -0,0 +1,103 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Guard\Authenticator;
+
+use Symfony\Component\Security\Guard\AbstractGuardAuthenticator;
+use Symfony\Component\HttpFoundation\RedirectResponse;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
+use Symfony\Component\Security\Core\Security;
+
+/**
+ * A base class to make form login authentication easier!
+ *
+ * @author Ryan Weaver <ryan@knpuniversity.com>
+ */
+abstract class AbstractFormLoginAuthenticator extends AbstractGuardAuthenticator
+{
+    /**
+     * Return the URL to the login page.
+     *
+     * @return string
+     */
+    abstract protected function getLoginUrl();
+
+    /**
+     * The user will be redirected to the secure page they originally tried
+     * to access. But if no such page exists (i.e. the user went to the
+     * login page directly), this returns the URL the user should be redirected
+     * to after logging in successfully (e.g. your homepage).
+     *
+     * @return string
+     */
+    abstract protected function getDefaultSuccessRedirectUrl();
+
+    /**
+     * Override to change what happens after a bad username/password is submitted.
+     *
+     * @param Request                 $request
+     * @param AuthenticationException $exception
+     *
+     * @return RedirectResponse
+     */
+    public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
+    {
+        $request->getSession()->set(Security::AUTHENTICATION_ERROR, $exception);
+        $url = $this->getLoginUrl();
+
+        return new RedirectResponse($url);
+    }
+
+    /**
+     * Override to change what happens after successful authentication.
+     *
+     * @param Request        $request
+     * @param TokenInterface $token
+     * @param string         $providerKey
+     *
+     * @return RedirectResponse
+     */
+    public function onAuthenticationSuccess(Request $request, TokenInterface $token, $providerKey)
+    {
+        // if the user hit a secure page and start() was called, this was
+        // the URL they were on, and probably where you want to redirect to
+        $targetPath = $request->getSession()->get('_security.'.$providerKey.'.target_path');
+
+        if (!$targetPath) {
+            $targetPath = $this->getDefaultSuccessRedirectUrl();
+        }
+
+        return new RedirectResponse($targetPath);
+    }
+
+    public function supportsRememberMe()
+    {
+        return true;
+    }
+
+    /**
+     * Override to control what happens when the user hits a secure page
+     * but isn't logged in yet.
+     *
+     * @param Request                      $request
+     * @param AuthenticationException|null $authException
+     *
+     * @return RedirectResponse
+     */
+    public function start(Request $request, AuthenticationException $authException = null)
+    {
+        $url = $this->getLoginUrl();
+
+        return new RedirectResponse($url);
+    }
+}

Guard/Firewall/GuardAuthenticationListener.php

@@ -0,0 +1,193 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Guard\Firewall;
+
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Event\GetResponseEvent;
+use Symfony\Component\Security\Guard\GuardAuthenticatorHandler;
+use Symfony\Component\Security\Guard\Token\PreAuthenticationGuardToken;
+use Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface;
+use Symfony\Component\Security\Guard\GuardAuthenticatorInterface;
+use Psr\Log\LoggerInterface;
+use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
+use Symfony\Component\Security\Http\Firewall\ListenerInterface;
+use Symfony\Component\Security\Http\RememberMe\RememberMeServicesInterface;
+
+/**
+ * Authentication listener for the "guard" system.
+ *
+ * @author Ryan Weaver <ryan@knpuniversity.com>
+ */
+class GuardAuthenticationListener implements ListenerInterface
+{
+    private $guardHandler;
+    private $authenticationManager;
+    private $providerKey;
+    private $guardAuthenticators;
+    private $logger;
+    private $rememberMeServices;
+
+    /**
+     * @param GuardAuthenticatorHandler      $guardHandler          The Guard handler
+     * @param AuthenticationManagerInterface $authenticationManager An AuthenticationManagerInterface instance
+     * @param string                         $providerKey           The provider (i.e. firewall) key
+     * @param GuardAuthenticatorInterface[]  $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, array $guardAuthenticators, LoggerInterface $logger = null)
+    {
+        if (empty($providerKey)) {
+            throw new \InvalidArgumentException('$providerKey must not be empty.');
+        }
+
+        $this->guardHandler = $guardHandler;
+        $this->authenticationManager = $authenticationManager;
+        $this->providerKey = $providerKey;
+        $this->guardAuthenticators = $guardAuthenticators;
+        $this->logger = $logger;
+    }
+
+    /**
+     * Iterates over each authenticator to see if each wants to authenticate the request.
+     *
+     * @param GetResponseEvent $event
+     */
+    public function handle(GetResponseEvent $event)
+    {
+        if (null !== $this->logger) {
+            $this->logger->info('Checking for guard authentication credentials.', array('firewall_key' => $this->providerKey, 'authenticators' => count($this->guardAuthenticators)));
+        }
+
+        foreach ($this->guardAuthenticators as $key => $guardAuthenticator) {
+            // get a key that's unique to *this* guard authenticator
+            // this MUST be the same as GuardAuthenticationProvider
+            $uniqueGuardKey = $this->providerKey.'_'.$key;
+
+            $this->executeGuardAuthenticator($uniqueGuardKey, $guardAuthenticator, $event);
+        }
+    }
+
+    private function executeGuardAuthenticator($uniqueGuardKey, GuardAuthenticatorInterface $guardAuthenticator, GetResponseEvent $event)
+    {
+        $request = $event->getRequest();
+        try {
+            if (null !== $this->logger) {
+                $this->logger->info('Calling getCredentials on guard configurator.', array('firewall_key' => $this->providerKey, 'authenticator' => get_class($guardAuthenticator)));
+            }
+
+            // 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;
+            }
+
+            // create a token with the unique key, so that the provider knows which authenticator to use
+            $token = new PreAuthenticationGuardToken($credentials, $uniqueGuardKey);
+
+            if (null !== $this->logger) {
+                $this->logger->info('Passing guard token information to the GuardAuthenticationProvider', array('firewall_key' => $this->providerKey, 'authenticator' => get_class($guardAuthenticator)));
+            }
+            // pass the token into the AuthenticationManager system
+            // this indirectly calls GuardAuthenticationProvider::authenticate()
+            $token = $this->authenticationManager->authenticate($token);
+
+            if (null !== $this->logger) {
+                $this->logger->info('Guard authentication successful!', array('token' => $token, 'authenticator' => get_class($guardAuthenticator)));
+            }
+
+            // sets the token on the token storage, etc
+            $this->guardHandler->authenticateWithToken($token, $request);
+        } catch (AuthenticationException $e) {
+            // oh no! Authentication failed!
+
+            if (null !== $this->logger) {
+                $this->logger->info('Guard authentication failed.', array('exception' => $e, 'authenticator' => get_class($guardAuthenticator)));
+            }
+
+            $response = $this->guardHandler->handleAuthenticationFailure($e, $request, $guardAuthenticator, $this->providerKey);
+
+            if ($response instanceof Response) {
+                $event->setResponse($response);
+            }
+
+            return;
+        }
+
+        // success!
+        $response = $this->guardHandler->handleAuthenticationSuccess($token, $request, $guardAuthenticator, $this->providerKey);
+        if ($response instanceof Response) {
+            if (null !== $this->logger) {
+                $this->logger->info('Guard authenticator set success response.', array('response' => $response, 'authenticator' => get_class($guardAuthenticator)));
+            }
+
+            $event->setResponse($response);
+        } else {
+            if (null !== $this->logger) {
+                $this->logger->info('Guard authenticator set no success response: request continues.', array('authenticator' => get_class($guardAuthenticator)));
+            }
+        }
+
+        // attempt to trigger the remember me functionality
+        $this->triggerRememberMe($guardAuthenticator, $request, $token, $response);
+    }
+
+    /**
+     * Should be called if this listener will support remember me.
+     *
+     * @param RememberMeServicesInterface $rememberMeServices
+     */
+    public function setRememberMeServices(RememberMeServicesInterface $rememberMeServices)
+    {
+        $this->rememberMeServices = $rememberMeServices;
+    }
+
+    /**
+     * 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
+     */
+    private function triggerRememberMe(GuardAuthenticatorInterface $guardAuthenticator, Request $request, TokenInterface $token, Response $response = null)
+    {
+        if (null === $this->rememberMeServices) {
+            if (null !== $this->logger) {
+                $this->logger->info('Remember me skipped: it is not configured for the firewall.', array('authenticator' => get_class($guardAuthenticator)));
+            }
+
+            return;
+        }
+
+        if (!$guardAuthenticator->supportsRememberMe()) {
+            if (null !== $this->logger) {
+                $this->logger->info('Remember me skipped: your authenticator does not support it.', array('authenticator' => get_class($guardAuthenticator)));
+            }
+
+            return;
+        }
+
+        if (!$response instanceof Response) {
+            throw new \LogicException(sprintf(
+                '%s::onAuthenticationSuccess *must* return a Response if you want to use the remember me functionality. Return a Response, or set remember_me to false under the guard configuration.',
+                get_class($guardAuthenticator)
+            ));
+        }
+
+        $this->rememberMeServices->loginSuccess($request, $response, $token);
+    }
+}