Skip to content

Commit f0c0fac

Browse files
xabbuhxabbuh
committed
feature symfony#5886 [2.8] Add "How to Use Multiple Guard Authenticators" cookbook documentation (mheki)
This PR was squashed before being merged into the 2.8 branch (closes symfony#5886). Discussion ---------- [2.8] Add "How to Use Multiple Guard Authenticators" cookbook documentation | Q | A | ------------- | --- | Doc fix? | no | New docs? | yes (symfony/symfony#14673) | Applies to | `2.8` onwards Hi guys, this is my first contribution to the symfony docs. During my preparations for the Symfony Guard component workshops I have spent some time trying to figure out the problem described here. I hope this cookbook entry will help others save their time. cc @weaverryan Thanks! Commits ------- 121196d [2.8] Add "How to Use Multiple Guard Authenticators" cookbook documentation
2 parents a447862 + 121196d commit f0c0fac

File tree

3 files changed

+174
-0
lines changed

3 files changed

+174
-0
lines changed

Diff for: ‎cookbook/map.rst.inc

+1
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`

Diff for: ‎cookbook/security/index.rst

+1
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

Diff for: ‎cookbook/security/multiple_guard_authenticators.rst

+172
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)