8000 minor #3695 Firewall backport (weaverryan) · symfony/symfony-docs@0a21718 · GitHub
[go: up one dir, main page]
Skip to content

Commit 0a21718

Browse files
weaverryanweaverryan
committed
minor #3695 Firewall backport (weaverryan)
This PR was merged into the 2.4 branch. Discussion ---------- Firewall backport This backports the changes from #3681 with the 2.4-only changes. After this is merged, we'll need to merge this into master (like normal). At that time, the 2.5-specific changes from the `firewall_restriction` and firewall configuration need to be added back. | Q | A | ------------- | --- | Doc fix? | yes | New docs? | no | Applies to | 2.4 | Fixed tickets | n/a Thanks! Commits ------- be46c76 After backporting something from master (2.5), removing the 2.5-specific features 9889dbe Enhanced Firewall Restrictions docs
2 parents dbaef06 + be46c76 commit 0a21718

File tree

4 files changed

+141
-69
lines changed

4 files changed

+141
-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).
187+
For more 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
@@ -140,7 +140,7 @@
140140
* :doc:`/cookbook/security/acl`
141141
* :doc:`/cookbook/security/acl_advanced`
142142
* :doc:`/cookbook/security/force_https`
143-
* :doc:`/cookbook/security/host_restriction`
143+
* :doc:`/cookbook/security/firewall_restriction`
144144
* :doc:`/cookbook/security/form_login`
145145
* :doc:`/cookbook/security/securing_services`
146146
* :doc:`/cookbook/security/custom_provider`

‎cookbook/security/firewall_restriction.rst

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
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.

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