Documented CSRF protection in login forms

book/security.rst

@@ -319,7 +319,7 @@ First, enable form login under your firewall:
             <config>
                 <firewall name="secured_area" pattern="^/">
                     <anonymous />
-                    <form-login login_path="login" check_path="login_check" />
+                    <form-login login-path="login" check-path="login_check" />
                 </firewall>
             </config>
         </srv:container>
@@ -519,6 +519,11 @@ Finally, create the corresponding template:
             <button type="submit">login</button>
         </form>
 
+.. caution::
+
+    This login form is currently not protected against CSRF attacks. Read
+    :doc:`/cookbook/security/csrf_in_login_form` on how to protect your login form.
+
 .. tip::
 
     The ``error`` variable passed into the template is an instance of

book/validation.rst

@@ -113,8 +113,9 @@ Next, to actually validate an ``Author`` object, use the ``validate`` method
 on the ``validator`` service (class :class:`Symfony\\Component\\Validator\\Validator`).
 The job of the ``validator`` is easy: to read the constraints (i.e. rules)
 of a class and verify whether or not the data on the object satisfies those
-constraints. If validation fails, an array of errors is returned. Take this
-simple example from inside a controller::
+constraints. If validation fails, a non-empty list of errors
+(class :class:`Symfony\\Component\\Validator\\ConstraintViolationList`) is
+returned. Take this simple example from inside a controller:
 
     // ...
     use Symfony\Component\HttpFoundation\Response;

cookbook/map.rst.inc

@@ -133,6 +133,7 @@
   * :doc:`/cookbook/security/custom_provider`
   * :doc:`/cookbook/security/custom_authentication_provider`
   * :doc:`/cookbook/security/target_path`
+  * :doc:`/cookbook/security/csrf_in_login_form`
 
 * **Serializer**
 

cookbook/security/csrf_in_login_form.rst

@@ -0,0 +1,164 @@
+.. index::
+    single: Security; CSRF in the Login Form
+
+Using CSRF in the Login Form
+============================
+
+When using a login form, you should make sure that you are protected against CSRF
+(`Cross-site request forgery`_). The Security component already has built-in support
+for CSRF. In this article you'll learn how you can use it in your login form.
+
+Configuring CSRF
+----------------
+
+At first, you have to configure the Security component so it can use CSRF protection.
+The Security component needs a CSRF provider. You can set this to use the default
+provider available in the Form component:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            firewalls:
+                secured_area:
+                    # ...
+                    form_login:
+                        # ...
+                        csrf_provider: form.csrf_provider
+
+    .. code-block:: xml
+
+        <!-- app/config/config.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <firewall name="secured_area">
+                    <!-- ... -->
+
+                    <form-login csrf-provider="form.csrf_provider" />
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'secured_area' => array(
+                    // ...
+                    'form_login' => array(
+                        // ...
+                        'csrf_provider' => 'form.csrf_provider',
+                    )
+                )
+            )
+        ));
+
+The Security component can be configured further, but this is all information it needs
+to be able to use CSRF in the login form.
+
+Rendering the CSRF field
+------------------------
+
+Now the Security component checks for CSRF tokens, you have to add a *hidden* field
+to the login form containing the CSRF token. By default, this field is named as
+``_csrf_token``. That hidden field has to contain the CSRF token, which can be generated
+by using the ``csrf_token`` function. That function requires a token ID, which must
+be set to ``authenticate`` when using the login form:
+
+.. configuration-block::
+
+    .. code-block:: html+twig
+
+        {# src/Acme/SecurityBundle/Resources/views/Security/login.html.twig #}
+
+        {# ... #}
+        <form action="{{ path('login_check') }}" method="post">
+            {# ... the login fields #}
+
+            <input type="hidden" name="_csrf_token"
+                value="{{ csrf_token('authenticate') }}"
+            >
+
+            <button type="submit">login</button>
+        </form>
+
+    .. code-block:: html+php
+
+        <!-- src/Acme/SecurityBundle/Resources/views/Security/login.html.php -->
+
+        <!-- ... -->
+        <form action="<?php echo $view['router']->generate('login_check') ?>" method="post">
+            <!-- ... the login fields -->
+
+            <input type="hidden" name="_csrf_token"
+                value="<?php echo $view['form']->csrfToken('authenticate') ?>"
+            >
+
+            <button type="submit">login</button>
+        </form>
+
+After this, you have protected your login form against CSRF attacks.
+
+.. tip::
+
+    You can change the name of the field by setting ``csrf_parameter`` and change
+    the token ID by setting ``intention`` in your configuration:
+
+    .. configuration-block::
+
+        .. code-block:: yaml
+
+            # app/config/security.yml
+            security:
+                firewalls:
+                    secured_area:
+                        # ...
+                        form_login:
+                            # ...
+                            csrf_parameter: _csrf_security_token
+                            intention: a_private_string
+
+        .. code-block:: xml
+
+            <!-- app/config/config.xml -->
+            <?xml version="1.0" encoding="UTF-8" ?>
+            <srv:container xmlns="http://symfony.com/schema/dic/security"
+                xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+                xmlns:srv="http://symfony.com/schema/dic/services"
+                xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+                <config>
+                    <firewall name="secured_area">
+                        <!-- ... -->
+
+                        <form-login csrf-parameter="_csrf_security_token"
+                            intention="a_private_string" />
+                    </firewall>
+                </config>
+            </srv:container>
+
+        .. code-block:: php
+
+            // app/config/security.php
+            $container->loadFromExtension('security', array(
+                'firewalls' => array(
+                    'secured_area' => array(
+                        // ...
+                        'form_login' => array(
+                            // ...
+                            'csrf_parameter' => '_csrf_security_token',
+                            'intention'      => 'a_private_string',
+                        )
+                    )
+                )
+            ));
+
+.. _`Cross-site request forgery`: http://en.wikipedia.org/wiki/Cross-site_request_forgery

cookbook/security/index.rst

@@ -15,3 +15,4 @@ Security
     custom_provider
     custom_authentication_provider
     target_path
+    csrf_in_login_form