Skip to content

Commit 2a85e4f

Browse files
author
Iltar van der Berg
committed
Added user_checkers.rst
1 parent 25fe737 commit 2a85e4f

File tree

2 files changed

+219
-0
lines changed

2 files changed

+219
-0
lines changed

‎cookbook/security/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Authentication (Identifying/Logging in the User)
2323
multiple_user_providers
2424
firewall_restriction
2525
host_restriction
26+
user_checkers
2627

2728
Authorization (Denying Access)
2829
------------------------------

‎cookbook/security/user_checkers.rst

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
.. index::
2+
single: Security; Creating and Enabling Custom User Checkers
3+
4+
How to Create and Enable Custom User Checkers
5+
=============================================
6+
7+
During the authentication of a user, additional checks might be required to verify
8+
if the identified user is allowed to log in. By defining custom user checkers, you
9+
can define per firewall which checkers should be used.
10+
11+
.. versionadded:: 2.8
12+
Adding custom user checkers was introduced in Symfony 2.8.
13+
14+
15+
Creating a Custom User Checker
16+
------------------------------
17+
18+
User checkers are defined in PHP classes that must implement the
19+
:class:`UserCheckerInterface Symfony\\Component\\Security\\Core\\UserCheckerInterface`.
20+
This interface defines two methods called ``checkPreAuth()`` and ``checkPostAuth()``
21+
to perform checks before and after user authentication. If one or more
22+
conditions are not met, an exception should be thrown which extends the
23+
:class:`AccountStatusException Symfony\\Component\\Security\\Core\\Exception\\AccountStatusException`
24+
25+
.. code-block:: php
26+
27+
namespace App\Security;
28+
29+
use Symfony\Component\Security\Core\User\UserCheckInterface;
30+
31+
class UserChecker implements UserCheckerInterface
32+
{
33+
public function checkPreAuth(UserInterface $user)
34+
{
35+
if (!$user instanceof AppUser) {
36+
return;
37+
}
38+
39+
// user is deleted, show a generic Account Not Found message.
40+
if ($user->isDeleted()) {
41+
throw new AccountDeletedException('...');
42+
}
43+
}
44+
45+
public function checkPostAuth(UserInterface $user)
46+
{
47+
if (!$user instanceof AppUser) {
48+
return;
49+
}
50+
51+
// user account is expired, the user may be notified
52+
if ($user->isExpired()) {
53+
throw new AccountExpiredException('...');
54+
}
55+
}
56+
}
57+
58+
Enabling the Custom User Checker
59+
--------------------------------
60+
61+
All that's left to be done is creating a service definition and configuring
62+
this in the firewall configuration. Configuring the service is done like any
63+
other service:
64+
65+
.. configuration-block::
66+
67+
.. code-block:: yaml
68+
69+
# app/config/services.yml
70+
services:
71+
app.user_checker:
72+
class: App\Security\UserChecker
73+
74+
.. code-block:: xml
75+
76+
<!-- app/config/services.xml -->
77+
<?xml version="1.0" encoding="UTF-8" ?>
78+
<container xmlns="http://symfony.com/schema/dic/services"
79+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
80+
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
81+
82+
<services>
83+
<service id="app.user_checker" class="App\Security\UserChecker">
84+
</service>
85+
</services>
86+
</container>
87+
88+
.. code-block:: php
89+
90+
// app/config/services.php
91+
use Symfony\Component\DependencyInjection\Definition;
92+
93+
$userChecker = new Definition('App\Security\UserChecker');
94+
$container->setDefinition('app.user_checker', $userChecker);
95+
96+
All that's left to do is add the checker to the desired firewall where the value
97+
is the service id of your user checker:
98+
99+
.. configuration-block::
100+
101+
.. code-block:: yaml
102+
103+
# app/config/security.yml
104+
105+
# ...
106+
security:
107+
firewalls:
108+
secured_area:
109+
pattern: ^/
110+
user_checkers: ["app.user_checker"]
111+
# ...
112+
113+
.. code-block:: xml
114+
115+
<!-- app/config/security.xml -->
116+
<?xml version="1.0" encoding="UTF-8"?>
117+
<srv:container xmlns="http://symfony.com/schema/dic/security"
118+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
119+
xmlns:srv="http://symfony.com/schema/dic/services"
120+
xsi:schemaLocation="http://symfony.com/schema/dic/services
121+
http://symfony.com/schema/dic/services/services-1.0.xsd">
122+
123+
<config>
124+
<!-- ... -->
125+
<firewall name="secured_area" pattern="^/">
126+
<user-checkers>app.user_checker</user-checkers>
127+
<!-- ... -->
128+
</firewall>
129+
</config>
130+
</srv:container>
131+
132+
.. code-block:: php
133+
134+
// app/config/security.php
135+
136+
// ...
137+
$container->loadFromExtension('security', array(
138+
'firewalls' => array(
139+
'secured_area' => array(
140+
'pattern' => '^/',
141+
'user_checkers' => array('app.user_checker'),
142+
// ...
143+
),
144+
),
145+
));
146+
147+
148+
Additional Configurations
149+
-------------------------
150+
151+
It's possible to add multiple user checkers to one firewall while
152+
configuring only one user checker for another firewall. When adding
153+
multiple user checkers, they are executed in the same sequence as
154+
defined in your configuration.
155+
156+
.. configuration-block::
157+
158+
.. code-block:: yaml
159+
160+
# app/config/security.yml
161+
162+
# ...
163+
security:
164+
firewalls:
165+
admin:
166+
pattern: ^/admin
167+
user_checkers: ["app.user_checker", "app.admin_checker"]
168+
# ...
169+
secured_area:
170+
pattern: ^/
171+
user_checkers: ["app.user_checker"]
172+
173+
.. code-block:: xml
174+
175+
<!-- app/config/security.xml -->
176+
<?xml version="1.0" encoding="UTF-8"?>
177+
<srv:container xmlns="http://symfony.com/schema/dic/security"
178+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
179+
xmlns:srv="http://symfony.com/schema/dic/services"
180+
xsi:schemaLocation="http://symfony.com/schema/dic/services
181+
http://symfony.com/schema/dic/services/services-1.0.xsd">
182+
183+
<config>
184+
<!-- ... -->
185+
<firewall name="admin" pattern="^/admin">
186+
<user-checkers>app.user_checker</user-checkers>
187+
<user-checkers>app.admin_checker</user-checkers>
188+
<!-- ... -->
189+
</firewall>
190+
<firewall name="secured_area" pattern="^/">
191+
<user-checkers>app.user_checker</user-checkers>
192+
<!-- ... -->
193+
</firewall>
194+
</config>
195+
</srv:container>
196+
197+
.. code-block:: php
198+
199+
// app/config/security.php
200+
201+
// ...
202+
$container->loadFromExtension('security', array(
203+
'firewalls' => array(
204+
'admin' => array(
205+
'pattern' => '^/admin',
206+
'user_checkers' => array(
207+
'app.user_checker',
208+
'app.admin_checker',
209+
),
210+
// ...
211+
),
212+
'secured_area' => array(
213+
'pattern' => '^/',
214+
'user_checkers' => array('app.user_checker'),
215+
// ...
216+
),
217+
),
218+
));

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