added information on AuthenticationFailureHandlerInterface in api keys docs

Sam Hudson · weaverryan · commit 92fb4b12cc31 · 2014-03-09T17:09:04.000-05:00
diff --git a/cookbook/security/api_key_authentication.rst b/cookbook/security/api_key_authentication.rst
@@ -210,6 +210,27 @@ exception in ``refreshUser()``.
     If you *do* want to store authentication data in the session so that
     the key doesn't need to be sent on every request, see :ref:`cookbook-security-api-key-session`.
 
+Handling Exceptions
+-------------------
+
+In order for you're ``ApiKeyAuthentication`` to correctly display a 403 http status when either bad credentials, or authentication fails you will need to implement the ``AuthenticationFailureHandlerInterface`` on your Authenticator. This will provide a method ``onAuthenticationFailure`` which you can then return a ``Response`` with.
+
+    // src/Acme/HelloBundle/Security/ApiKeyAuthenticator.php
+    namespace Acme\HelloBundle\Security;
+
+    use Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface;
+    use Symfony\Component\HttpFoundation\Response;
+
+    class ApiKeyAuthenticator implements SimplePreAuthenticatorInterface, AuthenticationFailureHandlerInterface
+    {
+        //...
+
+        public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
+        {
+            return new Response("Authentication Failed.", 403);
+        }
+    }
+
 .. _cookbook-security-api-key-config:
 
 Configuration
