minor #14045 [Security] Clarify the purpose of access denied handler (and entry point) (wouterj)

This PR was merged into the 4.4 branch.

Discussion
----------

[Security] Clarify the purpose of access denied handler (and entry point)

There is some confusion about the AccessDeniedHandler - mostly due to the way we've documented it. This PR tries to fix it by documenting what the AccessDeniedHandler is doing, how the other cases can be catched (using an entry point) and how you can catch all access denied exceptions (using an exception listener).

Commits
-------

3892e26 Clarify authentication entry point and access denied handler

Author: wouterj

security/access_denied_handler.rst

@@ -1,17 +1,116 @@
 .. index::
     single: Security; Creating a Custom Access Denied Handler
 
-How to Create a Custom Access Denied Handler
-============================================
+How to Customize Access Denied Responses
+========================================
 
-When your application throws an ``AccessDeniedException``, you can handle this exception
-with a service to return a custom response.
+In Symfony, you can throw an
+:class:`Symfony\\Component\\Security\\Core\\Exception\\AccessDeniedException`
+to disallow access to the user. Symfony will handle this exception and
+generates a response based on the authentication state:
 
-First, create a class that implements
+* **If the user is not authenticated** (or authenticated anonymously), an
+  authentication entry point is used to generated a response (typically
+  a redirect to the login page or an *401 Unauthorized* response);
+* **If the user is authenticated, but does not have the required
+  permissions**, a *403 Forbidden* response is generated.
+
+Customize the Unauthorized Response
+-----------------------------------
+
+You need to create a class that implements
+:class:`Symfony\\Component\\Security\\Http\\EntryPoint\\AuthenticationEntryPointInterface`.
+This interface has one method (``start()``) that is called whenever an
+unauthenticated user tries to access a protected resource::
+
+    // src/Security/AuthenticationEntryPoint.php
+    namespace App\Security;
+
+    use Symfony\Component\HttpFoundation\RedirectResponse;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Session\SessionInterface;
+    use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Http\EntryPoint\AuthenticationEntryPointInterface;
+
+    class AuthenticationEntryPoint implements AuthenticationEntryPointInterface
+    {
+        private $urlGenerator;
+        private $session;
+
+        public function __construct(UrlGeneratorInterface $urlGenerator, SessionInterface $session)
+        {
+            $this->urlGenerator = $urlGenerator;
+            $this->session = $session;
+        }
+
+        public function start(Request $request, AuthenticationException $authException = null): RedirectResponse
+        {
+            // add a custom flash message and redirect to the login page
+            $this->session->getFlashBag()->add('note', 'You have to login in order to access this page.');
+
+            return new RedirectResponse($this->urlGenerator->generate('security_login'));
+        }
+    }
+
+That's it if you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`.
+Otherwise, you have to register this service in the container.
+
+Now, configure this service ID as the entry point for the firewall:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/security.yaml
+        firewalls:
+            # ...
+
+            main:
+                # ...
+                entry_point: App\Security\AuthenticationEntryPoint
+
+    .. code-block:: xml
+
+        <!-- config/packages/security.xml -->
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <firewall name="main"
+                    entry-point="App\Security\AuthenticationEntryPoint"
+                >
+                    <!-- ... -->
+                </firewall>
+            </config>
+        </srv:container>
+
+    .. code-block:: php
+
+        // config/packages/security.php
+        use App\Security\AuthenticationEntryPoint;
+
+        $container->loadFromExtension('security', [
+            'firewalls' => [
+                'main' => [
+                    // ...
+                    'entry_point' => AuthenticationEntryPoint::class,
+                ],
+            ],
+        ]);
+
+Customize the Forbidden Response
+--------------------------------
+
+Create a class that implements
 :class:`Symfony\\Component\\Security\\Http\\Authorization\\AccessDeniedHandlerInterface`.
-This interface defines one method called ``handle()`` where you can implement whatever
-logic that should run when access is denied for the current user (e.g. send a
-mail, log a message, or generally return a custom response)::
+This interface defines one method called ``handle()`` where you can
+implement whatever logic that should execute when access is denied for the
+current user (e.g. send a mail, log a message, or generally return a custom
+response)::
 
     // src/Security/AccessDeniedHandler.php
     namespace App\Security;
@@ -50,11 +149,21 @@ configure it under your firewall:
     .. code-block:: xml
 
         <!-- config/packages/security.xml -->
-        <config>
-            <firewall name="main">
-                <access-denied-handler>App\Security\AccessDeniedHandler</access-denied-handler>
-            </firewall>
-        </config>
+        <?xml version="1.0" encoding="UTF-8"?>
+        <srv:container xmlns="http://symfony.com/schema/dic/security"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:srv="http://symfony.com/schema/dic/services"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <config>
+                <firewall name="main"
+                    access-denied-handler="App\Security\AccessDeniedHandler"
+                >
+                    <!-- ... -->
+                </firewall>
+            </config>
+        </srv:container>
 
     .. code-block:: php
 
@@ -70,5 +179,47 @@ configure it under your firewall:
             ],
         ]);
 
-That's it! Any ``AccessDeniedException`` thrown by code under the ``main`` firewall
-will now be handled by your service.
+Customizing All Access Denied Responses
+---------------------------------------
+
+In some cases, you might want to customize both responses or do a specific
+action (e.g. logging) for each ``AccessDeniedException``. In this case,
+configure a :ref:`kernel.exception listener <use-kernel-exception-event>`::
+
+    // src/EventListener/AccessDeniedListener.php
+    namespace App\EventListener;
+
+    use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpKernel\Event\ExceptionEvent;
+    use Symfony\Component\HttpKernel\KernelEvents;
+    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+
+    class AccessDeniedListener implements EventSubscriberInterface
+    {
+        public static function getSubscribedEvents(): array
+        {
+            return [
+                // the priority must be greater than the Security HTTP
+                // ExceptionListener, to make sure it's called before
+                // the default exception listener
+                KernelEvents::EXCEPTION => ['onKernelException', 2],
+            ];
+        }
+
+        public function onKernelException(ExceptionEvent $event): void
+        {
+            $exception = $event->getException();
+            if (!$exception instanceof AccessDeniedException) {
+                return;
+            }
+
+            // ... perform some action (e.g. logging)
+
+            // optionally set the custom response
+            $event->setResponse(new Response(null, 403));
+
+            // or stop propagation (prevents the next exception listeners from being called)
+            //$event->stopPropagation();
+        }
+    }