Cover of the book Symfony 5: The Fast Track

Symfony 5: The Fast Track is the best book to learn modern Symfony development, from zero to production. +300 pages in full color showing how to combine Symfony with Docker, APIs, queues & async tasks, Webpack, Single-Page Applications, etc.

Buy printed version
WARNING: You are browsing the documentation for Symfony 2.8 which is not maintained anymore. Consider upgrading your projects to Symfony 5.1.

How to Create a custom User Provider

2.8 version
Maintained Unmaintained

How to Create a custom User Provider

Part of Symfony’s standard authentication process depends on “user providers”. When a user submits a username and password, the authentication layer asks the configured user provider to return a user object for a given username. Symfony then checks whether the password of this user is correct and generates a security token so the user stays authenticated during the current session. Out of the box, Symfony has four user providers: memory, entity, ldap and chain. In this article you’ll see how you can create your own user provider, which could be useful if your users are accessed via a custom database, a file, or - as shown in this example - a web service.

Create a User Class

First, regardless of where your user data is coming from, you’ll need to create a User class that represents that data. The User can look however you want and contain any data. The only requirement is that the class implements Symfony\Component\Security\Core\User\UserInterface. The methods in this interface should therefore be defined in the custom user class: getRoles(), getPassword(), getSalt(), getUsername(), eraseCredentials(). It may also be useful to implement the Symfony\Component\Security\Core\User\EquatableInterface interface, which defines a method to check if the user is equal to the current user. This interface requires an isEqualTo() method.

This is how your WebserviceUser class looks in action:

// src/AppBundle/Security/User/WebserviceUser.php
namespace AppBundle\Security\User;

use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\User\EquatableInterface;

class WebserviceUser implements UserInterface, EquatableInterface
{
    private $username;
    private $password;
    private $salt;
    private $roles;

    public function __construct($username, $password, $salt, array $roles)
    {
        $this->username = $username;
        $this->password = $password;
        $this->salt = $salt;
        $this->roles = $roles;
    }

    public function getRoles()
    {
        return $this->roles;
    }

    public function getPassword()
    {
        return $this->password;
    }

    public function getSalt()
    {
        return $this->salt;
    }

    public function getUsername()
    {
        return $this->username;
    }

    public function eraseCredentials()
    {
    }

    public function isEqualTo(UserInterface $user)
    {
        if (!$user instanceof WebserviceUser) {
            return false;
        }

        if ($this->password !== $user->getPassword()) {
            return false;
        }

        if ($this->salt !== $user->getSalt()) {
            return false;
        }

        if ($this->username !== $user->getUsername()) {
            return false;
        }

        return true;
    }
}

If you have more information about your users - like a “first name” - then you can add a firstName field to hold that data.

Create a User Provider

Now that you have a User class, you’ll create a user provider, which will grab user information from some web service, create a WebserviceUser object, and populate it with data.

The user provider is just a plain PHP class that has to implement the Symfony\Component\Security\Core\User\UserProviderInterface, which requires three methods to be defined: loadUserByUsername($username), refreshUser(UserInterface $user), and supportsClass($class). For more details, see Symfony\Component\Security\Core\User\UserProviderInterface.

Here’s an example of how this might look:

// src/AppBundle/Security/User/WebserviceUserProvider.php
namespace AppBundle\Security\User;

use AppBundle\Security\User\WebserviceUser;
use Symfony\Component\Security\Core\User\UserProviderInterface;
use Symfony\Component\Security\Core\User\UserInterface;
use Symfony\Component\Security\Core\Exception\UsernameNotFoundException;
use Symfony\Component\Security\Core\Exception\UnsupportedUserException;

class WebserviceUserProvider implements UserProviderInterface
{
    public function loadUserByUsername($username)
    {
        return $this->fetchUser($username);
    }

    public function refreshUser(UserInterface $user)
    {
        if (!$user instanceof WebserviceUser) {
            throw new UnsupportedUserException(
                sprintf('Instances of "%s" are not supported.', get_class($user))
            );
        }

        $username = $user->getUsername();

        return $this->fetchUser($username);
    }

    public function supportsClass($class)
    {
        return WebserviceUser::class === $class;
    }

    private function fetchUser($username)
    {
        // make a call to your webservice here
        $userData = ...
        // pretend it returns an array on success, false if there is no user

        if ($userData) {
            $password = '...';

            // ...

            return new WebserviceUser($username, $password, $salt, $roles);
        }

        throw new UsernameNotFoundException(
            sprintf('Username "%s" does not exist.', $username)
        );
    }
}

Create a Service for the User Provider

Now you make the user provider available as a service:

  • YAML
    1
    2
    3
    4
    # app/config/services.yml
    services:
        app.webservice_user_provider:
            class: AppBundle\Security\User\WebserviceUserProvider
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    <!-- app/config/services.xml -->
    <?xml version="1.0" encoding="UTF-8" ?>
    <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="app.webservice_user_provider"
                class="AppBundle\Security\User\WebserviceUserProvider"
            />
        </services>
    </container>
    
  • PHP
    1
    2
    3
    4
    // app/config/services.php
    use AppBundle\Security\User\WebserviceUserProvider;
    
    $container->register('app.webservice_user_provider', WebserviceUserProvider::class);
    

Tip

The real implementation of the user provider will probably have some dependencies or configuration options or other services. Add these as arguments in the service definition.

Modify security.yml

Everything comes together in your security configuration. Add the user provider to the list of providers in the “security” section. Choose a name for the user provider (e.g. “webservice”) and mention the id of the service you just defined.

  • YAML
    1
    2
    3
    4
    5
    6
    7
    # app/config/security.yml
    security:
        # ...
    
        providers:
            webservice:
                id: app.webservice_user_provider
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    <!-- 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">
    
        <config>
            <!-- ... -->
    
            <provider name="webservice" id="app.webservice_user_provider" />
        </config>
    </srv:container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    // app/config/security.php
    $container->loadFromExtension('security', array(
        // ...
    
        'providers' => array(
            'webservice' => array(
                'id' => 'app.webservice_user_provider',
            ),
        ),
    ));
    

Symfony also needs to know how to encode passwords that are supplied by website users, e.g. by filling in a login form. You can do this by adding a line to the “encoders” section in your security configuration:

  • YAML
    1
    2
    3
    4
    5
    6
    # app/config/security.yml
    security:
        # ...
    
        encoders:
            AppBundle\Security\User\WebserviceUser: bcrypt
    
  • XML
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    13
    14
    15
    <!-- 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">
    
        <config>
            <!-- ... -->
    
            <encoder class="AppBundle\Security\User\WebserviceUser"
                algorithm="bcrypt" />
        </config>
    </srv:container>
    
  • PHP
     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    // app/config/security.php
    use AppBundle\Security\User\WebserviceUser;
    
    $container->loadFromExtension('security', array(
        // ...
    
        'encoders' => array(
            WebserviceUser::class => 'bcrypt',
        ),
        // ...
    ));
    

The value here should correspond with however the passwords were originally encoded when creating your users (however those users were created). When a user submits their password, it’s encoded using this algorithm and the result is compared to the hashed password returned by your getPassword() method.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.