[#2172] Adding more information about the firewall "context" key

Author: weaverryan

book/security.rst

@@ -148,6 +148,8 @@ Symfony's security system works by determining who a user is (i.e. authenticatio
 and then checking to see if that user should have access to a specific resource
 or URL.
 
+.. _book-security-firewalls:
+
 Firewalls (Authentication)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -656,8 +658,9 @@ see :doc:`/cookbook/security/form_login`.
     If you're using multiple firewalls and you authenticate against one firewall,
     you will *not* be authenticated against any other firewalls automatically.
     Different firewalls are like different security systems. To do this you have
-    to explicitly specify the same context for different firewalls. But usually
-    for most applications, having one main firewall is enough.
+    to explicitly specify the same :ref:`reference-security-firewall-context`
+    for different firewalls. But usually for most applications, having one
+    main firewall is enough.
 
 Authorization
 -------------

reference/configuration/security.rst

@@ -77,7 +77,9 @@ Each part will be explained in the next section.
                     access_denied_handler: some.service.id
                     entry_point: some.service.id
                     provider: name
-                    context: name
+                    # manages where each firewall stores session information
+                    # See "Firewall Context" below for more details
+                    context: context_key
                     stateless: false
                     x509:
                         provider: name
@@ -213,6 +215,66 @@ Redirecting after Login
 * ``target_path_parameter`` (type: ``string``, default: ``_target_path``)
 * ``use_referer`` (type: ``Boolean``, default: ``false``)
 
+.. _reference-security-firewall-context:
+
+Firewall Context
+----------------
+
+Most applications will only need one :ref:`firewall<book-security-firewalls>`.
+But if your application *does* use multiple firewalls, you'll notice that
+if you're authenticated in one firewall, you're not automatically authenticated
+in another. In other words, the systems don't share a common "context": each
+firewall acts like a separate security system.
+
+However, each firewall has an optional ``context`` key (which defaults to
+the name of the firewall), which is used when storing and retrieving security
+data to and from the session. If this key were set to the same value across
+multiple firewalls, the "context" could actually be shared:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+
+            firewalls:
+                somename:
+                    # ...
+                    context: my_context
+                othername:
+                    # ...
+                    context: my_context
+
+    .. code-block:: xml
+
+       <!-- app/config/security.xml -->
+       <security:config>
+          <firewall name="somename" context="my_context">
+            <! ... ->
+          </firewall>
+          <firewall name="othername" context="my_context">
+            <! ... ->
+          </firewall>
+       </security:config>
+
+    .. code-block:: php
+
+       // app/config/security.php
+       $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'somename' => array(
+                    // ...
+                    'context' => 'my_context'
+                ),
+                'othername' => array(
+                    // ...
+                    'context' => 'my_context'
+                ),
+            ),
+       ));
+
 HTTP-Digest Authentication
 --------------------------