cache_csrf_form

book/forms.rst

@@ -1765,6 +1765,13 @@ section.
     The ``intention`` option is optional but greatly enhances the security of
     the generated token by making it different for each form.
 
+.. caution::
+
+    CSRF tokens are meant to be different for every user. This is why you
+    need to be cautious if you try to cache pages with forms including this
+    kind of protection. For more information, see the
+    :ref:`cookbook <cookbook-form-csrf-caching>`.
+
 .. index::
    single: Forms; With no class
 
@@ -1905,6 +1912,8 @@ Learn more from the Cookbook
 * :doc:`/cookbook/form/form_customization`
 * :doc:`/cookbook/form/dynamic_form_modification`
 * :doc:`/cookbook/form/data_transformers`
+* :doc:`/cookbook/security/csrf_in_login_form`
+* :doc:`/cookbook/cache/form_csrf_caching`
 
 .. _`Symfony2 Form component`: https://github.com/symfony/Form
 .. _`DateTime`: http://php.net/manual/en/class.datetime.php

cookbook/cache/form_csrf_caching.rst

@@ -0,0 +1,54 @@
+.. index::
+    single: Cache; CSRF; Forms
+
+Caching Pages that Contain CSRF Protected Forms
+===============================================
+
+CSRF - or `Cross-site request forgery`_ - is a method by which a malicious
+user attempts to make your legitimate users unknowingly submit data that
+they don't intend to submit. Fortunately, CSRF attacks can be prevented by
+using a CSRF token inside your forms.
+
+For more information about how this protection works in Symfony, please
+check :ref:`CSRF Protection <forms-csrf>`.
+
+.. note::
+
+    A `Security CSRF Component`_ was introduced in Symfony 2.4 which provides
+    a class CsrfTokenManager for generating and validating CSRF tokens
+
+Why Varnish does not cache by default these pages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are many ways to generate unique tokens for each user but in order get
+them validated when the form is submitted, you need to store them inside the
+PHP Session.
+
+If you are using Varnish or some similar reverse proxy cache and you try to cache
+pages containing forms with CSRF token protection, you will see that, by default,
+Varnish fails to cache them.
+
+This happens because a cookie is sent in order to preserve the PHP session open and
+Varnish default behaviour is to not cache HTTP requests with cookies.
+
+If you think about it, if you managed to cache the form you would end up
+with many users getting the same token in the form generation. When these
+users try to send the form to the server, the CSRF validation will fail for
+them because the expected token is based on the session id and different
+for each user.
+
+How to cache most of the page and still be able to use CSRF protection
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In case the HTML page where the protected form appears is heavy to load, you
+can use more advanced caching techniques like `ESI`_ fragments, having a TTL for
+the full page and embedding the form inside an ESI tag with no cache at all.
+
+Another option to be able to cache that heavy page would be loading the form
+via an uncached AJAX request but cache the rest of the HTML response.
+
+Or you can even load just the CSRF token with an AJAX request and replace the
+form field value with it.
+
+.. _`ESI`: http://www.w3.org/TR/esi-lang
+.. _`Security CSRF Component`: https://github.com/symfony/security-csrf

cookbook/cache/index.rst

@@ -5,3 +5,4 @@ Cache
     :maxdepth: 2
 
     varnish
+    form_csrf_caching