feature #7105 Add documentation about access denied handler (nykopol, javiereguiluz)

This PR was submitted for the master branch but it was merged into the 2.7 branch instead (closes #7105).

Discussion
----------

Add documentation about access denied handler

Fix #5139

Commits
-------

ea4b7f8 Minor rewordings
dff303c When talking about generic responses, don't spell it as Response (which is a Symfony class)
a9f815a xabbuh review
66c0e76 fix typo
db65dd8 fix yml marker to yaml
a17965e add documentation about access denied handler

Author: xabbuh

security.rst

@@ -1320,6 +1320,7 @@ Authorization (Denying Access)
     security/force_https
     security/securing_services
     security/access_control
+    security/access_denied_handler
 
 Other Security Related Topics
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

security/access_denied_handler.rst

@@ -0,0 +1,77 @@
+.. index::
+    single: Security; Creating a Custom Access Denied Handler
+
+How to Create a Custom Access Denied Handler
+============================================
+
+When your application throws an ``AccessDeniedException``, you can handle this exception
+with a service to return a custom response.
+
+Each firewall context can define its own custom access denied handler:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        firewalls:
+            foo:
+                # ...
+                access_denied_handler: app.security.access_denied_handler
+
+    .. code-block:: xml
+
+        <config>
+          <firewall name="foo">
+            <access_denied_handler>app.security.access_denied_handler</access_denied_handler>
+          </firewall>
+        </config>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            'firewalls' => array(
+                'foo' => array(
+                    // ...
+                    'access_denied_handler' => 'app.security.access_denied_handler',
+                ),
+            ),
+        ));
+
+
+Your handler must implement the 
+:class:`Symfony\\Component\\Security\\Http\\Authorization\\AccessDeniedHandlerInterface`.
+This interface defines one method called ``handle()`` that implements the logic to
+execute when access is denied to the current user (send a mail, log a message, or
+generally return a custom response).
+
+.. code-block:: php
+
+    namespace AppBundle\Security;
+
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+    use Symfony\Component\Security\Http\Authorization\AccessDeniedHandlerInterface;
+
+    class AccessDeniedHandler implements AccessDeniedHandlerInterface
+    {
+        public function handle(Request $request, AccessDeniedException $accessDeniedException)
+        {
+            // ...
+
+            return new Response($content, 403);
+        }
+    }
+
+Then, register the service for the access denied handler:
+
+.. code-block:: yaml
+
+    # app/config/services.yml
+    services:
+        app.security.access_denied_handler:
+            class: AppBundle\Security\AccessDeniedHandler
+
+That's it! Any ``AccessDeniedException`` thrown by the ``foo`` firewall will now be handled by your service.