feature symfony#5265 Documentation for the new Guard authentication style (weaverryan)

This PR was merged into the 2.8 branch.

Discussion
----------

Documentation for the new Guard authentication style

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes symfony/symfony#14673
| Applies to    | 2.8+
| Fixed tickets | n/a

Hi guys!

This is a WIP documentation for a proposed new authentication system. I've written just enough so people can understand how to use it, but will finish it later once the code has gotten reviewed.

Thanks!

Commits
-------

51720c7 Many fixes thanks to great review from ogizanagi, javiereguiluz and others
4752d4c adding one clarifying message
9782ff1 adding toc entries
62dcae3 Using JsonResponse + cleanup
440fe6f revamping Guard article
bfce91b Fixing minor comments
9e411fe I'm extending the abstract class - so mention that. Also adding anonymous
ac107c7 WIP documentation for the new guard auth

Author: weaverryan

cookbook/map.rst.inc

@@ -162,6 +162,7 @@
 
   * :doc:`/cookbook/security/form_login_setup`
   * :doc:`/cookbook/security/entity_provider`
+  * :doc:`/cookbook/security/guard-authentication`
   * :doc:`/cookbook/security/remember_me`
   * :doc:`/cookbook/security/impersonating_user`
   * :doc:`/cookbook/security/form_login`

cookbook/security/api_key_authentication.rst

@@ -4,6 +4,11 @@
 How to Authenticate Users with API Keys
 =======================================
 
+.. tip::
+
+    Check out :doc:`/cookbook/security/guard-authentication` for a simpler and more
+    flexible way to accomplish custom authentication tasks like this.
+
 Nowadays, it's quite usual to authenticate the user via an API key (when developing
 a web service for instance). The API key is provided for every request and is
 passed as a query string parameter or via an HTTP header.

cookbook/security/custom_authentication_provider.rst

@@ -10,6 +10,7 @@ How to Create a custom Authentication Provider
     you through that process. But depending on your needs, you may be able
     to solve your problem in a simpler, or via a community bundle:
 
+    * :doc:`/cookbook/security/guard-authentication`
     * :doc:`/cookbook/security/custom_password_authenticator`
     * :doc:`/cookbook/security/api_key_authentication`
     * To authenticate via OAuth using a third-party service such as Google, Facebook

cookbook/security/custom_password_authenticator.rst

@@ -4,6 +4,11 @@
 How to Create a Custom Form Password Authenticator
 ==================================================
 
+.. tip::
+
+    Check out :doc:`/cookbook/security/guard-authentication` for a simpler and more
+    flexible way to accomplish custom authentication tasks like this.
+
 Imagine you want to allow access to your website only between 2pm and 4pm
 UTC. Before Symfony 2.4, you had to create a custom token, factory, listener
 and provider. In this entry, you'll learn how to do this for a login form