Updating some places to use the new CustomUserMessageAuthenticationException

cookbook/security/api_key_authentication.rst

@@ -25,6 +25,7 @@ value and then a User object is created::
     use Symfony\Component\Security\Core\Authentication\SimplePreAuthenticatorInterface;
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
     use Symfony\Component\Security\Core\Authentication\Token\PreAuthenticatedToken;
     use Symfony\Component\HttpFoundation\Request;
     use Symfony\Component\Security\Core\User\UserProviderInterface;
@@ -69,7 +70,8 @@ value and then a User object is created::
             $username = $userProvider->getUsernameForApiKey($apiKey);
 
             if (!$username) {
-                throw new AuthenticationException(
+                // this message will be returned to the client
+                throw new CustomUserMessageAuthenticationException(
                     sprintf('API Key "%s" does not exist.', $apiKey)
                 );
             }
@@ -90,6 +92,11 @@ value and then a User object is created::
         }
     }
 
+.. versionadded:: 2.8
+    The ``CustomUserMessageAuthenticationException`` class is new in Symfony 2.8
+    and helps you return custom authentication messages. In 2.7 or earlier, throw
+    an ``AuthenticationException`` or any sub-class (you can still do this in 2.8).
+
 Once you've :ref:`configured <cookbook-security-api-key-config>` everything,
 you'll be able to authenticate by adding an apikey parameter to the query
 string, like ``http://example.com/admin/foo?apikey=37b51d194a7513e45b56f6524f2d51f2``.
@@ -280,7 +287,11 @@ you can use to create an error ``Response``.
 
         public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
         {
-            return new Response("Authentication Failed.", 403);
+            return new Response(
+                // this contains information about *why* authentication failed
+                // use it, or return your own message
+                strtr($exception->getMessageKey(), $exception->getMessageData())
+            , 403)
         }
     }
 
@@ -532,7 +543,8 @@ to see if the stored token has a valid User object that can be used::
             }
 
             if (!$username) {
-                throw new AuthenticationException(
+                // this message will be returned to the client
+                throw new CustomUserMessageAuthenticationException(
                     sprintf('API Key "%s" does not exist.', $apiKey)
                 );
             }

cookbook/security/custom_password_authenticator.rst

@@ -29,7 +29,7 @@ the user::
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
     use Symfony\Component\Security\Core\Authentication\Token\UsernamePasswordToken;
     use Symfony\Component\Security\Core\Encoder\UserPasswordEncoderInterface;
-    use Symfony\Component\Security\Core\Exception\AuthenticationException;
+    use Symfony\Component\Security\Core\Exception\CustomUserMessageAuthenticationException;
     use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
     use Symfony\Component\Security\Core\User\UserProviderInterface;
 
@@ -47,15 +47,17 @@ the user::
             try {
                 $user = $userProvider->loadUserByUsername($token->getUsername());
             } catch (UsernameNotFoundException $e) {
-                throw new AuthenticationException('Invalid username or password');
+                // error will be shown to the client
+                throw new CustomUserMessageAuthenticationException('Invalid username or password');
             }
 
             $passwordValid = $this->encoder->isPasswordValid($user, $token->getCredentials());
 
             if ($passwordValid) {
                 $currentHour = date('G');
                 if ($currentHour < 14 || $currentHour > 16) {
-                    throw new AuthenticationException(
+                    // error will be shown to the client
+                    throw new CustomUserMessageAuthenticationException(
                         'You can only log in between 2 and 4!',
                         100
                     );
@@ -69,7 +71,8 @@ the user::
                 );
             }
 
-            throw new AuthenticationException('Invalid username or password');
+            // error will be shown to the client
+            throw new CustomUserMessageAuthenticationException('Invalid username or password');
         }
 
         public function supportsToken(TokenInterface $token, $providerKey)
@@ -84,6 +87,11 @@ the user::
         }
     }
 
+.. versionadded:: 2.8
+    The ``CustomUserMessageAuthenticationException`` class is new in Symfony 2.8
+    and helps you return custom authentication messages. In 2.7 or earlier, throw
+    an ``AuthenticationException`` or any sub-class (you can still do this in 2.8).
+
 How it Works
 ------------