Documented CSRF protection in login forms

Author: wouterj

cookbook/security/csrf_in_login_form.rst

@@ -0,0 +1,115 @@
+.. 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 for CSRF
+(`Cross-site request forgery`_). The Security component already has build-in support
+form 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 provided by 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 is
+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 for CSRF attacks.
+
+.. tip::
+
+    You can change the name of the field by setting ``csrf_parameter`` and the token
+    ID by setting ``intention`` in your configuration.
+
+.. _`Cross-site request forgery`: http://en.wikipedia.org/wiki/Cross-site_request_forgery