[Security] Explain lazy anonymous mode

HeahDude · HeahDude · commit 89891724b3e3 · 2020-02-18T19:00:04.000+01:00
diff --git a/security.rst b/security.rst
@@ -279,10 +279,6 @@ important section is ``firewalls``:
             ],
         ]);
 
-.. versionadded:: 4.4
-
-    The ``anonymous: lazy`` option was introduced in Symfony 4.4.
-
 A "firewall" is your authentication system: the configuration below it defines
 *how* your users will be able to authenticate (e.g. login form, API token, etc).
 
@@ -293,18 +289,40 @@ accidentally block Symfony's dev tools - which live under URLs like ``/_profiler
 and ``/_wdt``.
 
 All *real* URLs are handled by the ``main`` firewall (no ``pattern`` key means
-it matches *all* URLs). But this does *not* mean that every URL requires authentication.
-Nope, thanks to the ``anonymous`` key, this firewall *is* accessible anonymously.
-
-In fact, if you go to the homepage right now, you *will* have access and you'll see
-that you're "authenticated" as ``anon.``. Don't be fooled by the "Yes" next to
-Authenticated. The firewall verified that it does not know your identity, and so,
-you are anonymous:
+it matches *all* URLs).
+A firewall can have many modes of authentication, in other words many way to
+ask the question "Who are you?".
+It is convenient to first let users answer "I'm no one in particular, just a
+visitor as any other", this mode is ``anonymous``.
+It means any request can have an anonymous token to access some resource,
+while some actions (i.e. see other pages or buttons) can still require
+some privileges.
+
+In fact, if you go to the homepage right now, you *will* have access and you'll
+see that you're "authenticated" as ``anon.``. Don't be fooled by the "Yes" next
+to ``Authenticated``. The firewall verified that it does not know your
+identity, and so, you are anonymous:
 
 .. image:: /_images/security/anonymous_wdt.png
    :align: center
 
-You'll learn later how to deny access to certain URLs or controllers.
+It will also allow a request to access a form login without being authenticated
+as a unique user (otherwise an infinite redirection loop would happen asking
+the user to authenticate while trying to doing so).
+
+You'll learn later how to deny access to certain URLs, controllers, or part of
+templates.
+
+.. note::
+
+    The ``lazy`` anonymous mode prevent the session from being started if there is
+    no need for authorization (i.e. explicit check for a user privilege).
+    This is important to keep requests cacheable
+    (see :ref:`HTTP cache <http_cache>`.
+
+.. versionadded:: 4.4
+
+    The ``lazy`` anonymous mode has been introduced in Symfony 4.4.
 
 .. note::
 
diff --git a/security/form_login.rst b/security/form_login.rst
@@ -45,7 +45,7 @@ First, enable ``form_login`` under your firewall:
 
             <config>
                 <firewall name="main">
-                    <anonymous/>
+                    <anonymous lazy="true"/>
                     <form-login login-path="login" check-path="login"/>
                 </firewall>
             </config>
@@ -57,7 +57,7 @@ First, enable ``form_login`` under your firewall:
         $container->loadFromExtension('security', [
             'firewalls' => [
                 'main' => [
-                    'anonymous'  => null,
+                    'anonymous'  => 'lazy',
                     'form_login' => [
                         'login_path' => 'login',
                         'check_path' => 'login',
