feature #13171 [Security] Explain lazy anonymous mode (HeahDude)

This PR was merged into the 4.4 branch.

Discussion
----------

[Security] Explain lazy anonymous mode

Fixes #12390.

I'm not sure about documenting the abstract listener, since we try here to simplify all the docs in the component. I guess this is a very advance use case to create a custom firewall (never document for now AFAIK) so this should be another issue/PR, or even a blog post.

Commits
-------

42e6ad7 [Security] Explain lazy anonymous mode

Author: wouterj

http_cache.rst

@@ -1,6 +1,8 @@
 .. index::
    single: Cache
 
+.. _http-cache:
+
 HTTP Cache
 ==========
 

security.rst

@@ -281,7 +281,7 @@ important section is ``firewalls``:
 
 .. versionadded:: 4.4
 
-    The ``anonymous: lazy`` option was introduced in Symfony 4.4.
+    The ``lazy`` anonymous mode has been 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 +293,34 @@ 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.
+it matches *all* URLs).
+A firewall can have many modes of authentication, in other words many ways 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``.
 
-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:
+In fact, if you go to the homepage right now, you *will* have access and you'll
+see that you're "authenticated" as ``anon.``. 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 means any request can have an anonymous token to access some resource, while
+some actions (i.e. some pages or buttons) can still require some privileges.
+A request can then 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>`).
 
 .. note::
 

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',