diff --git a/cookbook/security/index.rst b/cookbook/security/index.rst
index c9a478c927a..3efdd455016 100644
--- a/cookbook/security/index.rst
+++ b/cookbook/security/index.rst
@@ -23,6 +23,7 @@ Authentication (Identifying/Logging in the User)
multiple_user_providers
firewall_restriction
host_restriction
+ user_checkers
Authorization (Denying Access)
------------------------------
diff --git a/cookbook/security/user_checkers.rst b/cookbook/security/user_checkers.rst
new file mode 100644
index 00000000000..e44d0b7c9f5
--- /dev/null
+++ b/cookbook/security/user_checkers.rst
@@ -0,0 +1,221 @@
+.. index::
+single: Security; Creating and Enabling Custom User Checkers
+
+How to Create and Enable Custom User Checkers
+=============================================
+
+During the authentication of a user, additional checks might be required to verify
+if the identified user is allowed to log in. By defining custom user checkers, you
+can define per firewall which checkers should be used.
+
+.. versionadded:: 2.8
+Adding custom user checkers was introduced in Symfony 2.8.
+
+
+Creating a Custom User Checker
+------------------------------
+
+Symfony provides an interface that enables you to implement a custom user checker
+:class:`UserCheckerInterface Symfony\\Component\\Security\\Core\\UserCheckerInterface`,
+this interface is required. If one or more conditions are not met, an exception should
+be throw which extends the
+:class:`AccountStatusException Symfony\\Component\\Security\\Core\\Exception\\AccountStatusException`
+
+.. code-block:: php
+
+ namespace App\Security;
+
+ use Symfony\Component\Security\Core\User\UserCheckInterface;
+
+ class UserChecker implements UserCheckerInterface
+ {
+ public function checkPreAuth(UserInterface $user)
+ {
+ if (!$user instanceof AppUser) {
+ return;
+ }
+
+ // user is deleted, show a generic Account Not Found message.
+ if ($user->isDeleted()) {
+ throw new AccountDeletedException('...');
+ }
+ }
+
+ public function checkPostAuth(UserInterface $user)
+ {
+ if (!$user instanceof AppUser) {
+ return;
+ }
+
+ // user account is expired, the user may be notified
+ if ($user->isExpired()) {
+ throw new AccountExpiredException('...');
+ }
+ }
+ }
+
+Enabling the Custom User Checker
+--------------------------------
+
+All that's left to be done is creating a service definition and configuring
+this in the firewall configuration. Configuring the service is done like any
+other service:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/services.yml
+ services:
+ app.user_checker:
+ class: App\Security\UserChecker
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/services.php
+ use Symfony\Component\DependencyInjection\Definition;
+
+ $userChecker = new Definition('App\Security\UserChecker');
+ $container->setDefinition('app.user_checker', $userChecker);
+
+All that's left to do is add the checker to the desired firewall where the value
+is the service id of your user checker:
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/security.yml
+
+ # ...
+ security:
+ firewalls:
+ secured_area:
+ pattern: ^/
+ user_checkers:
+ - "app.user_checker"
+ # ...
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+ app.user_checker
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/security.php
+
+ // ...
+ $container->loadFromExtension('security', array(
+ 'firewalls' => array(
+ 'secured_area' => array(
+ 'pattern' => '^/',
+ 'user_checkers' => array('app.user_checker'),
+ // ...
+ ),
+ ),
+ ));
+
+
+Additional Configurations
+-------------------------
+
+It's possible to add multiple user checkers to one firewall while
+configuring only one user checker for another firewall. When adding
+multiple user checkers, they are executed in the same sequence as
+defined in your configuration.
+
+.. configuration-block::
+
+ .. code-block:: yaml
+
+ # app/config/security.yml
+
+ # ...
+ security:
+ firewalls:
+ admin:
+ pattern: ^/admin
+ user_checkers:
+ - "app.user_checker"
+ - "app.admin_checker"
+ # ...
+ secured_area:
+ pattern: ^/
+ user_checkers:
+ - "app.user_checker"
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+
+ app.user_checker
+ app.admin_checker
+
+
+
+ app.user_checker
+
+
+
+
+
+ .. code-block:: php
+
+ // app/config/security.php
+
+ // ...
+ $container->loadFromExtension('security', array(
+ 'firewalls' => array(
+ 'admin' => array(
+ 'pattern' => '^/admin',
+ 'user_checkers' => array(
+ 'app.user_checker',
+ 'app.admin_checker',
+ ),
+ // ...
+ ),
+ 'secured_area' => array(
+ 'pattern' => '^/',
+ 'user_checkers' => array('app.user_checker'),
+ // ...
+ ),
+ ),
+ ));