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

3 files changed, 180 insertions, 0 deletions

diff --git a/Guard/Token/GuardTokenInterface.php b/Guard/Token/GuardTokenInterface.php
new file mode 100644
index 0000000..f0db250
--- /dev/null
+++ b/Guard/Token/GuardTokenInterface.php
@@ -0,0 +1,25 @@
+<?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\Token;
+
+/**
+ * A marker interface that both guard tokens implement.
+ *
+ * Any tokens passed to GuardAuthenticationProvider (i.e. any tokens that
+ * are handled by the guard auth system) must implement this
+ * interface.
+ *
+ * @author Ryan Weaver <ryan@knpuniversity.com>
+ */
+interface GuardTokenInterface
+{
+}
diff --git a/Guard/Token/PostAuthenticationGuardToken.php b/Guard/Token/PostAuthenticationGuardToken.php
new file mode 100644
index 0000000..36c40ca
--- /dev/null
+++ b/Guard/Token/PostAuthenticationGuardToken.php
@@ -0,0 +1,90 @@
+<?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\Token;
+
+use Symfony\Component\Security\Core\Authentication\Token\AbstractToken;
+use Symfony\Component\Security\Core\Role\RoleInterface;
+use Symfony\Component\Security\Core\User\UserInterface;
+
+/**
+ * Used as an "authenticated" token, though it could be set to not-authenticated later.
+ *
+ * If you're using Guard authentication, you *must* use a class that implements
+ * GuardTokenInterface as your authenticated token (like this class).
+ *
+ * @author Ryan Weaver <ryan@knpuniversity.com>n@gmail.com>
+ */
+class PostAuthenticationGuardToken extends AbstractToken implements GuardTokenInterface
+{
+    private $providerKey;
+
+    /**
+     * @param UserInterface            $user        The user!
+     * @param string                   $providerKey The provider (firewall) key
+     * @param RoleInterface[]|string[] $roles       An array of roles
+     *
+     * @throws \InvalidArgumentException
+     */
+    public function __construct(UserInterface $user, $providerKey, array $roles)
+    {
+        parent::__construct($roles);
+
+        if (empty($providerKey)) {
+            throw new \InvalidArgumentException('$providerKey (i.e. firewall key) must not be empty.');
+        }
+
+        $this->setUser($user);
+        $this->providerKey = $providerKey;
+
+        // this token is meant to be used after authentication success, so it is always authenticated
+        // you could set it as non authenticated later if you need to
+        parent::setAuthenticated(true);
+    }
+
+    /**
+     * This is meant to be only an authenticated token, where credentials
+     * have already been used and are thus cleared.
+     *
+     * {@inheritdoc}
+     */
+    public function getCredentials()
+    {
+        return array();
+    }
+
+    /**
+     * Returns the provider (firewall) key.
+     *
+     * @return string
+     */
+    public function getProviderKey()
+    {
+        return $this->providerKey;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function serialize()
+    {
+        return serialize(array($this->providerKey, parent::serialize()));
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function unserialize($serialized)
+    {
+        list($this->providerKey, $parentStr) = unserialize($serialized);
+        parent::unserialize($parentStr);
+    }
+}
diff --git a/Guard/Token/PreAuthenticationGuardToken.php b/Guard/Token/PreAuthenticationGuardToken.php
new file mode 100644
index 0000000..abbe985
--- /dev/null
+++ b/Guard/Token/PreAuthenticationGuardToken.php
@@ -0,0 +1,65 @@
+<?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\Token;
+
+use Symfony\Component\Security\Core\Authentication\Token\AbstractToken;
+
+/**
+ * The token used by the guard auth system before authentication.
+ *
+ * The GuardAuthenticationListener creates this, which is then consumed
+ * immediately by the GuardAuthenticationProvider. If authentication is
+ * successful, a different authenticated token is returned
+ *
+ * @author Ryan Weaver <ryan@knpuniversity.com>
+ */
+class PreAuthenticationGuardToken extends AbstractToken implements GuardTokenInterface
+{
+    private $credentials;
+    private $guardProviderKey;
+
+    /**
+     * @param mixed  $credentials
+     * @param string $guardProviderKey Unique key that bind this token to a specific GuardAuthenticatorInterface
+     */
+    public function __construct($credentials, $guardProviderKey)
+    {
+        $this->credentials = $credentials;
+        $this->guardProviderKey = $guardProviderKey;
+
+        parent::__construct(array());
+
+        // never authenticated
+        parent::setAuthenticated(false);
+    }
+
+    public function getGuardProviderKey()
+    {
+        return $this->guardProviderKey;
+    }
+
+    /**
+     * Returns the user credentials, which might be an array of anything you
+     * wanted to put in there (e.g. username, password, favoriteColor).
+     *
+     * @return mixed The user credentials
+     */
+    public function getCredentials()
+    {
+        return $this->credentials;
+    }
+
+    public function setAuthenticated($authenticated)
+    {
+        throw new \LogicException('The PreAuthenticationGuardToken is *never* authenticated.');
+    }
+}