Success/failure handlers are not documented

[fabpot]

Working on fixing symfony/symfony#10417, I wanted to update the documentation but there is no documentation for custom success/failure handlers for the firewall configuration. The success_handler and success_failure configuration settings are mentioned in configuration examples, but there is no explanation whatsoever.

I think we need to document them, but only as of Symfony 2.6 as they are less useful before. So, we need to document them in a new cookbook entry, based on the changes done in symfony/symfony#11993.

[wouterj]

We have an open issue for this in #802 We had some issues finding good usecases for such listeners, do you know anything?

[fabpot]

@wouterj Tickets symfony/symfony#5432, symfony/symfony#9272, symfony/symfony#10417, symfony/symfony#11926 talk about some use cases.

[weaverryan]

The use-case I just had (which seems reasonable) is authenticating via AJAX, and so wanting a JSON response back in those cases. But, for non-AJAX, I want to have the normal redirect functionality.

class CustomAuthenticationFailureHandler extends DefaultAuthenticationFailureHandler
{
    /**
     * @var TranslatorInterface
     */
    private $translator;

    public function setTranslator(TranslatorInterface $translator)
    {
        $this->translator = $translator;
    }

    public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
    {
        if ($request->isXmlHttpRequest()) {
            return new JsonResponse(array(
                'authenticated' => false,
                'error' => $this->translator->trans($exception->getMessageKey(), $exception->getMessageData()),
            ));
        }

        return parent::onAuthenticationFailure($request, $exception);
    }
}

services:
    security.custom_auth_failure_handler:
        class: Knp\UserBundle\Security\Authentication\CustomAuthenticationFailureHandler
        arguments:
            - "@http_kernel"
            - "@security.http_utils"
        calls:
            - [setTranslator, ["@translator"]]

And of course, failure_handler is set to this service id.

If you don't want to extend DefaultAuthenticationFailureHandler, then you can just implement AuthenticationFailureHandlerInterface. But the key is that if you have a setOptions(array $options) method on your failure handler, Symfony will call that and pass you all the things like failure_path, etc. That's the change that happened in symfony/symfony#11993 (which is also why extending DefaultAuthenticationFailureHandler works).

So, I think this can be added, though maybe we should just doc it for 2.6, and backport a few pieces to 2.3. Marking this as actionable :). Imo, we should work these into this article: http://symfony.com/doc/current/cookbook/security/form_login.html, and maybe rename it - it's really all about handling redirect behavior after login - maybe "How to control what happens after a user logs in (or fails login)"

[nicolas-san]

@wouterj I want to redirect my user on different route based on is role.
One have access to a dashboard, another just is profile page.

So, after some search, I use a custom handler:

https://github.com/nicolas-san/authSuccessHandlerRedirect/blob/master/MyBundle/Handler/LoginSuccessHandler.php

(I use Fos user bundle, my route for profile is fos_user_profile_show, for general purpose, I can change it to more basic route like "profile".)

Perhaps this usecase is ok for the doc ?
And if you have some comment on my handler, I'll take them :)

[ABM-Dan]

This might be made easier to explain if we had interfaces exposing setOptions and setProviderKey.

[ureimers]

As this issue is still open (because of lack of a good use case?) maybe this one will do:

My use case is that new user's need to confirm their email address first by receiving and following a standard double-opt-in mail. If a user then confirms her email address, a flag isEmailConfirmed is set to true.

When a user logs in a simple UserChecker checks the flag on post authentication:

final class UserChecker implements UserCheckerInterface
{
    public function checkPostAuth(UserInterface $user)
    {
        if (!$user->isEmailConfirmed()) {
            throw new EmailNotConfirmedException();
        }
    }

    public function checkPreAuth(UserInterface $user)
    {
        // Nothing to do before authentication. Yet.
    }
}

I then use a custom AuthenticationFailureHandler to handle that specific exception and redirect the user to a page where she can resend her confirmation email. As I still want to use the default logic for every other scenario, I extend the DefaultAuthenticationFailureHandler:

final class AuthenticationFailureHandler extends DefaultAuthenticationFailureHandler
{
    public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
    {
        if ($exception instanceof EmailNotConfirmedException) {
            return $this->httpUtils->createRedirectResponse($request, 'app_resend_confirmation_email');
        }

        return parent::onAuthenticationFailure($request, $exception);
    }
}

Both of the mechanisms used show how easy it is to accomplish both, a post authentication check and redirecting the user because of what the post authentication request might have thrown. Just beautiful :-)

There are other scenarios like this where you want to present a user a dedicated page if a specific requirement for a successful login wasn't met. Without the custom failure handler, the EmailNotConfirmedException's message would simply be displayed as an error of the login form.

Additional notes:

It seems that with Symfony 3.4 the mentioning of the handler was removed entirely from the default security configuration documentation. Is there a reason for that? Without looking through the source code of the Security Component I wouldn't have found out about this very useful configuration method.

Furthermore this comment from Fabien should be mentioned in a possible documentation too. It's easy to miss so I'll add it here again:

There is one slight side-effect: as we are passing options and the provider key, you must not use the same custom handler in two different firewalls.

[carsonbot]

Thank you for this issue.
There has not been a lot of activity here for a while. Has this been resolved?

[carsonbot]

Just a quick reminder to make a comment on this. If I don't hear anything I'll close this.

[wouterj]

Success/failure handlers are still relevant in the new security system and definitely deserve some documentation.

[javiereguiluz]

Closing in favor of #15908, a meta-issue that groups all pending security-related issues so we can easily check them.

[javiereguiluz]

Closing as fixed in #18931.