Enhanced Firewall Restrictions docs

Squashed commits: [2081fc4] Enhanced Firewall Restrictions docs for PR symfony/symfony#10404 [8f065bc] Add redirect to new page [b42e80f] fixed typos [cc6b07d] tiny update
symfony · weaverryan · Apr 2, 2014 · Mar 18, 2014 · Mar 19, 2014 · Mar 19, 2014
commit 9889dbe00be1e046168bdb0001f7f80f15d766b5
diff --git a/book/security.rst b/book/security.rst
@@ -181,6 +181,11 @@ 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.
 
+.. tip::
+
+    You can also match a request against other details of the request (e.g. host, method). For more
+    information and examples read :doc:`/cookbook/security/firewall_restriction`.
+
 .. image:: /images/book/security_anonymous_user_access.png
    :align: center
 
@@ -2135,7 +2140,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

diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc
@@ -139,7 +139,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`

diff --git a/cookbook/security/firewall_restriction.rst b/cookbook/security/firewall_restriction.rst
@@ -0,0 +1,193 @@
+.. 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 of the request.
+
+.. note::
+
+    You can use any of these 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.
+
+.. 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 ini
8000
tialization 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.
diff --git a/cookbook/security/host_restriction.rst b/cookbook/security/host_restriction.rst
@@ -1,70 +1,4 @@
-.. index::
-   single: Security; Restrict Security Firewalls to a Host
-
 How to Restrict Firewalls to a Specific Host
 ============================================
 
-.. versionadded:: 2.4
-    Support for restricting security firewalls to a specific host was introduced in
-    Symfony 2.4.
-
-When using the Security component, you can create firewalls that match certain
-URL patterns and therefore are activated for all pages whose URL matches
-that pattern. Additionally, you can restrict the initialization of a firewall
-to a host using the ``host`` key:
-
-.. configuration-block::
-
-    .. code-block:: yaml
-
-        # app/config/security.yml
-
-        # ...
-
-        security:
-            firewalls:
-                secured_area:
-                    pattern:    ^/
-                    host:       ^admin\.example\.com$
-                    http_basic: true
-
-    .. 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="^/" host="^admin\.example\.com$">
-                    <http-basic />
-                </firewall>
-            </config>
-        </srv:container>
-
-    .. code-block:: php
-
-        // app/config/security.php
-
-        // ...
-
-        $container->loadFromExtension('security', array(
-            'firewalls' => array(
-                'secured_area' => array(
-                    'pattern'    => '^/',
-                    'host'       => '^admin\.example\.com$',
-                    'http_basic' => true,
-                ),
-            ),
-        ));
-
-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.
+This entry has moved to ":doc:`/cookbook/security/firewall_restriction`".