Skip to content

Commit bad8468

Browse files
marek-pietrzak-tgmarek-pietrzak-tg
committed
Add "How to Use Multiple Guard Authenticators" cookbook documentation
1 parent a447862 commit bad8468

File tree

3 files changed

+169
-0
lines changed

3 files changed

+169
-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: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
.. index::
2+
3+
How to Use Multiple Guard Authenticators
4+
========================================
5+
6+
Guard authentication component allows you to easily use many different authenticators at a time.
7+
8+
An entry point is a service id (of one of your authenticators) whose start()
9+
method should be called when an anonymous user hits a page that requires authentication.
10+
11+
Multiple authenticators with shared entry point
12+
-----------------------------------------------
13+
Let's have an example of two authenticators: one based on login form, another one on facebook login.
14+
Both authenticators entry points redirect user to the same login page.
15+
However, in your configuration you have to explicitly say which entry point you want to use.
16+
17+
This is how your security configuration can look in action:
18+
19+
.. configuration-block::
20+
21+
.. code-block:: yaml
22+
23+
# app/config/security.yml
24+
security:
25+
# ...
26+
firewalls:
27+
default:
28+
anonymous: ~
29+
guard:
30+
authenticators:
31+
- app.form_login_authenticator
32+
- app.facebook_connect_authenticator
33+
entry_point: app.form_login_authenticator
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="default">
48+
<anonymous />
49+
<guard entry_point="app.form_login_authenticator">
50+
<authenticator>app.form_login_authenticator</authenticator>
51+
<authenticator>app.facebook_connect_authenticator</authenticator>
52+
</guard>
53+
</firewall>
54+
</config>
55+
</srv:container>
56+
57+
.. code-block:: php
58+
59+
// app/config/security.php
60+
$container->loadFromExtension('security', array(
61+
// ...
62+
'firewalls' => array(
63+
'default' => array(
64+
'anonymous' => null,
65+
'guard' => array(
66+
'entry_point' => 'app.form_login_authenticator',
67+
'authenticators' => array(
68+
'app.form_login_authenticator',
69+
'app.facebook_connect_authenticator'
70+
),
71+
),
72+
),
73+
),
74+
));
75+
76+
There is one limitation with this approach - you have to use exactly one entry point.
77+
78+
Multiple authenticators with separate entry points
79+
--------------------------------------------------
80+
Let's now have an example of two different authenticators: one based on login form, another one on an API token.
81+
When user hits secured area he should be redirected to the login page.
82+
Also when user hits an API endpoint, he should get a relevant API response.
83+
84+
Solution for this use case is to provide guard authenticators in two separate firewalls.
85+
86+
This is an example of your configuration:
87+
88+
.. configuration-block::
89+
90+
.. code-block:: yaml
91+
92+
# app/config/security.yml
93+
security:
94+
# ...
95+
firewalls:
96+
api:
97+
pattern: ^/api/
98+
guard:
99+
authenticators:
100+
- app.api_token_authenticator
101+
default:
102+
anonymous: ~
103+
guard:
104+
authenticators:
105+
- app.form_login_authenticator
106+
access_control:
107+
- { path: ^/login, roles: IS_AUTHENTICATED_ANONYMOUSLY }
108+
- { path: ^/api, roles: ROLE_API_USER }
109+
- { path: ^/, roles: ROLE_ADMIN }
110+
111+
.. code-block:: xml
112+
113+
<!-- app/config/security.xml -->
114+
<?xml version="1.0" encoding="UTF-8"?>
115+
<srv:container xmlns="http://symfony.com/schema/dic/security"
116+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
117+
xmlns:srv="http://symfony.com/schema/dic/services"
118+
xsi:schemaLocation="http://symfony.com/schema/dic/services
119+
http://symfony.com/schema/dic/services/services-1.0.xsd">
120+
121+
<config>
122+
<!-- ... -->
123+
<firewall name="api" pattern="^/api/">
124+
<guard>
125+
<authenticator>app.api_token_authenticator</authenticator>
126+
</guard>
127+
</firewall>
128+
<firewall name="default">
129+
<anonymous />
130+
<guard>
131+
<authenticator>app.form_login_authenticator</authenticator>
132+
</guard>
133+
</firewall>
134+
<rule path="^/login" role="IS_AUTHENTICATED_ANONYMOUSLY" />
135+
<rule path="^/api" role="ROLE_API_USER" />
136+
<rule path="^/" role="ROLE_ADMIN" />
137+
</config>
138+
</srv:container>
139+
140+
.. code-block:: php
141+
142+
// app/config/security.php
143+
$container->loadFromExtension('security', array(
144+
// ...
145+
'firewalls' => array(
146+
'api' => array(
147+
'guard' => array(
148+
'authenticators' => array(
149+
'app.api_token_authenticator',
150+
),
151+
),
152+
),
153+
'default' => array(
154+
'anonymous' => null,
155+
'guard' => array(
156+
'authenticators' => array(
157+
'app.form_login_authenticator',
158+
),
159+
),
160+
),
161+
),
162+
'access_control' => array(
163+
array('path' => '^/login', 'role' => 'IS_AUTHENTICATED_ANONYMOUSLY'),
164+
array('path' => '^/api', 'role' => 'ROLE_API_USER'),
165+
array('path' => '^/', 'role' => 'ROLE_ADMIN'),
166+
),
167+
));

0 commit comments

Comments
 (0)