Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 450146e

Browse filesBrowse files
weaverryanweaverryan
committed
feature #3681 Enhanced Firewall Restrictions docs (danez)
This PR was merged into the master branch. Discussion ---------- Enhanced Firewall Restrictions docs see symfony/symfony#10404 And as I'm not native english, someone please read my changes :) Commits ------- eafbab1 Enhanced Firewall Restrictions docs
2 parents 2f3f88b + eafbab1 commit 450146e
Copy full SHA for 450146e

File tree

Expand file treeCollapse file tree

5 files changed

+209
-69
lines changed
Filter options
Expand file treeCollapse file tree

5 files changed

+209
-69
lines changed

‎book/security.rst

Copy file name to clipboardExpand all lines: book/security.rst
+6-1Lines 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

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

Copy file name to clipboardExpand all lines: cookbook/map.rst.inc
+1-1Lines 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

Copy file name to clipboard
+193Lines 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

Copy file name to clipboard
+3-67Lines changed: 3 additions & 67 deletions
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

Copy file name to clipboardExpand all lines: reference/configuration/security.rst
+6Lines changed: 6 additions & 0 deletions
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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.