.. caution::

Understanding exactly how ``access_control`` works is **very** important

to make sure you application is properly secured. See :ref:`security-book-access-control-explanation`

below for detailed information.

.. _security-book-access-control-explanation:

Understanding how ``access_control`` works

For each incoming request, Symfony2 checks each ``access_control`` entry

to find *one* that matches the current request. As soon as it finds a matching

``access_control`` entry, it stops - only the **first** matching ``access_control``

is used to enforce access.

Each ``access_control`` has several options that configure two different

things: (a) :ref:`should the incoming request match this access control entry<security-book-access-control-matching-options>`

and (b) :ref:`once it matches, should some sort of access restriction be enforced<security-book-access-control-enforcement-options>`:

.. _security-book-access-control-matching-options:

**(a) Matching Options**

Symfony2 creates an instance of :class:`Symfony\\Component\\HttpFoundation\\RequestMatcher`

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``

* ``host``

* ``methods``

Take the following ``access_control`` entries as an example:

.. configuration-block::

.. code-block:: yaml

.. code-block:: xml

.. code-block:: php

For each incoming request, Symfony will decided which ``access_control``

to use based on the URI, the client's IP address, the incoming host name,

and the request method. Remember, the first rule that matches is used, and

if ``ip``, ``host`` or ``method`` are not specified for an entry, that ``access_control``

will match any ``ip``, ``host`` or ``method``:

| **URI** | **IP** | **HOST** | **METHOD** | ``access_control`` | Why? |

| ``/admin/user`` | 127.0.0.1 | example.com | GET | rule #1 (``ROLE_USER_IP``) | The URI matches ``path`` and the IP matches ``ip``. |

| ``/admin/user`` | 127.0.0.1 | symfony.com | GET | rule #1 (``ROLE_USER_IP``) | The ``path`` and ``ip`` still match. This would also match |

| | | | | | the ``ROLE_USER_HOST`` entry, but *only* the **first** |

| | | | | | ``access_control`` match is used. |

| ``/admin/user`` | 168.0.0.1 | symfony.com | GET | rule #2 (``ROLE_USER_HOST``) | The ``ip`` doesn't match the first rule, so the second |

| | | | | | rule (which matches) is used. |

| ``/admin/user`` | 168.0.0.1 | symfony.com | POST | rule #2 (``ROLE_USER_HOST``) | The second rule still matches. This would also match the |

| | | | | | third rule (``ROLE_USER_METHOD``), but only the **first** |

| | | | | | matched ``access_control`` is used. |

| ``/admin/user`` | 168.0.0.1 | example.com | POST | rule #3 (``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 | example.com | GET | rule #4 (``ROLE_USER``) | 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. |

| ``/foo`` | 127.0.0.1 | 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. |

.. _security-book-access-control-enforcement-options:

**(b) Access Enforcement**

Once Symfony2 has decided which ``access_control`` entry matches (if any),

it then *enforces* access restrictions based on the ``roles`` and ``requires_channel``

options:

* ``role`` If the user does not have the given role(s), then access is denied

(internally, an :class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`

is thrown);

* ``requires_channel`` If the incoming request's channel (e.g. ``http``)

does not match this value (e.g. ``https``), the user will be redirected

(e.g. redirected from ``http`` to ``https``, or vice versa).

.. tip::

If access is denied, the system will try to authenticate the user if not

already (e.g. redirect the user to the login page). If the user is already

logged in, the 403 "access denied" error page will be shown. See

:doc:`/cookbook/controller/error_pages` for more information.

path based on IP. This is particularly relevant in the case of

contain some private content like the current logged in user's information. To

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.

Here is how it works when the path is ``/esi/something`` coming from the

``10.0.0.1`` IP:

* The first access control rule does not match and is ignored as the ``path``

matches but the ``ip`` does not;

* The second access control rule matches (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, the first access control rule does match as both the ``path`` and the

``ip`` match: access is allowed as the user always has the

``IS_AUTHENTICATED_ANONYMOUSLY`` role.

* The second access rule is not examined as the first rule matched.

.. _book-security-securing-channel:

You can also require a user to access a URL via SSL; just use the

``requires_channel`` argument in any ``access_control`` entries:

Copyright (c) 2004-2013 Fabien Potencier