Merge branch '3.4' into 4.3

* 3.4:
  Improved documentation about access controls

Author: javiereguiluz

security.rst

@@ -435,7 +435,7 @@ start with ``/admin``, you can:
 
             access_control:
                 # require ROLE_ADMIN for /admin*
-                - { path: ^/admin, roles: ROLE_ADMIN }
+                - { path: '^/admin', roles: ROLE_ADMIN }
 
                 # the 'path' value can be any valid regular expression
                 # (this one will match URLs like /api/post/7298 and /api/comment/528491)
@@ -481,11 +481,11 @@ start with ``/admin``, you can:
             ],
             'access_control' => [
                 // require ROLE_ADMIN for /admin*
-                ['path' => '^/admin', 'role' => 'ROLE_ADMIN'],
+                ['path' => '^/admin', 'roles' => 'ROLE_ADMIN'],
 
                 // the 'path' value can be any valid regular expression
                 // (this one will match URLs like /api/post/7298 and /api/comment/528491)
-                ['path' => '^/api/(post|comment)/\d+$', 'role' => 'ROLE_USER'],
+                ['path' => '^/api/(post|comment)/\d+$', 'roles' => 'ROLE_USER'],
             ],
         ]);
 
@@ -503,10 +503,10 @@ the list and stops when it finds the first match:
 
             access_control:
                 # matches /admin/users/*
-                - { path: ^/admin/users, roles: ROLE_SUPER_ADMIN }
+                - { path: '^/admin/users', roles: ROLE_SUPER_ADMIN }
 
                 # matches /admin/* except for anything matching the above rule
-                - { path: ^/admin, roles: ROLE_ADMIN }
+                - { path: '^/admin', roles: ROLE_ADMIN }
 
     .. code-block:: xml
 
@@ -533,8 +533,8 @@ the list and stops when it finds the first match:
             // ...
 
             'access_control' => [
-                ['path' => '^/admin/users', 'role' => 'ROLE_SUPER_ADMIN'],
-                ['path' => '^/admin', 'role' => 'ROLE_ADMIN'],
+                ['path' => '^/admin/users', 'roles' => 'ROLE_SUPER_ADMIN'],
+                ['path' => '^/admin', 'roles' => 'ROLE_ADMIN'],
             ],
         ]);
 

security/access_control.rst

@@ -24,11 +24,11 @@ for each ``access_control`` entry, which determines whether or not a given
 access control should be used on this request. The following ``access_control``
 options are used for matching:
 
-* ``path``
-* ``ip`` or ``ips`` (netmasks are also supported)
-* ``port``
-* ``host``
-* ``methods``
+* ``path``: a regular expression (without delimiters)
+* ``ip`` or ``ips``: netmasks are also supported
+* ``port``: an integer
+* ``host``: a regular expression
+* ``methods``: one or many methods
 
 Take the following ``access_control`` entries as an example:
 
@@ -40,11 +40,12 @@ Take the following ``access_control`` entries as an example:
         security:
             # ...
             access_control:
-                - { path: ^/admin, roles: ROLE_USER_IP, ip: 127.0.0.1 }
-                - { path: ^/admin, roles: ROLE_USER_PORT, ip: 127.0.0.1, port: 8080 }
-                - { path: ^/admin, roles: ROLE_USER_HOST, host: symfony\.com$ }
-                - { path: ^/admin, roles: ROLE_USER_METHOD, methods: [POST, PUT] }
-                - { path: ^/admin, roles: ROLE_USER }
+                - { path: '^/admin', roles: ROLE_USER_IP, ip: 127.0.0.1 }
+                - { path: '^/admin', roles: ROLE_USER_PORT, ip: 127.0.0.1, port: 8080 }
+                - { path: '^/admin', roles: ROLE_USER_HOST, host: symfony\.com$ }
+                - { path: '^/admin', roles: ROLE_USER_METHOD, methods: [POST, PUT] }
+                # when defining multiple roles, users must have at least one of them (it's like an OR condition)
+                - { path: '^/admin', roles: [ROLE_MANAGER, ROLE_ADMIN] }
 
     .. code-block:: xml
 
@@ -62,7 +63,8 @@ Take the following ``access_control`` entries as an example:
                 <rule path="^/admin" role="ROLE_USER_PORT" ip="127.0.0.1" port="8080"/>
                 <rule path="^/admin" role="ROLE_USER_HOST" host="symfony\.com$"/>
                 <rule path="^/admin" role="ROLE_USER_METHOD" methods="POST, PUT"/>
