Skip to content

Commit eafbab1

Browse files
author
Daniel Tschinder
committed
Enhanced Firewall Restrictions docs
Squashed commits: [2081fc4] Enhanced Firewall Restrictions docs for PR symfony/symfony#10404 [8f065bc] Add redirect to new page [b42e80f] fixed typos [cc6b07d] tiny update
1 parent 739f43f commit eafbab1

File tree

5 files changed

+209
-69
lines changed

5 files changed

+209
-69
lines changed

‎book/security.rst

+6-1
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,11 @@ 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+
.. tip::
185+
186+
You can also match a request against other details of the request (e.g. host, method). For more
187+
information and examples read :doc:`/cookbook/security/firewall_restriction`.
188+
184189
.. image:: /images/book/security_anonymous_user_access.png
185190
:align: center
186191

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

21442149
.. _`FOSUserBundle`: https://github.com./FriendsOfSymfony/FOSUserBundle
21452150
.. _`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

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

‎cookbook/security/host_restriction.rst

+3-67
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,6 @@
1-
.. index::
2-
single: Security; Restrict Security Firewalls to a Host
3-
41
How to Restrict Firewalls to a Specific Host
52
============================================
63

7-
.. versionadded:: 2.4
8-
Support for restricting security firewalls to a specific host was introduced in
9-
Symfony 2.4.
10-
11-
When using the Security component, you can create firewalls that match certain
12-
URL patterns and therefore are activated for all pages whose URL matches
13-
that pattern. Additionally, you can restrict the initialization of a firewall
14-
to a host using the ``host`` key:
15-
16-
.. configuration-block::
17-
18-
.. code-block:: yaml
19-
20-
# app/config/security.yml
21-
22-
# ...
23-
24-
security:
25-
firewalls:
26-
secured_area:
27-
pattern: ^/
28-
host: ^admin\.example\.com$
29-
http_basic: true
30-
31-
.. code-block:: xml
32-
33-
<!-- app/config/security.xml -->
34-
<?xml version="1.0" encoding="UTF-8"?>
35-
<srv:container xmlns="http://symfony.com/schema/dic/security"
36-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
37-
xmlns:srv="http://symfony.com/schema/dic/services"
38-
xsi:schemaLocation="http://symfony.com/schema/dic/services
39-
http://symfony.com/schema/dic/services/services-1.0.xsd">
40-
41-
<config>
42-
<!-- ... -->
43-
<firewall name="secured_area" pattern="^/" host="^admin\.example\.com$">
44-
<http-basic />
45-
</firewall>
46-
</config>
47-
</srv:container>
48-
49-
.. code-block:: php
50-
51-
// app/config/security.php
52-
53-
// ...
54-
55-
$container->loadFromExtension('security', array(
56-
'firewalls' => array(
57-
'secured_area' => array(
58-
'pattern' => '^/',
59-
'host' => '^admin\.example\.com$',
60-
'http_basic' => true,
61-
),
62-
),
63-
));
64-
65-
The ``host`` (like the ``pattern``) is a regular expression. In this example,
66-
the firewall will only be activated if the host is equal exactly (due to
67-
the ``^`` and ``$`` regex characters) to the hostname ``admin.example.com``.
68-
If the hostname does not match this pattern, the firewall will not be activated
69-
and subsequent firewalls will have the opportunity to be matched for this
70-
request.
4+
As of Symfony 2.5, more possibilities to restrict firewalls have been added.
5+
You can read everything about all the possibilities (including ``host``)
6+
in ":doc:`/cookbook/security/firewall_restriction`".

‎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)