Skip to content

Commit 808d055

Browse files
romaricdrigonromaricdrigon
committed
Created consolidated "Access control" section; added warning about routing error pages
1 parent 7c038bf commit 808d055

File tree

1 file changed

+110
-118
lines changed

1 file changed

+110
-118
lines changed

‎book/security.rst

+110-118
Original file line numberDiff line numberDiff line change
@@ -677,6 +677,11 @@ see :doc:`/cookbook/security/form_login`.
677677
for different firewalls. But usually for most applications, having one
678678
main firewall is enough.
679679

680+
**5. Routing error pages are not covered by firewalls**
681+
682+
As Routing is done *before* security, Routing error pages are not covered
683+
by any firewall.
684+
680685
Authorization
681686
-------------
682687

@@ -1000,73 +1005,6 @@ the user will be redirected to ``https``:
10001005
),
10011006
),
10021007
1003-
.. _book-security-securing-controller:
1004-
1005-
Securing a Controller
1006-
~~~~~~~~~~~~~~~~~~~~~
1007-
1008-
Protecting your application based on URL patterns is easy, but may not be
1009-
fine-grained enough in certain cases. When necessary, you can easily force
1010-
authorization from inside a controller::
1011-
1012-
// ...
1013-
use Symfony\Component\Security\Core\Exception\AccessDeniedException;
1014-
1015-
public function helloAction($name)
1016-
{
1017-
if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
1018-
throw new AccessDeniedException();
1019-
}
1020-
1021-
// ...
1022-
}
1023-
1024-
.. _book-security-securing-controller-annotations:
1025-
1026-
You can also choose to install and use the optional JMSSecurityExtraBundle,
1027-
which can secure your controller using annotations::
1028-
1029-
// ...
1030-
use JMS\SecurityExtraBundle\Annotation\Secure;
1031-
1032-
/**
1033-
* @Secure(roles="ROLE_ADMIN")
1034-
*/
1035-
public function helloAction($name)
1036-
{
1037-
// ...
1038-
}
1039-
1040-
For more information, see the `JMSSecurityExtraBundle`_ documentation.
1041-
1042-
Securing other Services
1043-
~~~~~~~~~~~~~~~~~~~~~~~
1044-
1045-
In fact, anything in Symfony can be protected using a strategy similar to
1046-
the one seen in the previous section. For example, suppose you have a service
1047-
(i.e. a PHP class) whose job is to send emails from one user to another.
1048-
You can restrict use of this class - no matter where it's being used from -
1049-
to users that have a specific role.
1050-
1051-
For more information on how you can use the Security component to secure
1052-
different services and methods in your application, see :doc:`/cookbook/security/securing_services`.
1053-
1054-
Access Control Lists (ACLs): Securing Individual Database Objects
1055-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1056-
1057-
Imagine you are designing a blog system where your users can comment on your
1058-
posts. Now, you want a user to be able to edit their own comments, but not
1059-
those of other users. Also, as the admin user, you yourself want to be able
1060-
to edit *all* comments.
1061-
1062-
The Security component comes with an optional access control list (ACL) system
1063-
that you can use when you need to control access to individual instances
1064-
of an object in your system. *Without* ACL, you can secure your system so that
1065-
only certain users can edit blog comments in general. But *with* ACL, you
1066-
can restrict or allow access on a comment-by-comment basis.
1067-
1068-
For more information, see the cookbook article: :doc:`/cookbook/security/acl`.
1069-
10701008
Users
10711009
-----
10721010

@@ -1711,6 +1649,111 @@ In the above configuration, users with ``ROLE_ADMIN`` role will also have the
17111649
``ROLE_USER`` role. The ``ROLE_SUPER_ADMIN`` role has ``ROLE_ADMIN``, ``ROLE_ALLOWED_TO_SWITCH``
17121650
and ``ROLE_USER`` (inherited from ``ROLE_ADMIN``).
17131651

1652+
Access Control
1653+
--------------
1654+
1655+
Now that you have Users and Roles, you can go further than URL patterns based authorization.
1656+
1657+
.. _book-security-securing-controller:
1658+
1659+
Access Control in Controllers
1660+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1661+
1662+
Protecting your application based on URL patterns is easy, but may not be
1663+
fine-grained enough in certain cases. When necessary, you can easily force
1664+
authorization from inside a controller::
1665+
1666+
// ...
1667+
use Symfony\Component\Security\Core\Exception\AccessDeniedException;
1668+
1669+
public function helloAction($name)
1670+
{
1671+
if (false === $this->get('security.context')->isGranted('ROLE_ADMIN')) {
1672+
throw new AccessDeniedException();
1673+
}
1674+
1675+
// ...
1676+
}
1677+
1678+
.. caution::
1679+
1680+
A firewall must be active or an exception will be thrown when the ``isGranted()``
1681+
method is called. It's almost always a good idea to have a main firewall that
1682+
covers all URLs (as it has been shown in this chapter).
1683+
1684+
.. _book-security-securing-controller-annotations:
1685+
1686+
You can also choose to install and use the optional `JMSSecurityExtraBundle`_,
1687+
which can secure your controller using annotations::
1688+
1689+
// ...
1690+
use JMS\SecurityExtraBundle\Annotation\Secure;
1691+
1692+
/**
1693+
* @Secure(roles="ROLE_ADMIN")
1694+
*/
1695+
public function helloAction($name)
1696+
{
1697+
// ...
1698+
}
1699+
1700+
Access Control in Other Services
1701+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1702+
1703+
In fact, anything in Symfony can be protected using a strategy similar to
1704+
the one seen in the previous section. For example, suppose you have a service
1705+
(i.e. a PHP class) whose job is to send emails from one user to another.
1706+
You can restrict use of this class - no matter where it's being used from -
1707+
to users that have a specific role.
1708+
1709+
For more information on how you can use the Security component to secure
1710+
different services and methods in your application, see :doc:`/cookbook/security/securing_services`.
1711+
1712+
.. _book-security-template:
1713+
1714+
Access Control in Templates
1715+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
1716+
1717+
If you want to check if the current user has a role inside a template, use
1718+
the built-in helper function:
1719+
1720+
.. configuration-block::
1721+
1722+
.. code-block:: html+jinja
1723+
1724+
{% if is_granted('ROLE_ADMIN') %}
1725+
<a href="...">Delete</a>
1726+
{% endif %}
1727+
1728+
.. code-block:: html+php
1729+
1730+
<?php if ($view['security']->isGranted('ROLE_ADMIN')): ?>
1731+
<a href="...">Delete</a>
1732+
<?php endif; ?>
1733+
1734+
.. note::
1735+
1736+
If you use this function and are *not* at a URL behind a firewall
1737+
active, an exception will be thrown. Again, it's almost always a good
1738+
idea to have a main firewall that covers all URLs (as has been shown
1739+
in this chapter).
1740+
1741+
Access Control Lists (ACLs): Securing Individual Database Objects
1742+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1743+
1744+
Imagine you are designing a blog system where your users can comment on your
1745+
posts. Now, you want a user to be able to edit their own comments, but not
1746+
those of other users. Also, as the admin user, you yourself want to be able
1747+
to edit *all* comments.
1748+
1749+
The Security component comes with an optional access control list (ACL) system
1750+
that you can use when you need to control access to individual instances
1751+
of an object in your system. *Without* ACL, you can secure your system so that
1752+
only certain users can edit blog comments in general. But *with* ACL, you
1753+
can restrict or allow access on a comment-by-comment basis.
1754+
1755+
For more information, see the cookbook article: :doc:`/cookbook/security/acl`.
1756+
17141757
Logging Out
17151758
-----------
17161759

@@ -1822,57 +1865,6 @@ is defined by the ``target`` parameter above (e.g. the ``homepage``). For
18221865
more information on configuring the logout, see the
18231866
:doc:`Security Configuration Reference </reference/configuration/security>`.
18241867

1825-
.. _book-security-template:
1826-
1827-
Access Control in Templates
1828-
---------------------------
1829-
1830-
If you want to check if the current user has a role inside a template, use
1831-
the built-in helper function:
1832-
1833-
.. configuration-block::
1834-
1835-
.. code-block:: html+jinja
1836-
1837-
{% if is_granted('ROLE_ADMIN') %}
1838-
<a href="...">Delete</a>
1839-
{% endif %}
1840-
1841-
.. code-block:: html+php
1842-
1843-
<?php if ($view['security']->isGranted('ROLE_ADMIN')): ?>
1844-
<a href="...">Delete</a>
1845-
<?php endif; ?>
1846-
1847-
.. note::
1848-
1849-
If you use this function and are *not* at a URL where there is a firewall
1850-
active, an exception will be thrown. Again, it's almost always a good
1851-
idea to have a main firewall that covers all URLs (as has been shown
1852-
in this chapter).
1853-
1854-
Access Control in Controllers
1855-
-----------------------------
1856-
1857-
If you want to check if the current user has a role in your controller, use
1858-
the :method:`Symfony\\Component\\Security\\Core\\SecurityContext::isGranted`
1859-
method of the security context::
1860-
1861-
public function indexAction()
1862-
{
1863-
// show different content to admin users
1864-
if ($this->get('security.context')->isGranted('ROLE_ADMIN')) {
1865-
// ... load admin content here
1866-
}
1867-
1868-
// ... load other regular content here
1869-
}
1870-
1871-
.. note::
1872-
1873-
A firewall must be active or an exception will be thrown when the ``isGranted``
1874-
method is called. See the note above about templates for more details.
1875-
18761868
Impersonating a User
18771869
--------------------
18781870

0 commit comments

Comments
 (0)