[WIP] 4373 - document security events

components/security/authentication.rst

@@ -267,5 +267,51 @@ in) is correct, you can use::
         $user->getSalt()
     );
 
+Authentication Events
+---------------------
+
+The security component provides 4 related authentication 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 Success and Failure Events
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a provider authenticates the user, a ``security.authentication.success``
+event is dispatched.  Likewise, when a provider attempts authentication but
+fails (i.e. throws an ``AuthenticationException``), 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.
+
+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