fixes

`supportsToken` should be defined above `authenticateToken` to reflect documentation numbering

`onAuthenticationFailure` should return http code 401 Unauthorized (RFC 7235) not 403 Forbidden.

added missing information about defining `access_control` - figuring this out kept me hanging for a while

used `ROLE_API` instead of `ROLE_USER` to demonstrate `access_control` configuration

Author: gondo

cookbook/security/api_key_authentication.rst

@@ -54,6 +54,11 @@ value and then a User object is created::
             );
         }
 
+        public function supportsToken(TokenInterface $token, $providerKey)
+        {
+            return $token instanceof PreAuthenticatedToken && $token->getProviderKey() === $providerKey;
+        }
+
         public function authenticateToken(TokenInterface $token, UserProviderInterface $userProvider, $providerKey)
         {
             if (!$userProvider instanceof ApiKeyUserProvider) {
@@ -83,11 +88,6 @@ value and then a User object is created::
                 $user->getRoles()
             );
         }
-
-        public function supportsToken(TokenInterface $token, $providerKey)
-        {
-            return $token instanceof PreAuthenticatedToken && $token->getProviderKey() === $providerKey;
-        }
     }
 
 Once you've :ref:`configured <cookbook-security-api-key-config>` everything,
@@ -177,7 +177,7 @@ The ``$userProvider`` might look something like this::
                 null,
                 // the roles for the user - you may choose to determine
                 // these dynamically somehow based on the user
-                array('ROLE_USER')
+                array('ROLE_API')
             );
         }
 
@@ -249,6 +249,7 @@ would allow you to have custom data on the ``User`` object.
 
 Finally, just make sure that ``supportsClass()`` returns ``true`` for User
 objects with the same class as whatever user you return in ``loadUserByUsername()``.
+
 If your authentication is stateless like in this example (i.e. you expect
 the user to send the API key with every request and so you don't save the
 login to the session), then you can simply throw the ``UnsupportedUserException``
@@ -262,7 +263,7 @@ exception in ``refreshUser()``.
 Handling Authentication Failure
 -------------------------------
 
-In order for your ``ApiKeyAuthenticator`` to correctly display a 403
+In order for your ``ApiKeyAuthenticator`` to correctly display a 401
 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
@@ -285,7 +286,7 @@ you can use to create an error ``Response``.
 
         public function onAuthenticationFailure(Request $request, AuthenticationException $exception)
         {
-            return new Response("Authentication Failed.", 403);
+            return new Response("Authentication Failed.", 401);
         }
     }
 
@@ -411,6 +412,46 @@ using the ``simple_preauth`` and ``provider`` keys respectively:
             ),
         ));
 
+If you have defined `access_control`, make sure to add new entry:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/security.yml
+        security:
+            # ...
+            
+            access_control:
+                - { path: ^/admin, roles: ROLE_API }
+
+    .. code-block:: xml
+
+        <!-- app/config/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
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <rule path="^/admin"
+                role="ROLE_API"
+            />
+        </srv:container>
+
+    .. code-block:: php
+
+        // app/config/security.php
+        $container->loadFromExtension('security', array(
+            'access_control' => array(
+                array(
+                    'path' => '^/admin',
+                    'role' => 'ROLE_API',
+                ),
+            ),
+        ));
+
 That's it! Now, your ``ApiKeyAuthenticator`` should be called at the beginning
 of each request and your authentication process will take place.