feature #5303 [WIP] 4373 - document security events (kevintweber)

This PR was merged into the 2.3 branch.

Discussion
----------

[WIP] 4373 - document security events

This is documentation for #4373.  This pull request has two parts:
* The component/security/authentication additions
* The new cookbook security cookbook page.

The new cookbook page is designed to give an example of how to use authentication events in an application.  I have given example code for two of the four classes needed to throttle failed login attempts.  The other two classes are a doctrine entity, and a class containing throttle domain logic, both of which are outside the scope of this documentation.

I would welcome any comments and suggestions.  Thank you.

Commits
-------

0dbabfe Security - Cookbook - removed bad example.
69c0089 Merge branch '4373_Document_Security_Events' of github.com:kevintweber/symfony-docs into 4373_Document_Security_Events
a14bd07 Security - Authentication - removed inaccurate tip.
f15bea4 Added new cookbook page to security index.
5bdfd71 Better formatting for authentication tip.
9b2e9d8 Better section titles for security events on authentication page.
286f00c Added security event descriptions to security component authentication page.

Author: weaverryan

components/security/authentication.rst

@@ -268,5 +268,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`: https://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