feature #3565 added information on AuthenticationFailureHandlerInterface (samsamm777)

weaverryan · weaverryan · commit b02c16aa4304 · 2014-03-09T17:09:05.000-05:00
This PR was submitted for the master branch but it was merged into the 2.4 branch instead (closes #3565). Discussion ---------- added information on AuthenticationFailureHandlerInterface The Api Keys documentation made no mention of the AuthenticationFailureHandlerInterface which is required to correctly display Authentication Failure responses. Without it, authentication failures will result in a 500 response. I've made mention to the interface and given an example implementation. http://symfony.com/doc/current/cookbook/security/api_key_authentication.html#cookbook-security-api-key-config ``` Doc fix? yes New docs? no Applies to: 2.4 Fixed tickets: none found ``` Commits ------- 066bccb fixed typo db8e01a recommendations by xabbuh 3366dfc fixed authentication failed header 21e3536 fixed line wrapping e4f5c6e added information on AuthenticationFailureHandlerInterface in api keys docs
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1 @@
+.DS_Store
diff --git a/cookbook/security/api_key_authentication.rst b/cookbook/security/api_key_authentication.rst
@@ -210,6 +210,34 @@ 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 Authentication Failure
+-------------------------------
+
+In order for your ``ApiKeyAuthentication`` to correctly display a 403
+http status when either bad credentials or authentication fails you will 
+need to implement the :class:`Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface` on your 
+Authenticator. This will provide a method ``onAuthenticationFailure`` which 
+you can use to create an error ``Response``.
+
+    // src/Acme/HelloBundle/Security/ApiKeyAuthenticator.php
+    namespace Acme\HelloBundle\Security;
+
+    use Symfony\Component\Security\Core\Authentication\SimplePreAuthenticatorInterface;
+    use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Http\Authentication\AuthenticationFailureHandlerInterface;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\HttpFoundation\Request;
+
+    class ApiKeyAuthenticator implements SimplePreAuthenticatorInterface, AuthenticationFailureHandlerInterface
+    {
+        //...
+
+        public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
+        {
+            return new Response("Authentication Failed.", 403);
+        }
+    }
+
 .. _cookbook-security-api-key-config:
 
 Configuration