-                <rule path="^/admin" role="ROLE_USER"/>
+                <!-- when defining multiple roles, users must have at least one of them (it's like an OR condition) -->
+                <rule path="^/admin" roles="ROLE_ADMIN, ROLE_MANAGER" />
             </config>
         </srv:container>
 
@@ -74,28 +76,29 @@ Take the following ``access_control`` entries as an example:
             'access_control' => [
                 [
                     'path' => '^/admin',
-                    'role' => 'ROLE_USER_IP',
-                    'ip' => '127.0.0.1',
+                    'roles' => 'ROLE_USER_IP',
+                    'ips' => '127.0.0.1',
                 ],
                 [
                     'path' => '^/admin',
-                    'role' => 'ROLE_USER_PORT',
+                    'roles' => 'ROLE_USER_PORT',
                     'ip' => '127.0.0.1',
                     'port' => '8080',
                 ],
                 [
                     'path' => '^/admin',
-                    'role' => 'ROLE_USER_HOST',
+                    'rolse' => 'ROLE_USER_HOST',
                     'host' => 'symfony\.com$',
                 ],
                 [
                     'path' => '^/admin',
-                    'role' => 'ROLE_USER_METHOD',
+                    'roles' => 'ROLE_USER_METHOD',
                     'methods' => 'POST, PUT',
                 ],
                 [
                     'path' => '^/admin',
-                    'role' => 'ROLE_USER',
+                    // when defining multiple roles, users must have at least one of them (it's like an OR condition)
+                    'roles' => ['ROLE_MANAGER', 'ROLE_ADMIN'],
                 ],
             ],
         ]);
@@ -127,9 +130,10 @@ if ``ip``, ``port``, ``host`` or ``method`` are not specified for an entry, that
 | ``/admin/user`` | 168.0.0.1   | 80          | example.com | POST       | rule #4 (``ROLE_USER_METHOD``) | The ``ip`` and ``host`` don't match the first two entries,  |
 |                 |             |             |             |            |                                | but the third - ``ROLE_USER_METHOD`` - matches and is used. |
 +-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
-| ``/admin/user`` | 168.0.0.1   | 80          | example.com | GET        | rule #5 (``ROLE_USER``)        | The ``ip``, ``host`` and ``method`` prevent the first       |
+| ``/admin/user`` | 168.0.0.1   | 80          | example.com | GET        | rule #4 (``ROLE_MANAGER``)     | The ``ip``, ``host`` and ``method`` prevent the first       |
 |                 |             |             |             |            |                                | three entries from matching. But since the URI matches the  |
-|                 |             |             |             |            |                                | ``path`` pattern of the ``ROLE_USER`` entry, it is used.    |
+|                 |             |             |             |            |                                | ``path`` pattern, then the ``ROLE_MANAGER`` (or the         |
+|                 |             |             |             |            |                                | ``ROLE_ADMIN``) is used.                                    |
 +-----------------+-------------+-------------+-------------+------------+--------------------------------+-------------------------------------------------------------+
 | ``/foo``        | 127.0.0.1   | 80          | symfony.com | POST       | matches no entries             | This doesn't match any ``access_control`` rules, since its  |
 |                 |             |             |             |            |                                | URI doesn't match any of the ``path`` values.               |
@@ -155,6 +159,14 @@ options:
   does not match this value (e.g. ``https``), the user will be redirected
   (e.g. redirected from ``http`` to ``https``, or vice versa).
 
+.. tip::
+
+    Behind the scenes, the array value of ``roles`` is passed as the
+    ``$attributes`` argument to each voter in the application with the
+    :class:`Symfony\\Component\\HttpFoundation\\Request` as ``$subject``. You
+    can learn how to use your custom attributes by reading
+    :ref:`security/custom-voter`.
+
 .. tip::
 
     If access is denied, the system will try to authenticate the user if not
@@ -191,8 +203,8 @@ pattern so that it is only accessible by requests from the local server itself:
             access_control:
                 #
                 # the 'ips' option supports IP addresses and subnet masks
