Enhanced Firewall Restrictions docs for PR symfony/symfony#10404

book/security.rst

@@ -181,6 +181,12 @@ firewall is activated does *not* mean, however, that the HTTP authentication
 username and password box is displayed for every URL. For example, any user
 can access ``/foo`` without being prompted to authenticate.
 
+.. note::
+
+    You can also match a request against other options of the request and 
+    not only the URL. For more information and examples read
+    :doc:`/cookbook/security/firewall_restriction`.
+
 .. image:: /images/book/security_anonymous_user_access.png
    :align: center
 
@@ -2139,7 +2145,7 @@ Learn more from the Cookbook
 * :doc:`Blacklist users by IP address with a custom voter </cookbook/security/voters>`
 * :doc:`Access Control Lists (ACLs) </cookbook/security/acl>`
 * :doc:`/cookbook/security/remember_me`
-* :doc:`How to Restrict Firewalls to a Specific Host </cookbook/security/host_restriction>`
+* :doc:`How to Restrict Firewalls to a Specific Request </cookbook/security/firewall_restriction>`
 
 .. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
 .. _`implement the \Serializable interface`: http://php.net/manual/en/class.serializable.php

cookbook/map.rst.inc

@@ -138,7 +138,7 @@
   * :doc:`/cookbook/security/acl`
   * :doc:`/cookbook/security/acl_advanced`
   * :doc:`/cookbook/security/force_https`
-  * :doc:`/cookbook/security/host_restriction`
+  * :doc:`/cookbook/security/firewall_restriction`
   * :doc:`/cookbook/security/form_login`
   * :doc:`/cookbook/security/securing_services`
   * :doc:`/cookbook/security/custom_provider`

cookbook/security/firewall_restriction.rst

@@ -0,0 +1,199 @@
+.. index::
+   single: Security; Restrict Security Firewalls to a Request
+
+How to Restrict Firewalls to a Specific Request
+===============================================
+
+When using the Security component, you can create firewalls that match certain request options.
+In most cases matching against the URL is sufficient but in special cases you can further 
+restrict the initialization of a firewall against other options from the request.
+
+.. note::
+
+    You can use any of this restrictions individually or mix them together to get 
+    your desired firewall configuration. 
+
+Restricting by pattern
+----------------------
+
+This is the default restriction and restricts a firewall to only be initialized if the request URL 
+matches the configured ``pattern``. 
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+
+        # ...
+
+        security:
+            firewalls:
+                secured_area:
+                    pattern:    ^/admin
+                    # ...
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+                <firewall name="secured_area" pattern="^/admin">
+                    <!-- ... -->
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+
+        // ...
+
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'secured_area' => array(
+                    'pattern'    => '^/admin',
+                    // ...
+                ),
+            ),
+        ));
+
+The ``pattern`` is a regular expression. In this example, the firewall will only be 
+activated if the URL starts (due to the ``^`` regex character) with ``/admin`. If 
+the URL does not match this pattern, the firewall will not be activated and subsequent 
+firewalls will have the opportunity to be matched for this request.
+
+Restricting by host
+-------------------
+
+.. versionadded:: 2.4
+    Support for restricting security firewalls to a specific host was introduced in
+    Symfony 2.4.
+
+If matching against the pattern only is not enough, the request can also be matched against 
+``host``. When the configuration option ``host`` is set the firewall will be restricted to 
+only initialize if the host from the request matches against the configuration option.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+
+        # ...
+
+        security:
+            firewalls:
+                secured_area:
+                    host:       ^admin\.example\.com$
+                    # ...
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+                <firewall name="secured_area" host="^admin\.example\.com$">
+                    <!-- ... -->
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+
+        // ...
+
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'secured_area' => array(
+                    'host'       => '^admin\.example\.com$',
+                    // ...
+                ),
+            ),
+        ));
+
+The ``host`` (like the ``pattern``) is a regular expression. In this example,
+the firewall will only be activated if the host is equal exactly (due to
+the ``^`` and ``$`` regex characters) to the hostname ``admin.example.com``.
+If the hostname does not match this pattern, the firewall will not be activated
+and subsequent firewalls will have the opportunity to be matched for this
+request.
+
+Restricting by http methods
+---------------------------
+
+.. versionadded:: 2.5
+    Support for restricting security firewalls to specific http methods was introduced in
+    Symfony 2.5.
+
+The configuration option ``methods`` restricts the initialization of the firewall to
+the provided http methods.
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+
+        # ...
+
+        security:
+            firewalls:
+                secured_area:
+                    methods:    [GET, POST]
+                    # ...
+
+    .. code-block:: xml
+
+        <!-- app/config/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <!-- ... -->
+                <firewall name="secured_area" methods="GET,POST">
+                    <!-- ... -->
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+
+        // ...
+
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'secured_area' => array(
+                    'methods'    => array('GET', 'POST'),
+                    // ...
+                ),
+            ),
+        ));
+
+In this example, the firewall will only be activated if the http method of the
+request is either ``GET`` or ``POST``. If the method is not in the array of the
+allowed methods, the firewall will not be activated and subsequent firewalls will again
+have the opportunity to be matched for this request.

reference/configuration/security.rst

@@ -17,6 +17,10 @@ Each part will be explained in the next section.
     Support for restricting security firewalls to a specific host was introduced in
     Symfony 2.4.
 
+.. versionadded:: 2.5
+    Support for restricting security firewalls to specific http methods was introduced in
+    Symfony 2.5.
+
 .. configuration-block::
 
     .. code-block:: yaml
@@ -104,6 +108,8 @@ Each part will be explained in the next section.
                     pattern: .*
                     # restrict the firewall to a specific host
                     host: admin\.example\.com
+                     # restrict the firewall to specific http methods
+                    methods: [GET,POST]
                     request_matcher: some.service.id
                     access_denied_url: /foo/error403
                     access_denied_handler: some.service.id