From 8bb5331828c4c419bbf1ab3ebb5ed174773506da Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 9 May 2016 15:58:58 +0200 Subject: [PATCH 1/6] Added the documentation for the success/failure handlers --- cookbook/map.rst.inc | 1 + cookbook/security/index.rst | 1 + cookbook/security/login_handlers.rst | 89 ++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+) create mode 100644 cookbook/security/login_handlers.rst diff --git a/cookbook/map.rst.inc b/cookbook/map.rst.inc index 65276f9a4a5..fd6264da7af 100644 --- a/cookbook/map.rst.inc +++ b/cookbook/map.rst.inc @@ -167,6 +167,7 @@ * :doc:`/cookbook/security/remember_me` * :doc:`/cookbook/security/impersonating_user` * :doc:`/cookbook/security/form_login` + * :doc:`/cookbook/security/login_handlers` * :doc:`/cookbook/security/custom_provider` * :doc:`/cookbook/security/custom_password_authenticator` * :doc:`/cookbook/security/api_key_authentication` diff --git a/cookbook/security/index.rst b/cookbook/security/index.rst index c9a478c927a..a3d9be614d3 100644 --- a/cookbook/security/index.rst +++ b/cookbook/security/index.rst @@ -12,6 +12,7 @@ Authentication (Identifying/Logging in the User) remember_me impersonating_user form_login + login_handlers custom_provider custom_password_authenticator api_key_authentication diff --git a/cookbook/security/login_handlers.rst b/cookbook/security/login_handlers.rst new file mode 100644 index 00000000000..a70a3a4e243 --- /dev/null +++ b/cookbook/security/login_handlers.rst @@ -0,0 +1,89 @@ +.. index:: + single: Security; Login + single: Security; Logout + single: Security; Handler + +How to Customize the Success and Failure Login Handlers +======================================================= + +After the users successfully log in in your application, they are redirected to +the proper URL according to the security configuration options. This is done in +the :class:`Symfony\\Component\\Security\\Http\\Authentication\\DefaultAuthenticationSuccessHandler` +class and Symfony defines a similar class called ``DefaultAuthenticationFailureHandler`` +to handle the login failures. + +This article explains **how to define your own login handlers** to execute +custom logic after the user has logged in successfully or failed to do that. + +Creating a Success Login Handler +-------------------------------- + +First, create a class that implements :class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationSuccessHandlerInterface` +and add your own logic:: + + namespace AppBundle\Security; + + use Symfony\Component\HttpFoundation\RedirectResponse; + use Symfony\Component\Security\Http\Authentication\AuthenticationSuccessHandlerInterface; + + class SuccesfulLoginHandler implements AuthenticationSuccessHandlerInterface + { + public function onAuthenticationSuccess(Request $request, TokenInterface $token) + { + // do something... + + // you can inherit from the DefaultAuthenticationSuccessHandler + // class to reuse the logic that decides the URL to redirect to + return new RedirectResponse(...); + } + } + +Then, define a new service for this login handler: + +.. code-block:: yaml + + # app/config/services.yml + services: + app.security.success_login: + class: AppBundle\Security\SuccesfulLoginHandler + +Lastly, add a new ``success_handler`` option under the configuration of the +firewalls where this handler will be enabled and pass the ``id`` of the service +as its value: + +.. code-block:: yaml + + # app/config/security.yml + firewalls: + main: + pattern: ^/ + form_login: + success_handler: app.security.successful_login + +Creating a Failure Login Handler +-------------------------------- + +The steps to follow are identical to the ones explained in the previous section. +First, define your own logic in a class that implements +:class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationFailureHandlerInterface` +and create a new service for it. Then, add the ``failure_handler`` configuration +option in your firewall: + +.. code-block:: yaml + + # app/config/security.yml + firewalls: + main: + pattern: ^/ + form_login: + failure_handler: app.security.failure_login + +When Should Login Handlers Be Used? +----------------------------------- + +Symfony defines an event called ``security.interactive_login`` that lets you +customize the behavior of the login process. The main differences between this +event and the login handlers are XXXX and YYYY. + +Therefore, you should use the login handlers when XXXX and YYYY, whereas the +interactive login event is better for ZZZZ. From 7d562dbc4f908968020f4049a2d2ac32d2c34d9e Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 21 May 2016 11:00:49 +0200 Subject: [PATCH 2/6] Added the explanation of the last section --- cookbook/security/login_handlers.rst | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/cookbook/security/login_handlers.rst b/cookbook/security/login_handlers.rst index a70a3a4e243..1d1f8356060 100644 --- a/cookbook/security/login_handlers.rst +++ b/cookbook/security/login_handlers.rst @@ -81,9 +81,15 @@ option in your firewall: When Should Login Handlers Be Used? ----------------------------------- -Symfony defines an event called ``security.interactive_login`` that lets you -customize the behavior of the login process. The main differences between this -event and the login handlers are XXXX and YYYY. - -Therefore, you should use the login handlers when XXXX and YYYY, whereas the -interactive login event is better for ZZZZ. +These security handlers are closely related to the ``security.authentication.success`` +and ``security.authentication.failure`` events, but Symfony also defines an event +called ``security.interactive_login`` that lets you customize the behavior of +the login process. + +The success/failure handlers should be used when you need to change the login +behavior on success/failure by changing the returned ``Response`` object. + +The listener hooked into ``security.interactive_login`` should be used when you +need to execute some code on login success/failure but without altering the +``Response`` object being sent. For example, to store in a Redis cache the number +of failed login attempts to protect against brute-force attacks. From 7dde7b15beed98ce24800facaa28d9a7508b8072 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 21 May 2016 15:29:50 +0200 Subject: [PATCH 3/6] Fixes --- cookbook/security/login_handlers.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/cookbook/security/login_handlers.rst b/cookbook/security/login_handlers.rst index 1d1f8356060..3963c84c487 100644 --- a/cookbook/security/login_handlers.rst +++ b/cookbook/security/login_handlers.rst @@ -6,10 +6,11 @@ How to Customize the Success and Failure Login Handlers ======================================================= -After the users successfully log in in your application, they are redirected to +After the users successfully log in to your application, they are redirected to the proper URL according to the security configuration options. This is done in the :class:`Symfony\\Component\\Security\\Http\\Authentication\\DefaultAuthenticationSuccessHandler` -class and Symfony defines a similar class called ``DefaultAuthenticationFailureHandler`` +class and Symfony defines a similar class called +:class:`Symfony\\Component\\Security\\Http\\Authentication\\DefaultAuthenticationFailureHandler` to handle the login failures. This article explains **how to define your own login handlers** to execute From 362a09fad2f84f034ba67fb7a509942a9b247c48 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 21 May 2016 15:38:37 +0200 Subject: [PATCH 4/6] Added all the configuration formats --- cookbook/security/login_handlers.rst | 143 +++++++++++++++++++++++---- 1 file changed, 122 insertions(+), 21 deletions(-) diff --git a/cookbook/security/login_handlers.rst b/cookbook/security/login_handlers.rst index 3963c84c487..90dcfdf48e5 100644 --- a/cookbook/security/login_handlers.rst +++ b/cookbook/security/login_handlers.rst @@ -41,25 +41,88 @@ and add your own logic:: Then, define a new service for this login handler: -.. code-block:: yaml +.. configuration-block:: - # app/config/services.yml - services: - app.security.success_login: - class: AppBundle\Security\SuccesfulLoginHandler + .. code-block:: yaml + + # app/config/services.yml + services: + app.security.success_login: + class: AppBundle\Security\SuccesfulLoginHandler + + .. code-block:: xml + + + + + + + + + + + + .. code-block:: php + + // src/AppBundle/Resources/config/services.php + $container->register( + 'app.security.success_login', + 'AppBundle\Security\SuccesfulLoginHandler' + ); Lastly, add a new ``success_handler`` option under the configuration of the firewalls where this handler will be enabled and pass the ``id`` of the service as its value: -.. code-block:: yaml - - # app/config/security.yml - firewalls: - main: - pattern: ^/ - form_login: - success_handler: app.security.successful_login +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security: + # ... + firewalls: + main: + # ... + form_login: + success_handler: app.security.successful_login + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', array( + // ... + 'firewalls' => array( + 'main' => array( + // ... + 'form_login' => array( + 'success_handler' => 'app.security.successful_login', + ), + ), + ), + )); Creating a Failure Login Handler -------------------------------- @@ -70,14 +133,52 @@ First, define your own logic in a class that implements and create a new service for it. Then, add the ``failure_handler`` configuration option in your firewall: -.. code-block:: yaml - - # app/config/security.yml - firewalls: - main: - pattern: ^/ - form_login: - failure_handler: app.security.failure_login +.. configuration-block:: + + .. code-block:: yaml + + # app/config/security.yml + security: + # ... + firewalls: + main: + # ... + form_login: + failure_handler: app.security.failure_login + + .. code-block:: xml + + + + + + + + + + + + + + + .. code-block:: php + + // app/config/security.php + $container->loadFromExtension('security', array( + // ... + 'firewalls' => array( + 'main' => array( + // ... + 'form_login' => array( + 'failure_handler' => 'app.security.failure_login', + ), + ), + ), + )); When Should Login Handlers Be Used? ----------------------------------- From c3119e73227c70c939371cf5281daff8460c2b32 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 21 May 2016 15:39:52 +0200 Subject: [PATCH 5/6] Fixed a grammar issue --- cookbook/security/login_handlers.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cookbook/security/login_handlers.rst b/cookbook/security/login_handlers.rst index 90dcfdf48e5..a2a1ea91ebb 100644 --- a/cookbook/security/login_handlers.rst +++ b/cookbook/security/login_handlers.rst @@ -128,7 +128,7 @@ Creating a Failure Login Handler -------------------------------- The steps to follow are identical to the ones explained in the previous section. -First, define your own logic in a class that implements +First, define your own logic in a class that implements the :class:`Symfony\\Component\\Security\\Http\\Authentication\\AuthenticationFailureHandlerInterface` and create a new service for it. Then, add the ``failure_handler`` configuration option in your firewall: From ecfd34d3d051a674fb1ac9d7072adf6694fbced2 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sat, 21 May 2016 15:50:41 +0200 Subject: [PATCH 6/6] Fixed some copy+paste errors --- cookbook/security/login_handlers.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cookbook/security/login_handlers.rst b/cookbook/security/login_handlers.rst index a2a1ea91ebb..ee46bd8c4eb 100644 --- a/cookbook/security/login_handlers.rst +++ b/cookbook/security/login_handlers.rst @@ -52,7 +52,7 @@ Then, define a new service for this login handler: .. code-block:: xml - + register( 'app.security.success_login', 'AppBundle\Security\SuccesfulLoginHandler'