-                - { path: ^/internal, roles: IS_AUTHENTICATED_ANONYMOUSLY, ips: [127.0.0.1, ::1, 192.168.0.1/24] }
-                - { path: ^/internal, roles: ROLE_NO_ACCESS }
+                - { path: '^/internal', roles: IS_AUTHENTICATED_ANONYMOUSLY, ips: [127.0.0.1, ::1, 192.168.0.1/24] }
+                - { path: '^/internal', roles: ROLE_NO_ACCESS }
 
     .. code-block:: xml
 
@@ -225,13 +237,13 @@ pattern so that it is only accessible by requests from the local server itself:
             'access_control' => [
                 [
                     'path' => '^/internal',
-                    'role' => 'IS_AUTHENTICATED_ANONYMOUSLY',
+                    'roles' => 'IS_AUTHENTICATED_ANONYMOUSLY',
                     // the 'ips' option supports IP addresses and subnet masks
                     'ips' => ['127.0.0.1', '::1'],
                 ],
                 [
                     'path' => '^/internal',
-                    'role' => 'ROLE_NO_ACCESS',
+                    'roles' => 'ROLE_NO_ACCESS',
                 ],
             ],
         ]);
@@ -276,7 +288,10 @@ key:
             access_control:
                 -
                     path: ^/_internal/secure
-                    allow_if: "'127.0.0.1' == request.getClientIp() or is_granted('ROLE_ADMIN')"
+                    # the 'role' and 'allow-if' options work like an OR expression, so
+                    # access is granted if the expression is TRUE or the user has ROLE_ADMIN
+                    roles: 'ROLE_ADMIN'
+                    allow_if: "'127.0.0.1' == request.getClientIp() or request.header.has('X-Secure-Access')"
 
     .. code-block:: xml
 
@@ -290,8 +305,11 @@ key:
 
             <config>
                 <!-- ... -->
+                <!-- the 'role' and 'allow-if' options work like an OR expression, so
+                     access is granted if the expression is TRUE or the user has ROLE_ADMIN -->
                 <rule path="^/_internal/secure"
-                    allow-if="'127.0.0.1' == request.getClientIp() or is_granted('ROLE_ADMIN')"/>
+                    role="ROLE_ADMIN"
+                    allow-if="'127.0.0.1' == request.getClientIp() or request.header.has('X-Secure-Access')" />
             </config>
         </srv:container>
 
@@ -303,14 +321,23 @@ key:
             'access_control' => [
                 [
                     'path' => '^/_internal/secure',
-                    'allow_if' => '"127.0.0.1" == request.getClientIp() or is_granted("ROLE_ADMIN")',
+                    // the 'role' and 'allow-if' options work like an OR expression, so
+                    // access is granted if the expression is TRUE or the user has ROLE_ADMIN
+                    'roles' => 'ROLE_ADMIN',
+                    'allow_if' => '"127.0.0.1" == request.getClientIp() or request.header.has('X-Secure-Access')',
                 ],
             ],
         ]);
 
-In this case, when the user tries to access any URL starting with ``/_internal/secure``,
-they will only be granted access if the IP address is ``127.0.0.1`` or if
-the user has the ``ROLE_ADMIN`` role.
+In this case, when the user tries to access any URL starting with
+``/_internal/secure``, they will only be granted access if the IP address is
+``127.0.0.1`` or a secure header, or if the user has the ``ROLE_ADMIN`` role.
+
+.. note::
+
+    Internally ``allow_if`` triggers the built-in
+    :class:`Symfony\\Component\\Security\\Core\\Authorization\\Voter\\ExpressionVoter`
+    as like it was part of the attributes defined in the ``roles`` option.
 
 Inside the expression, you have access to a number of different variables
 and functions including ``request``, which is the Symfony
@@ -420,7 +447,7 @@ the user will be redirected to ``https``:
             'access_control' => [
                 [
                     'path' => '^/cart/checkout',
-                    'role' => 'IS_AUTHENTICATED_ANONYMOUSLY',
+                    'roles' => 'IS_AUTHENTICATED_ANONYMOUSLY',
                     'requires_channel' => 'https',
                 ],
             ],

security/force_https.rst

@@ -23,10 +23,10 @@ access control:
                 # ...
 
                 access_control:
-                    - { path: ^/secure, roles: ROLE_ADMIN, requires_channel: https }
-                    - { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY, requires_channel: https }
+                    - { path: '^/secure', roles: ROLE_ADMIN, requires_channel: https }
+                    - { path: '^/login', roles: IS_AUTHENTICATED_ANONYMOUSLY, requires_channel: https }
                     # catch all other URLs
