Skip to content

Commit 9889dbe

Browse files
Daniel Tschinderweaverryan
Daniel Tschinder
authored and
weaverryan
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 3570711 commit 9889dbe

File tree

4 files changed

+201
-69
lines changed

4 files changed

+201
-69
lines changed

‎book/security.rst

Lines changed: 6 additions & 1 deletion
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

@@ -2135,7 +2140,7 @@ Learn more from the Cookbook
21352140
* :doc:`Blacklist users by IP address with a custom voter </cookbook/security/voters>`
21362141
* :doc:`Access Control Lists (ACLs) </cookbook/security/acl>`
21372142
* :doc:`/cookbook/security/remember_me`
2138-
* :doc:`How to Restrict Firewalls to a Specific Host </cookbook/security/host_restriction>`
2143+
* :doc:`How to Restrict Firewalls to a Specific Request </cookbook/security/firewall_restriction>`
21392144

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

‎cookbook/map.rst.inc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,7 @@
139139
* :doc:`/cookbook/security/acl`
140140
* :doc:`/cookbook/security/acl_advanced`
141141
* :doc:`/cookbook/security/force_https`
142-
* :doc:`/cookbook/security/host_restriction`
142+
* :doc:`/cookbook/security/firewall_restriction`
143143
* :doc:`/cookbook/security/form_login`
144144
* :doc:`/cookbook/security/securing_services`
145145
* :doc:`/cookbook/security/custom_provider`

‎cookbook/security/firewall_restriction.rst

Lines changed: 193 additions & 0 deletions
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

Lines changed: 1 addition & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,4 @@
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+
This entry has moved to ":doc:`/cookbook/security/firewall_restriction`".

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy