feature #4895 Added configuration of the user provider (peterrehm)

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

Discussion
----------

Added configuration of the user provider

| Q             | A
| ------------- | ---
| Doc fix?      | yes
| New docs?     | no
| Applies to    | all
| Fixed tickets | #4148

This should make it clearer that a user provider must be registered.

Commits
-------

075b652 Removed unneeded spaces
56dd365 Updated as per discussion
c4cbd84 Updated according to comment and changed to AppBundle
a6fb18c Added configuration of the your_api_key_user_provider as user provider

cookbook/security/api_key_authentication.rst

@@ -22,8 +22,8 @@ Your exact situation may differ, but in this example, a token is read
 from an ``apikey`` query parameter, the proper username is loaded from that
 value and then a User object is created::
 
-    // src/Acme/HelloBundle/Security/ApiKeyAuthenticator.php
-    namespace Acme\HelloBundle\Security;
+    // src/AppBundle/Security/ApiKeyAuthenticator.php
+    namespace AppBundle\Security;
 
     use Symfony\Component\Security\Core\Authentication\SimplePreAuthenticatorInterface;
     use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
@@ -147,8 +147,8 @@ used by Symfony's core user provider system).
 
 The ``$userProvider`` might look something like this::
 
-    // src/Acme/HelloBundle/Security/ApiKeyUserProvider.php
-    namespace Acme\HelloBundle\Security;
+    // src/AppBundle/Security/ApiKeyUserProvider.php
+    namespace AppBundle\Security;
 
     use Symfony\Component\Security\Core\User\UserProviderInterface;
     use Symfony\Component\Security\Core\User\User;
@@ -192,6 +192,41 @@ The ``$userProvider`` might look something like this::
         }
     }
 
+Now register your user provider as service:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # app/config/services.yml
+        services:
+            api_key_user_provider:
+                class: AppBundle\Security\ApiKeyUserProvider
+
+    .. code-block:: xml
+
+        <!-- app/config/services.xml -->
+        <?xml version="1.0" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd">
+            <services>
+                <!-- ... -->
+
+                <service id="api_key_user_provider"
+                    class="AppBundle\Security\ApiKeyUserProvider" />
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        // app/config/services.php
+
+        // ...
+        $container
+            ->register('api_key_user_provider', 'AppBundle\Security\ApiKeyUserProvider');
+
 .. note::
 
     Read the dedicated article to learn
@@ -231,8 +266,8 @@ you can use to create an error ``Response``.
 
 .. code-block:: php
 
-    // src/Acme/HelloBundle/Security/ApiKeyAuthenticator.php
-    namespace Acme\HelloBundle\Security;
+    // src/AppBundle/Security/ApiKeyAuthenticator.php
+    namespace AppBundle\Security;
 
     use Symfony\Component\Security\Core\Authentication\SimplePreAuthenticatorInterface;
     use Symfony\Component\Security\Core\Exception\AuthenticationException;
@@ -270,8 +305,8 @@ your custom user provider as a service called ``your_api_key_user_provider``
             # ...
 
             apikey_authenticator:
-                class:     Acme\HelloBundle\Security\ApiKeyAuthenticator
-                arguments: ["@your_api_key_user_provider"]
+                class:     AppBundle\Security\ApiKeyAuthenticator
+                arguments: ["@api_key_user_provider"]
 
     .. code-block:: xml
 
@@ -285,9 +320,9 @@ your custom user provider as a service called ``your_api_key_user_provider``
                 <!-- ... -->
 
                 <service id="apikey_authenticator"
-                    class="Acme\HelloBundle\Security\ApiKeyAuthenticator"
+                    class="AppBundle\Security\ApiKeyAuthenticator"
                 >
-                    <argument type="service" id="your_api_key_user_provider" />
+                    <argument type="service" id="api_key_user_provider" />
                 </service>
             </services>
         </container>
@@ -301,8 +336,8 @@ your custom user provider as a service called ``your_api_key_user_provider``
         // ...
 
         $container->setDefinition('apikey_authenticator', new Definition(
-            'Acme\HelloBundle\Security\ApiKeyAuthenticator',
-            array(new Reference('your_api_key_user_provider'))
+            'AppBundle\Security\ApiKeyAuthenticator',
+            array(new Reference('api_key_user_provider'))
         ));
 
 Now, activate it in the ``firewalls`` section of your security configuration
@@ -323,6 +358,10 @@ using the ``simple_preauth`` key:
                     simple_preauth:
                         authenticator: apikey_authenticator
 
+            providers:
+                api_key_user_provider:
+                    id: api_key_user_provider
+
     .. code-block:: xml
 
         <!-- app/config/security.xml -->
@@ -341,6 +380,8 @@ using the ``simple_preauth`` key:
                 >
                     <simple-preauth authenticator="apikey_authenticator" />
                 </firewall>
+
+                <provider name="api_key_user_provider" id="api_key_user_provider" />
             </config>
         </srv:container>
 
@@ -360,6 +401,11 @@ using the ``simple_preauth`` key:
                     ),
                 ),
             ),
+            'providers' => array(
+                'api_key_user_provider'  => array(
+                    'id' => 'api_key_user_provider',
+                ),
+            ),
         ));
 
 That's it! Now, your ``ApiKeyAuthentication`` should be called at the beginning
@@ -399,6 +445,10 @@ configuration or set it to ``false``:
                     simple_preauth:
                         authenticator: apikey_authenticator
 
+            providers:
+                api_key_user_provider:
+                    id: api_key_user_provider
+
     .. code-block:: xml
 
         <!-- app/config/security.xml -->
@@ -417,6 +467,8 @@ configuration or set it to ``false``:
                 >
                     <simple-preauth authenticator="apikey_authenticator" />
                 </firewall>
+
+                <provider name="api_key_user_provider" id="api_key_user_provider" />
             </config>
         </srv:container>
 
@@ -435,14 +487,19 @@ configuration or set it to ``false``:
                     ),
                 ),
             ),
+            'providers' => array(
+                'api_key_user_provider' => array(
+                    'id' => 'api_key_user_provider',
+                ),
+            ),
         ));
 
 Even though the token is being stored in the session, the credentials - in this
 case the API key (i.e. ``$token->getCredentials()``) - are not stored in the session
 for security reasons. To take advantage of the session, update ``ApiKeyAuthenticator``
 to see if the stored token has a valid User object that can be used::
 
-    // src/Acme/HelloBundle/Security/ApiKeyAuthenticator.php
+    // src/AppBundle/Security/ApiKeyAuthenticator.php
     // ...
 
     class ApiKeyAuthenticator implements SimplePreAuthenticatorInterface
@@ -496,7 +553,7 @@ stored in the database, then you may want to re-query for a fresh version
 of the user to make sure it's not out-of-date. But regardless of your requirements,
 ``refreshUser()`` should now return the User object::
 
-    // src/Acme/HelloBundle/Security/ApiKeyUserProvider.php
+    // src/AppBundle/Security/ApiKeyUserProvider.php
 
     // ...
     class ApiKeyUserProvider implements UserProviderInterface
@@ -536,7 +593,7 @@ a certain URL (e.g. the redirect URL in OAuth).
 Fortunately, handling this situation is easy: just check to see what the
 current URL is before creating the token in ``createToken()``::
 
-    // src/Acme/HelloBundle/Security/ApiKeyAuthenticator.php
+    // src/AppBundle/Security/ApiKeyAuthenticator.php
 
     // ...
     use Symfony\Component\Security\Http\HttpUtils;
@@ -548,7 +605,7 @@ current URL is before creating the token in ``createToken()``::
 
         protected $httpUtils;
 
-        public function __construct(ApiKeyUserProviderInterface $userProvider, HttpUtils $httpUtils)
+        public function __construct(UserProviderInterface $userProvider, HttpUtils $httpUtils)
         {
             $this->userProvider = $userProvider;
             $this->httpUtils = $httpUtils;
@@ -584,8 +641,8 @@ service:
             # ...
 
             apikey_authenticator:
-                class:     Acme\HelloBundle\Security\ApiKeyAuthenticator
-                arguments: ["@your_api_key_user_provider", "@security.http_utils"]
+                class:     AppBundle\Security\ApiKeyAuthenticator
+                arguments: ["@api_key_user_provider", "@security.http_utils"]
 
     .. code-block:: xml
 
@@ -599,9 +656,9 @@ service:
                 <!-- ... -->
 
                 <service id="apikey_authenticator"
-                    class="Acme\HelloBundle\Security\ApiKeyAuthenticator"
+                    class="AppBundle\Security\ApiKeyAuthenticator"
                 >
-                    <argument type="service" id="your_api_key_user_provider" />
+                    <argument type="service" id="api_key_user_provider" />
                     <argument type="service" id="security.http_utils" />
                 </service>
             </services>
@@ -616,9 +673,9 @@ service:
         // ...
 
         $container->setDefinition('apikey_authenticator', new Definition(
-            'Acme\HelloBundle\Security\ApiKeyAuthenticator',
+            'AppBundle\Security\ApiKeyAuthenticator',
             array(
-                new Reference('your_api_key_user_provider'),
+                new Reference('api_key_user_provider'),
                 new Reference('security.http_utils')
             )
         ));