-                    - { path: ^/, roles: IS_AUTHENTICATED_ANONYMOUSLY, requires_channel: https }
+                    - { path: '^/', roles: IS_AUTHENTICATED_ANONYMOUSLY, requires_channel: https }
 
         .. code-block:: xml
 
@@ -62,7 +62,7 @@ access control:
                 'access_control' => [
                     [
                         'path'             => '^/secure',
-                        'role'             => 'ROLE_ADMIN',
+                        'roles'            => 'ROLE_ADMIN',
                         'requires_channel' => 'https',
                     ],
                     [

security/form_login_setup.rst

@@ -31,7 +31,7 @@ and your generated code may be slightly different:
 
     Choose a name for the controller class (e.g. SecurityController) [SecurityController]:
     > SecurityController
-    
+
     Do you want to generate a '/logout' URL? (yes/no) [yes]:
     > yes
 
@@ -424,3 +424,39 @@ deal with this low level session variable. However, the
 can be used to read (like in the example above) or set this value manually.
 
 .. _`MakerBundle`: https://symfony.com/doc/current/bundles/SymfonyMakerBundle/index.html
+=======
+        // ...
+        'access_control' => [
+            ['path' => '^/login', 'roles' => 'IS_AUTHENTICATED_ANONYMOUSLY'],
+            ['path' => '^/', 'roles' => 'ROLE_ADMIN'],
+        ],
+
+3. Be Sure check_path Is Behind a Firewall
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Next, make sure that your ``check_path`` URL (e.g. ``/login``) is behind
+the firewall you're using for your form login (in this example, the single
+firewall matches *all* URLs, including ``/login``). If ``/login``
+doesn't match any firewall, you'll receive a ``Unable to find the controller
+for path "/login"`` exception.
+
+4. Multiple Firewalls Don't Share the Same Security Context
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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 :ref:`reference-security-firewall-context`
+for different firewalls. But usually for most applications, having one
+main firewall is enough.
+
+5. Routing Error Pages Are not Covered by Firewalls
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As routing is done *before* security, 404 error pages are not covered by
+any firewall. This means you can't check for security or even access the
+user object on these pages. See :doc:`/controller/error_pages`
+for more details.
+
+.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
+>>>>>>> 3.4

security/multiple_guard_authenticators.rst

@@ -108,9 +108,9 @@ the solution is to split the configuration into two separate firewalls:
                         authenticators:
                             - App\Security\LoginFormAuthenticator
             access_control:
-                - { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY }
-                - { path: ^/api, roles: ROLE_API_USER }
-                - { path: ^/, roles: ROLE_USER }
+                - { path: '^/login', roles: IS_AUTHENTICATED_ANONYMOUSLY }
+                - { path: '^/api', roles: ROLE_API_USER }
+                - { path: '^/', roles: ROLE_USER }
 
     .. code-block:: xml
 
@@ -168,8 +168,8 @@ the solution is to split the configuration into two separate firewalls:
                 ],
             ],
             'access_control' => [
-                ['path' => '^/login', 'role' => 'IS_AUTHENTICATED_ANONYMOUSLY'],
-                ['path' => '^/api', 'role' => 'ROLE_API_USER'],
-                ['path' => '^/', 'role' => 'ROLE_USER'],
+                ['path' => '^/login', 'roles' => 'IS_AUTHENTICATED_ANONYMOUSLY'],
+                ['path' => '^/api', 'roles' => 'ROLE_API_USER'],
+                ['path' => '^/', 'roles' => 'ROLE_USER'],
             ],
         ]);

security/voters.rst

@@ -1,6 +1,8 @@
 .. index::
    single: Security; Data Permission Voters
 
+.. _security/custom-voter:
+
 How to Use Voters to Check User Permissions
 ===========================================
 
@@ -19,7 +21,8 @@ How Symfony Uses Voters
 In order to use voters, you have to understand how Symfony works with them.
 All voters are called each time you use the ``isGranted()`` method on Symfony's
 authorization checker or call ``denyAccessUnlessGranted()`` in a controller (which
-uses the authorization checker).
+uses the authorization checker), or by
+:ref:`access controls <security-access-control-enforcement-options>`.
 
 Ultimately, Symfony takes the responses from all voters and makes the final
 decision (to allow or deny access to the resource) according to the strategy defined