Merge pull request #2442 from danfinnie/multiple_ip_matching

[WCM] [SecurityBundle] Document multiple IP matching in rules

Author: weaverryan

book/security.rst

@@ -770,7 +770,7 @@ access control should be used on this request. The following ``access_control``
 options are used for matching:
 
 * ``path``
-* ``ip``
+* ``ip`` or ``ips``
 * ``host``
 * ``methods``
 
@@ -877,6 +877,11 @@ prevent any direct access to these resources from a web browser (by guessing the
 ESI URL pattern), the ESI route **must** be secured to be only visible from
 the trusted reverse proxy cache.
 
+.. versionadded:: 2.3
+    Version 2.3 allows multiple IP addresses in a single rule with the ``ips: [a, b]``
+    construct.  Prior to 2.3, users should create one rule per IP address to match and
+    use the ``ip`` key instead of ``ips``.
+
 Here is an example of how you might secure all ESI routes that start with a
 given prefix, ``/esi``, from outside access:
 
@@ -888,36 +893,37 @@ given prefix, ``/esi``, from outside access:
         security:
             # ...
             access_control:
-                - { path: ^/esi, roles: IS_AUTHENTICATED_ANONYMOUSLY, ip: 127.0.0.1 }
+                - { path: ^/esi, roles: IS_AUTHENTICATED_ANONYMOUSLY, ips: [127.0.0.1, ::1] }
                 - { path: ^/esi, roles: ROLE_NO_ACCESS }
 
     .. code-block:: xml
 
             <access-control>
-                <rule path="^/esi" role="IS_AUTHENTICATED_ANONYMOUSLY" ip="127.0.0.1" />
+                <rule path="^/esi" role="IS_AUTHENTICATED_ANONYMOUSLY" ips="127.0.0.1, ::1" />
                 <rule path="^/esi" role="ROLE_NO_ACCESS" />
             </access-control>
 
     .. code-block:: php
 
             'access_control' => array(
-                array('path' => '^/esi', 'role' => 'IS_AUTHENTICATED_ANONYMOUSLY', 'ip' => '127.0.0.1'),
+                array('path' => '^/esi', 'role' => 'IS_AUTHENTICATED_ANONYMOUSLY', 'ips' => '127.0.0.1, ::1'),
                 array('path' => '^/esi', 'role' => 'ROLE_NO_ACCESS'),
             ),
 
 Here is how it works when the path is ``/esi/something`` coming from the
 ``10.0.0.1`` IP:
 
 * The first access control rule is ignored as the ``path`` matches but the
-  ``ip`` does not;
+  ``ip`` does not match either of the IPs listed;
 
 * The second access control rule is enabled (the only restriction being the
   ``path`` and it matches): as the user cannot have the ``ROLE_NO_ACCESS``
   role as it's not defined, access is denied (the ``ROLE_NO_ACCESS`` role can
   be anything that does not match an existing role, it just serves as a trick
   to always deny access).
 
-Now, if the same request comes from ``127.0.0.1``:
+Now, if the same request comes from ``127.0.0.1`` or ``::1`` (the IPv6 loopback
+address):
 
 * Now, the first access control rule is enabled as both the ``path`` and the
   ``ip`` match: access is allowed as the user always has the