feature #7081 JSON authentication listener docs (dunglas, javiereguiluz)

This PR was merged into the master branch.

Discussion
----------

JSON authentication listener docs

Docs for symfony/symfony#18952.

Commits
-------

b192ab3 Fixed a syntax issue
16ae3f6 Reworded and simplified the article
820f28e Fixed the name of the "username" property
6d018f6 Fixed a syntax error
ab5259b Removed a tip which is not too relevant for the article
d2dd895 Fixed the JSON format (this time for real)
6ff24da Fixed the JSON format
0961128 Show the simple example first and then explain the complex use case
68bd9a5 JSON authentication listener docs

Author: xabbuh

security/json_login_setup.rst

@@ -0,0 +1,200 @@
+How to Build a JSON Authentication Endpoint
+===========================================
+
+In this entry, you'll build a JSON endpoint to log in your users. Of course, when the
+user logs in, you can load your users from anywhere - like the database.
+See :ref:`security-user-providers` for details.
+
+First, enable the JSON login under your firewall:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+
+            firewalls:
+                main:
+                    anonymous: ~
+                    json_login:
+                        check_path: /login
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <firewall name="main">
+                    <anonymous />
+                    <json-login check-path="/login" />
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'main' => array(
+                    'anonymous'  => null,
+                    'json_login' => array(
+                        'check_path' => '/login',
+                    ),
+                ),
+            ),
+        ));
+
+.. tip::
+
+    The ``check_path`` can also be a route name (but cannot have mandatory wildcards - e.g.
+    ``/login/{foo}`` where ``foo`` has no default value).
+
+Now, when a request is made to the ``/login`` URL, the security system initiates
+the authentication process. You just need to define anywhere in your application
+an empty controller associated with that URL:
+
+.. configuration-block::
+
+    .. code-block:: php-annotations
+
+        // src/AppBundle/Controller/SecurityController.php
+
+        // ...
+        use Symfony\Component\HttpFoundation\Request;
+        use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+
+        class SecurityController extends Controller
+        {
+            /**
+             * @Route("/login", name="login")
+             */
+            public function loginAction(Request $request)
+            {
+            }
+        }
+
+    .. code-block:: yaml
+
+        # app/config/routing.yml
+        login:
+            path:     /login
+            defaults: { _controller: AppBundle:Security:login }
+
+    .. code-block:: xml
+
+        <!-- app/config/routing.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <routes xmlns="http://symfony.com/schema/routing"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/routing
+                http://symfony.com/schema/routing/routing-1.0.xsd">
+
+            <route id="login" path="/login">
+                <default key="_controller">AppBundle:Security:login</default>
+            </route>
+        </routes>
+
+    ..  code-block:: php
+
+        // app/config/routing.php
+        use Symfony\Component\Routing\RouteCollection;
+        use Symfony\Component\Routing\Route;
+
+        $collection = new RouteCollection();
+        $collection->add('login', new Route('/login', array(
+            '_controller' => 'AppBundle:Security:login',
+        )));
+
+        return $collection;
+
+Don't let this empty controller confuse you. When you submit a ``POST`` request
+to the ``/login`` URL with the following JSON document as body, the security
+system automatically handles it and takes care of checking the submitted
+username and password and authenticating the user or throwing an error:
+
+.. code-block:: json
+
+    {
+        "username": "dunglas",
+        "password": "MyPassword"
+    }
+
+If the JSON document has a different structure, you can specify the path to
+access to the user and password properties using the ``username_path`` and
+``password_path`` keys (they default respectively to ``username`` and ``password``).
+
+For example, if the JSON document has the following structure:
+
+.. code-block:: json
+
+    {
+        "security": {
+            "credentials": {
+                "login": "dunglas",
+                "password": "MyPassword"
+            }
+        }
+    }
+
+The security configuration should be:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+
+            firewalls:
+                main:
+                    anonymous: ~
+                    json_login:
+                        check_path:    login
+                        username_path: security.credentials.login
+                        password_path: security.credentials.password
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <firewall name="main">
+                    <anonymous />
+                    <json-login check-path="login"
+                                username-path="security.credentials.login"
+                                password-path="security.credentials.password" />
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'main' => array(
+                    'anonymous'  => null,
+                    'json_login' => array(
+                        'check_path' => 'login',
+                        'username_path' => 'security.credentials.login',
+                        'password_path' => 'security.credentials.password',
+                    ),
+                ),
+            ),
+        ));