diff --git a/components/security/authentication.rst b/components/security/authentication.rst index 00425a5d8f3..f720878a737 100644 --- a/components/security/authentication.rst +++ b/components/security/authentication.rst @@ -267,5 +267,53 @@ in) is correct, you can use:: $user->getSalt() ); +Events +------ + +The security component provides 4 related events: + +=============================== ================================================ ========================================================================= +Name Event Constant Argument Passed to the Listener +=============================== ================================================ ========================================================================= +security.authentication.success ``AuthenticationEvents::AUTHENTICATION_SUCCESS`` :class:`Symfony\Component\Security\Core\Event\AuthenticationEvent` +security.authentication.failure ``AuthenticationEvents::AUTHENTICATION_FAILURE`` :class:`Symfony\Component\Security\Core\Event\AuthenticationFailureEvent` +security.interactive_login ``SecurityEvents::INTERACTIVE_LOGIN`` :class:`Symfony\Component\Security\Http\Event\InteractiveLoginEvent` +security.switch_user ``SecurityEvents::SWITCH_USER`` :class:`Symfony\Component\Security\Http\Event\SwitchUserEvent` +=============================== ================================================ ========================================================================= + +Authentication Events +~~~~~~~~~~~~~~~~~~~~~ + +When a provider authenticates the user, a ``security.authentication.success`` +event is dispatched. Likewise, when no providers authenticate the user, +a ``security.authentication.failure`` event is dispatched. You +could listen on the ``security.authentication.failure`` event, for example, +in order to log failed login attempts. + +It is important to remember that one authentication event is always triggered +when a request points to a secured area. + +Security Events +~~~~~~~~~~~~~~~ + +The ``security.interactive_login`` event is triggered after a user has actively +logged into your website. It is important to distinguish this action from +non-interactive authentication methods, such as: + +* authentication based on a "remember me" cookie. +* authentication based on your session. +* authentication using a HTTP basic or HTTP digest header. + +You could listen on the ``security.interactive_login`` event, for example, in +order to give your user a welcome flash message every time they log in. + +The ``security.switch_user`` event is triggered every time you activate +the ``switch_user`` firewall listener. + +.. seealso:: + + For more information on switching users, see + :doc:`/cookbook/security/impersonating_user`. + .. _`CVE-2013-5750`: http://symfony.com/blog/cve-2013-5750-security-issue-in-fosuserbundle-login-form .. _`BasePasswordEncoder::checkPasswordLength`: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Security/Core/Encoder/BasePasswordEncoder.php