Skip to content

Commit 121196d

Browse files
marek-pietrzak-tgxabbuh
marek-pietrzak-tg
authored and
xabbuh
committed
[2.8] Add "How to Use Multiple Guard Authenticators" cookbook documentation
1 parent a447862 commit 121196d

File tree

3 files changed

+174
-0
lines changed

3 files changed

+174
-0
lines changed

‎cookbook/map.rst.inc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,7 @@
176176
* :doc:`/cookbook/security/csrf_in_login_form`
177177
* :doc:`/cookbook/security/named_encoders`
178178
* :doc:`/cookbook/security/multiple_user_providers`
179+
* :doc:`/cookbook/security/multiple_guard_authenticators`
179180
* :doc:`/cookbook/security/firewall_restriction`
180181
* :doc:`/cookbook/security/host_restriction`
181182
* :doc:`/cookbook/security/user_checkers`

‎cookbook/security/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ Authentication (Identifying/Logging in the User)
2222
csrf_in_login_form
2323
named_encoders
2424
multiple_user_providers
25+
multiple_guard_authenticators
2526
firewall_restriction
2627
host_restriction
2728
user_checkers

‎cookbook/security/multiple_guard_authenticators.rst

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
How to Use Multiple Guard Authenticators
2+
========================================
3+
4+
.. versionadded:: 2.8
5+
The ``Guard`` component was introduced in Symfony 2.8.
6+
7+
The Guard authentication component allows you to easily use many different
8+
authenticators at a time.
9+
10+
An entry point is a service id (of one of your authenticators) whose
11+
``start()`` method is called to start the authentication process.
12+
13+
Multiple Authenticators with Shared Entry Point
14+
-----------------------------------------------
15+
16+
Sometimes you want to offer your users different authentication mechanisms like
17+
a form login and a Facebook login while both entry points redirect the user to
18+
the same login page.
19+
However, in your configuration you have to explicitly say which entry point
20+
you want to use.
21+
22+
This is how your security configuration can look in action:
23+
24+
.. configuration-block::
25+
26+
.. code-block:: yaml
27+
28+
# app/config/security.yml
29+
security:
30+
# ...
31+
firewalls:
32+
default:
33+
anonymous: ~
34+
guard:
35+
authenticators:
36+
- app.form_login_authenticator
37+
- app.facebook_connect_authenticator
38+
entry_point: app.form_login_authenticator
39+
40+
.. code-block:: xml
41+
42+
<!-- app/config/security.xml -->
43+
<?xml version="1.0" encoding="UTF-8"?>
44+
<srv:container xmlns="http://symfony.com/schema/dic/security"
45+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
46+
xmlns:srv="http://symfony.com/schema/dic/services"
47+
xsi:schemaLocation="http://symfony.com/schema/dic/services
48+
http://symfony.com/schema/dic/services/services-1.0.xsd">
49+
50+
<config>
51+
<!-- ... -->
52+
<firewall name="default">
53+
<anonymous />
54+
<guard entry-point="app.form_login_authenticator">
55+
<authenticator>app.form_login_authenticator</authenticator>
56+
<authenticator>app.facebook_connect_authenticator</authenticator>
57+
</guard>
58+
</firewall>
59+
</config>
60+
</srv:container>
61+
62+
.. code-block:: php
63+
64+
// app/config/security.php
65+
$container->loadFromExtension('security', array(
66+
// ...
67+
'firewalls' => array(
68+
'default' => array(
69+
'anonymous' => null,
70+
'guard' => array(
71+
'entry_point' => 'app.form_login_authenticator',
72+
'authenticators' => array(
73+
'app.form_login_authenticator',
74+
'app.facebook_connect_authenticator'
75+
),
76+
),
77+
),
78+
),
79+
));
80+
81+
There is one limitation with this approach - you have to use exactly one entry point.
82+
83+
Multiple Authenticators with Separate Entry Points
84+
--------------------------------------------------
85+
86+
However, there are use cases where you have authenticators that protect different
87+
parts of your application. For example, you have a login form that protects
88+
the secured area of your application front-end and API end points that are
89+
protected with API tokens. As you can only configure one entry point per firewall,
90+
the solution is to split the configuration into two separate firewalls:
91+
92+
.. configuration-block::
93+
94+
.. code-block:: yaml
95+
96+
# app/config/security.yml
97+
security:
98+
# ...
99+
firewalls:
100+
api:
101+
pattern: ^/api/
102+
guard:
103+
authenticators:
104+
- app.api_token_authenticator
105+
default:
106+
anonymous: ~
107+
guard:
108+
authenticators:
109+
- app.form_login_authenticator
110+
access_control:
111+
- { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY }
112+
- { path: ^/api, roles: ROLE_API_USER }
113+
- { path: ^/, roles: ROLE_USER }
114+
115+
.. code-block:: xml
116+
117+
<!-- app/config/security.xml -->
118+
<?xml version="1.0" encoding="UTF-8"?>
119+
<srv:container xmlns="http://symfony.com/schema/dic/security"
120+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
121+
xmlns:srv="http://symfony.com/schema/dic/services"
122+
xsi:schemaLocation="http://symfony.com/schema/dic/services
123+
http://symfony.com/schema/dic/services/services-1.0.xsd">
124+
125+
<config>
126+
<!-- ... -->
127+
<firewall name="api" pattern="^/api/">
128+
<guard>
129+
<authenticator>app.api_token_authenticator</authenticator>
130+
</guard>
131+
</firewall>
132+
<firewall name="default">
133+
<anonymous />
134+
<guard>
135+
<authenticator>app.form_login_authenticator</authenticator>
136+
</guard>
137+
</firewall>
138+
<rule path="^/login" role="IS_AUTHENTICATED_ANONYMOUSLY" />
139+
<rule path="^/api" role="ROLE_API_USER" />
140+
<rule path="^/" role="ROLE_USER" />
141+
</config>
142+
</srv:container>
143+
144+
.. code-block:: php
145+
146+
// app/config/security.php
147+
$container->loadFromExtension('security', array(
148+
// ...
149+
'firewalls' => array(
150+
'api' => array(
151+
'pattern' => '^/api',
152+
'guard' => array(
153+
'authenticators' => array(
154+
'app.api_token_authenticator',
155+
),
156+
),
157+
),
158+
'default' => array(
159+
'anonymous' => null,
160+
'guard' => array(
161+
'authenticators' => array(
162+
'app.form_login_authenticator',
163+
),
164+
),
165+
),
166+
),
167+
'access_control' => array(
168+
array('path' => '^/login', 'role' => 'IS_AUTHENTICATED_ANONYMOUSLY'),
169+
array('path' => '^/api', 'role' => 'ROLE_API_USER'),
170+
array('path' => '^/', 'role' => 'ROLE_USER'),
171+
),
172+
));

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