feature #3912 [Security] Added remote_user firewall info and documentation for pre authenticated firewalls (Maxime Douailin, mdouailin)

This PR was merged into the master branch.

Discussion
----------

[Security] Added remote_user firewall info and documentation for pre authenticated firewalls

| Q             | A
| ------------- | ---
| Doc fix?      | no
| New docs?     | yes (symfony/symfony#10698)
| Applies to    | 2.6+
| Fixed tickets | no

Some documentation for pre authenticated firewalls, and added remote_user configuration reference for this new firewall.

Commits
-------

f36c45e uppercase title
e6aa733 swapped comment and opening in xml configuration example
b8a0eb2 fixes missing backtick
be0d866 fix missing backtick, rephrased bottom note
86ba188 rebased using x509 pr, added remote_user pre authenticated part
8465d46 [Reference][Configuration] Removed version added for remote_user
34ad1b5 [Security] Added remote_user firewall info and documentation for pre authenticated firewalls

Author: weaverryan

cookbook/security/pre_authenticated.rst

@@ -34,8 +34,8 @@ Enable the x509 authentication for a particular firewall in the security configu
 
     .. code-block:: xml
 
-        <?xml version="1.0" ?>
         <!-- app/config/security.xml -->
+        <?xml version="1.0" ?>
         <srv:container xmlns="http://symfony.com/schema/dic/security"
             xmlns:srv="http://symfony.com/schema/dic/services">
 
@@ -66,14 +66,79 @@ the user provider, and sets the ``SSL_CLIENT_S_DN`` as credentials in the
 You can override these by setting the ``user`` and the ``credentials`` keys
 in the x509 firewall configuration respectively.
 
+.. _cookbook-security-pre-authenticated-user-provider-note:
+
 .. note::
 
     An authentication provider will only inform the user provider of the username
     that made the request. You will need to create (or use) a "user provider" that
     is referenced by the ``provider`` configuration parameter (``your_user_provider``
-    in the configuration example). This provider will turn the username into a User 
-    object of your choice. For more information on creating or configuring a user 
+    in the configuration example). This provider will turn the username into a User
+    object of your choice. For more information on creating or configuring a user
     provider, see:
 
     * :doc:`/cookbook/security/custom_provider`
-    * :doc:`/cookbook/security/entity_provider`
+    * :doc:`/cookbook/security/entity_provider`
+
+REMOTE_USER Based Authentication
+--------------------------------
+
+.. versionadded:: 2.6
+    REMOTE_USER pre authenticated firewall was introduced in Symfony 2.6.
+
+A lot of authentication modules, like ``auth_kerb`` for Apache provide the username
+using the ``REMOTE_USER`` environment variable. This variable can be trusted by
+the application since the authentication happened before the request reached it.
+
+To configure Symfony using the ``REMOTE_USER`` environment variable, simply enable the
+corresponding firewall in your security configuration:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            firewalls:
+                secured_area:
+                    pattern: ^/
+                    remote_user:
+                        provider: your_user_provider
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" ?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:srv="http://symfony.com/schema/dic/services">
+
+            <config>
+                <firewall name="secured_area" pattern="^/">
+                    <remote-user provider="your_user_provider"/>
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'secured_area' => array(
+                    'pattern'     => '^/'
+                    'remote_user' => array(
+                        'provider' => 'your_user_provider',
+                    ),
+                ),
+            ),
+        ));
+
+The firewall will then provide the ``REMOTE_USER`` environment variable to
+your user provider. You can change the variable name used by setting the ``user``
+key in the ``remote_user`` firewall configuration.
+
+.. note::
+
+    Just like for X509 authentication, you will need to configure a "user provider".
+    See :ref:`the note previous note <cookbook-security-pre-authenticated-user-provider-note>`
+    for more information.

reference/configuration/security.rst

@@ -121,6 +121,8 @@ Each part will be explained in the next section.
                     stateless: false
                     x509:
                         provider: some_key_from_above
+                    remote_user:
+                        provider: some_key_from_above
                     http_basic:
                         provider: some_key_from_above
                     http_digest: