Skip to content

Commit 2081fc4

Browse files
author
Daniel Tschinder
committed
Enhanced Firewall Restrictions docs for PR symfony/symfony#10404 
1 parent 739f43f commit 2081fc4

File tree

5 files changed

+213
-72
lines changed

5 files changed

+213
-72
lines changed

‎book/security.rst

+7-1
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,12 @@ firewall is activated does *not* mean, however, that the HTTP authentication
181181
username and password box is displayed for every URL. For example, any user
182182
can access ``/foo`` without being prompted to authenticate.
183183

184+
.. note::
185+
186+
You can also match a request against other options of the request and
187+
not only the URL. For more information and examples read
188+
:doc:`/cookbook/security/firewall_restriction`.
189+
184190
.. image:: /images/book/security_anonymous_user_access.png
185191
:align: center
186192

@@ -2139,7 +2145,7 @@ Learn more from the Cookbook
21392145
* :doc:`Blacklist users by IP address with a custom voter </cookbook/security/voters>`
21402146
* :doc:`Access Control Lists (ACLs) </cookbook/security/acl>`
21412147
* :doc:`/cookbook/security/remember_me`
2142-
* :doc:`How to Restrict Firewalls to a Specific Host </cookbook/security/host_restriction>`
2148+
* :doc:`How to Restrict Firewalls to a Specific Request </cookbook/security/firewall_restriction>`
21432149

21442150
.. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle
21452151
.. _`implement the \Serializable interface`: http://php.net/manual/en/class.serializable.php

‎cookbook/map.rst.inc

+1-1
Original file line numberDiff line numberDiff line change
@@ -138,7 +138,7 @@
138138
* :doc:`/cookbook/security/acl`
139139
* :doc:`/cookbook/security/acl_advanced`
140140
* :doc:`/cookbook/security/force_https`
141-
* :doc:`/cookbook/security/host_restriction`
141+
* :doc:`/cookbook/security/firewall_restriction`
142142
* :doc:`/cookbook/security/form_login`
143143
* :doc:`/cookbook/security/securing_services`
144144
* :doc:`/cookbook/security/custom_provider`

‎cookbook/security/firewall_restriction.rst

+199
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
.. index::
2+
single: Security; Restrict Security Firewalls to a Request
3+
4+
How to Restrict Firewalls to a Specific Request
5+
===============================================
6+
7+
When using the Security component, you can create firewalls that match certain request options.
8+
In most cases matching against the URL is sufficient but in special cases you can further
9+
restrict the initialization of a firewall against other options from the request.
10+
11+
.. note::
12+
13+
You can use any of this restrictions individually or mix them together to get
14+
your desired firewall configuration.
15+
16+
Restricting by pattern
17+
----------------------
18+
19+
This is the default restriction and restricts a firewall to only be initialized if the request URL
20+
matches the configured ``pattern``.
21+
22+
.. configuration-block::
23+
24+
.. code-block:: yaml
25+
26+
# app/config/security.yml
27+
28+
# ...
29+
30+
security:
31+
firewalls:
32+
secured_area:
33+
pattern: ^/admin
34+
# ...
35+
36+
.. code-block:: xml
37+
38+
<!-- app/config/security.xml -->
39+
<?xml version="1.0" encoding="UTF-8"?>
40+
<srv:container xmlns="http://symfony.com/schema/dic/security"
41+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
42+
xmlns:srv="http://symfony.com/schema/dic/services"
43+
xsi:schemaLocation="http://symfony.com/schema/dic/services
44+
http://symfony.com/schema/dic/services/services-1.0.xsd">
45+
46+
<config>
47+
<!-- ... -->
48+
<firewall name="secured_area" pattern="^/admin">
49+
<!-- ... -->
50+
</firewall>
51+
</config>
52+
</srv:container>
53+
54+
.. code-block:: php
55+
56+
// app/config/security.php
57+
58+
// ...
59+
60+
$container->loadFromExtension('security', array(
61+
'firewalls' => array(
62+
'secured_area' => array(
63+
'pattern' => '^/admin',
64+
// ...
65+
),
66+
),
67+
));
68+
69+
The ``pattern`` is a regular expression. In this example, the firewall will only be
70+
activated if the URL starts (due to the ``^`` regex character) with ``/admin`. If
71+
the URL does not match this pattern, the firewall will not be activated and subsequent
72+
firewalls will have the opportunity to be matched for this request.
73+
74+
Restricting by host
75+
-------------------
76+
77+
.. versionadded:: 2.4
78+
Support for restricting security firewalls to a specific host was introduced in
79+
Symfony 2.4.
80+
81+
If matching against the pattern only is not enough, the request can also be matched against
82+
``host``. When the configuration option ``host`` is set the firewall will be restricted to
83+
only initialize if the host from the request matches against the configuration option.
84+
85+
.. configuration-block::
86+
87+
.. code-block:: yaml
88+
89+
# app/config/security.yml
90+
91+
# ...
92+
93+
security:
94+
firewalls:
95+
secured_area:
96+
host: ^admin\.example\.com$
97+
# ...
98+
99+
.. code-block:: xml
100+
101+
<!-- app/config/security.xml -->
102+
<?xml version="1.0" encoding="UTF-8"?>
103+
<srv:container xmlns="http://symfony.com/schema/dic/security"
104+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
105+
xmlns:srv="http://symfony.com/schema/dic/services"
106+
xsi:schemaLocation="http://symfony.com/schema/dic/services
107+
http://symfony.com/schema/dic/services/services-1.0.xsd">
108+
109+
<config>
110+
<!-- ... -->
111+
<firewall name="secured_area" host="^admin\.example\.com$">
112+
<!-- ... -->
113+
</firewall>
114+
</config>
115+
</srv:container>
116+
117+
.. code-block:: php
118+
119+
// app/config/security.php
120+
121+
// ...
122+
123+
$container->loadFromExtension('security', array(
124+
'firewalls' => array(
125+
'secured_area' => array(
126+
'host' => '^admin\.example\.com$',
127+
// ...
128+
),
129+
),
130+
));
131+
132+
The ``host`` (like the ``pattern``) is a regular expression. In this example,
133+
the firewall will only be activated if the host is equal exactly (due to
134+
the ``^`` and ``$`` regex characters) to the hostname ``admin.example.com``.
135+
If the hostname does not match this pattern, the firewall will not be activated
136+
and subsequent firewalls will have the opportunity to be matched for this
137+
request.
138+
139+
Restricting by http methods
140+
---------------------------
141+
142+
.. versionadded:: 2.5
143+
Support for restricting security firewalls to specific http methods was introduced in
144+
Symfony 2.5.
145+
146+
The configuration option ``methods`` restricts the initialization of the firewall to
147+
the provided http methods.
148+
149+
.. configuration-block::
150+
151+
.. code-block:: yaml
152+
153+
# app/config/security.yml
154+
155+
# ...
156+
157+
security:
158+
firewalls:
159+
secured_area:
160+
methods: [GET, POST]
161+
# ...
162+
163+
.. code-block:: xml
164+
165+
<!-- app/config/security.xml -->
166+
<?xml version="1.0" encoding="UTF-8"?>
167+
<srv:container xmlns="http://symfony.com/schema/dic/security"
168+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
169+
xmlns:srv="http://symfony.com/schema/dic/services"
170+
xsi:schemaLocation="http://symfony.com/schema/dic/services
171+
http://symfony.com/schema/dic/services/services-1.0.xsd">
172+
173+
<config>
174+
<!-- ... -->
175+
<firewall name="secured_area" methods="GET,POST">
176+
<!-- ... -->
177+
</firewall>
178+
</config>
179+
</srv:container>
180+
181+
.. code-block:: php
182+
183+
// app/config/security.php
184+
185+
// ...
186+
187+
$container->loadFromExtension('security', array(
188+
'firewalls' => array(
189+
'secured_area' => array(
190+
'methods' => array('GET', 'POST'),
191+
// ...
192+
),
193+
),
194+
));
195+
196+
In this example, the firewall will only be activated if the http method of the
197+
request is either ``GET`` or ``POST``. If the method is not in the array of the
198+
allowed methods, the firewall will not be activated and subsequent firewalls will again
199+
have the opportunity to be matched for this request.

‎cookbook/security/host_restriction.rst

-70
This file was deleted.

‎reference/configuration/security.rst

+6
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ Each part will be explained in the next section.
1717
Support for restricting security firewalls to a specific host was introduced in
1818
Symfony 2.4.
1919

20+
.. versionadded:: 2.5
21+
Support for restricting security firewalls to specific http methods was introduced in
22+
Symfony 2.5.
23+
2024
.. configuration-block::
2125

2226
.. code-block:: yaml
@@ -104,6 +108,8 @@ Each part will be explained in the next section.
104108
pattern: .*
105109
# restrict the firewall to a specific host
106110
host: admin\.example\.com
111+
# restrict the firewall to specific http methods
112+
methods: [GET,POST]
107113
request_matcher: some.service.id
108114
access_denied_url: /foo/error403
109115
access_denied_handler: some.service.id

0 commit comments

Comments
 (0)