How to Create a custom Authentication Provider

How to Create a custom Authentication Provider

Caution

Creating a custom authentication system is hard, and almost definitely not needed. Instead, see Custom Authentication System with Guard (API Token Example) for a simple way to create an authentication system you will love. Do not keep reading unless you want to learn the lowest level details of authentication.

Symfony provides support for the most common authentication mechanisms. However, your app may need to integrated with some proprietary single-sign-on system or some legacy authentication mechanism. In those cases you could create a custom authentication provider. This article discusses the core classes involved in the authentication process, and how to implement a custom authentication provider. Because authentication and authorization are separate concepts, this extension will be user-provider agnostic, and will function with your application’s user providers, may they be based in memory, a database, or wherever else you choose to store them.

Meet WSSE

The following article demonstrates how to create a custom authentication provider for WSSE authentication. The security protocol for WSSE provides several security benefits:

  1. Username / Password encryption
  2. Safe guarding against replay attacks
  3. No web server configuration required

WSSE is very useful for the securing of web services, may they be SOAP or REST.

There is plenty of great documentation on WSSE, but this article will focus not on the security protocol, but rather the manner in which a custom protocol can be added to your Symfony application. The basis of WSSE is that a request header is checked for encrypted credentials, verified using a timestamp and nonce, and authenticated for the requested user using a password digest.

Note

WSSE also supports application key validation, which is useful for web services, but is outside the scope of this article.

The Token

The role of the token in the Symfony security context is an important one. A token represents the user authentication data present in the request. Once a request is authenticated, the token retains the user’s data, and delivers this data across the security context. First, you’ll create your token class. This will allow the passing of all relevant information to your authentication provider:

  1. // src/Security/Authentication/Token/WsseUserToken.php
  2. namespace App\Security\Authentication\Token;
  4. use Symfony\Component\Security\Core\Authentication\Token\AbstractToken;
  6. class WsseUserToken extends AbstractToken
  7. {
  8.     public $created;
  9.     public $digest;
  10.     public $nonce;
  12.     public function __construct(array $roles = [])
  13.     {
  14.         parent::__construct($roles);
  16.         // If the user has roles, consider it authenticated
  17.         $this->setAuthenticated(count($roles) > 0);
  18.     }
  20.     public function getCredentials(): string
  21.     {
  22.         return '';
  23.     }
  24. }

Note

The WsseUserToken class extends the Security component’s Symfony\Component\Security\Core\Authentication\Token\AbstractToken class, which provides basic token functionality. Implement the Symfony\Component\Security\Core\Authentication\Token\TokenInterface on any class to use as a token.

The Listener

Next, you need a listener to listen on the firewall. The listener is responsible for fielding requests to the firewall and calling the authentication provider. Listener is a callable, so you have to implement an __invoke() method. A security listener should handle the Symfony\Component\HttpKernel\Event\RequestEvent event, and set an authenticated token in the token storage if successful:

  1. // src/Security/Firewall/WsseListener.php
  2. namespace App\Security\Firewall;
  4. use App\Security\Authentication\Token\WsseUserToken;
  5. use Symfony\Component\HttpFoundation\Response;
  6. use Symfony\Component\HttpKernel\Event\RequestEvent;
  7. use Symfony\Component\Security\Core\Authentication\AuthenticationManagerInterface;
  8. use Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface;
  9. use Symfony\Component\Security\Core\Exception\AuthenticationException;
  11. class WsseListener
  12. {
  13.     protected $tokenStorage;
  14.     protected $authenticationManager;
  16.     public function __construct(TokenStorageInterface $tokenStorage, AuthenticationManagerInterface $authenticationManager)
  17.     {
  18.         $this->tokenStorage = $tokenStorage;
  19.         $this->authenticationManager = $authenticationManager;
  20.     }
  22.     public function __invoke(RequestEvent $event): void
  23.     {
  24.         $request = $event->getRequest();
  26.         $wsseRegex = '/UsernameToken Username="(?P<username>[^"]+)", PasswordDigest="(?P<digest>[^"]+)", Nonce="(?P<nonce>[a-zA-Z0-9+\/]+={0,2})", Created="(?P<created>[^"]+)"/';
  27.         if (!$request->headers->has('x-wsse') || 1 !== preg_match($wsseRegex, $request->headers->get('x-wsse'), $matches)) {
  28.             return;
  29.         }
  31.         $token = new WsseUserToken();
  32.         $token->setUser($matches['username']);
  34.         $token->digest  = $matches['digest'];
  35.         $token->nonce   = $matches['nonce'];
  36.         $token->created = $matches['created'];
  38.         try {
  39.             $authToken = $this->authenticationManager->authenticate($token);
  40.             $this->tokenStorage->setToken($authToken);
  42.             return;
  43.         } catch (AuthenticationException $failed) {
  44.             // ... you might log something here
  46.             // To deny the authentication clear the token. This will redirect to the login page.
  47.             // Make sure to only clear your token, not those of other authentication listeners.
  48.             // $token = $this->tokenStorage->getToken();
  49.             // if ($token instanceof WsseUserToken && $this->providerKey === $token->getProviderKey()) {
  50.             //     $this->tokenStorage->setToken(null);
  51.             // }
  52.             // return;
  53.         }
  55.         // By default deny authorization
  56.         $response = new Response();
  57.         $response->setStatusCode(Response::HTTP_FORBIDDEN);
  58.         $event->setResponse($response);
  59.     }
  60. }

This listener checks the request for the expected X-WSSE header, matches the value returned for the expected WSSE information, creates a token using that information, and passes the token on to the authentication manager. If the proper information is not provided, or the authentication manager throws an Symfony\Component\Security\Core\Exception\AuthenticationException, a 401 Response is returned.

Note

A class not used above, the Symfony\Component\Security\Http\Firewall\AbstractAuthenticationListener class, is a very useful base class which provides commonly needed functionality for security extensions. This includes maintaining the token in the session, providing success / failure handlers, login form URLs, and more. As WSSE does not require maintaining authentication sessions or login forms, it won’t be used for this example.

Note

Returning prematurely from the listener is relevant only if you want to chain authentication providers (for example to allow anonymous users). If you want to forbid access to anonymous users and have a 404 error, you should set the status code of the response before returning.

The Authentication Provider

The authentication provider will do the verification of the WsseUserToken. Namely, the provider will verify the Created header value is valid within five minutes, the Nonce header value is unique within five minutes, and the PasswordDigest header value matches with the user’s password:

  1. // src/Security/Authentication/Provider/WsseProvider.php
  2. namespace App\Security\Authentication\Provider;
  4. use App\Security\Authentication\Token\WsseUserToken;
  5. use Psr\Cache\CacheItemPoolInterface;
  6. use Symfony\Component\Security\Core\Authentication\Provider\AuthenticationProviderInterface;
  7. use Symfony\Component\Security\Core\Authentication\Token\TokenInterface;
  8. use Symfony\Component\Security\Core\Exception\AuthenticationException;
  9. use Symfony\Component\Security\Core\User\UserProviderInterface;
  11. class WsseProvider implements AuthenticationProviderInterface
  12. {
  13.     private $userProvider;
  14.     private $cachePool;
  16.     public function __construct(UserProviderInterface $userProvider, CacheItemPoolInterface $cachePool)
  17.     {
  18.         $this->userProvider = $userProvider;
  19.         $this->cachePool = $cachePool;
  20.     }
  22.     public function authenticate(TokenInterface $token): WsseUserToken
  23.     {
  24.         $user = $this->userProvider->loadUserByUsername($token->getUsername());
  26.         if ($user && $this->validateDigest($token->digest, $token->nonce, $token->created, $user->getPassword())) {
  27.             $authenticatedToken = new WsseUserToken($user->getRoles());
  28.             $authenticatedToken->setUser($user);
  30.             return $authenticatedToken;
  31.         }
  33.         throw new AuthenticationException('The WSSE authentication failed.');
  34.     }
  36.     /**
  37.      * This function is specific to Wsse authentication and is only used to help this example
  38.      *
  39.      * For more information specific to the logic here, see
  40.      * https://github.com/symfony/symfony-docs/pull/3134#issuecomment-27699129
  41.      */
  42.     protected function validateDigest($digest, $nonce, $created, $secret): bool
  43.     {
  44.         // Check created time is not in the future
  45.         if (strtotime($created) > time()) {
  46.             return false;
  47.         }
  49.         // Expire timestamp after 5 minutes
  50.         if (time() - strtotime($created) > 300) {
  51.             return false;
  52.         }
  54.         // Try to fetch the cache item from pool
  55.         $cacheItem = $this->cachePool->getItem(md5($nonce));
  57.         // Validate that the nonce is *not* in cache
  58.         // if it is, this could be a replay attack
  59.         if ($cacheItem->isHit()) {
  60.             // In a real world application you should throw a custom
  61.             // exception extending the AuthenticationException
  62.             throw new AuthenticationException('Previously used nonce detected');
  63.         }
  65.         // Store the item in cache for 5 minutes
  66.         $cacheItem->set(null)->expiresAfter(300);
  67.         $this->cachePool->save($cacheItem);
  69.         // Validate Secret
  70.         $expected = base64_encode(sha1(base64_decode($nonce).$created.$secret, true));
  72.         return hash_equals($expected, $digest);
  73.     }
  75.     public function supports(TokenInterface $token): bool
  76.     {
  77.         return $token instanceof WsseUserToken;
  78.     }
  79. }

Note

The Symfony\Component\Security\Core\Authentication\Provider\AuthenticationProviderInterface requires an authenticate() method on the user token, and a supports() method, which tells the authentication manager whether or not to use this provider for the given token. In the case of multiple providers, the authentication manager will then move to the next provider in the list.

The Factory

You have created a custom token, custom listener, and custom provider. Now you need to tie them all together. How do you make a unique provider available for every firewall? The answer is by using a factory. A factory is where you hook into the Security component, telling it the name of your provider and any configuration options available for it. First, you must create a class which implements Symfony\Bundle\SecurityBundle\DependencyInjection\Security\Factory\SecurityFactoryInterface:

  1. // src/DependencyInjection/Security/Factory/WsseFactory.php
  2. namespace App\DependencyInjection\Security\Factory;
  4. use App\Security\Authentication\Provider\WsseProvider;
  5. use App\Security\Firewall\WsseListener;
  6. use Symfony\Bundle\SecurityBundle\DependencyInjection\Security\Factory\SecurityFactoryInterface;
  7. use Symfony\Component\Config\Definition\Builder\NodeDefinition;
  8. use Symfony\Component\DependencyInjection\ChildDefinition;
  9. use Symfony\Component\DependencyInjection\ContainerBuilder;
  10. use Symfony\Component\DependencyInjection\Reference;
  12. class WsseFactory implements SecurityFactoryInterface
  13. {
  14.     public function create(ContainerBuilder $container, $id, $config, $userProvider, $defaultEntryPoint): array
  15.     {
  16.         $providerId = 'security.authentication.provider.wsse.'.$id;
  17.         $container
  18.             ->setDefinition($providerId, new ChildDefinition(WsseProvider::class))
  19.             ->setArgument(0, new Reference($userProvider))
  20.         ;
  22.         $listenerId = 'security.authentication.listener.wsse.'.$id;
  23.         $container->setDefinition($listenerId, new ChildDefinition(WsseListener::class));
  25.         return [$providerId, $listenerId, $defaultEntryPoint];
  26.     }
  28.     public function getPosition(): string
  29.     {
  30.         return 'pre_auth';
  31.     }
  33.     public function getKey(): string
  34.     {
  35.         return 'wsse';
  36.     }
  38.     public function addConfiguration(NodeDefinition $node): void
  39.     {
  40.     }
  41. }

The Symfony\Bundle\SecurityBundle\DependencyInjection\Security\Factory\SecurityFactoryInterface requires the following methods:

create()

Method which adds the listener and authentication provider to the DI container for the appropriate security context.

getPosition()

Returns when the provider should be called. This can be one of pre_auth, form, http or remember_me.

getKey()

Method which defines the configuration key used to reference the provider in the firewall configuration.

addConfiguration()

Method which is used to define the configuration options underneath the configuration key in your security configuration. Setting configuration options are explained later in this article.

Note

A class not used in this example, Symfony\Bundle\SecurityBundle\DependencyInjection\Security\Factory\AbstractFactory, is a very useful base class which provides commonly needed functionality for security factories. It may be useful when defining an authentication provider of a different type.

Now that you have created a factory class, the wsse key can be used as a firewall in your security configuration.

Note

You may be wondering “why do you need a special factory class to add listeners and providers to the dependency injection container?”. This is a very good question. The reason is you can use your firewall multiple times, to secure multiple parts of your application. Because of this, each time your firewall is used, a new service is created in the DI container. The factory is what creates these new services.

Configuration

It’s time to see your authentication provider in action. You will need to do a few things in order to make this work. The first thing is to add the services above to the DI container. Your factory class above makes reference to service ids that may not exist yet: App\Security\Authentication\Provider\WsseProvider and App\Security\Firewall\WsseListener. It’s time to define those services.

  • YAML

    1. # config/services.yaml
    2. services:
    3.     # ...
    5.     App\Security\Authentication\Provider\WsseProvider:
    6.         arguments:
    7.             $cachePool: '@cache.app'
    9.     App\Security\Firewall\WsseListener:
    10.         arguments: ['@security.token_storage', '@security.authentication.manager']

  • XML

    1. <!-- config/services.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <container xmlns="http://symfony.com/schema/dic/services"
    4.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    5.     xsi:schemaLocation="http://symfony.com/schema/dic/services https://symfony.com/schema/dic/services/services-1.0.xsd">
    7.     <services>
    8.         <service id="App\Security\Authentication\Provider\WsseProvider">
    9.             <argument key="$cachePool" type="service" id="cache.app"></argument>
    10.         </service>
    12.         <service id="App\Security\Firewall\WsseListener">
    13.             <argument type="service" id="security.token_storage"/>
    14.             <argument type="service" id="security.authentication.manager"/>
    15.         </service>
    16.     </services>
    17. </container>

  • PHP

    1. // config/services.php
    2. namespace Symfony\Component\DependencyInjection\Loader\Configurator;
    4. use App\Security\Authentication\Provider\WsseProvider;
    5. use App\Security\Firewall\WsseListener;
    6. use Symfony\Component\DependencyInjection\Reference;
    8. return function(ContainerConfigurator $configurator) {
    9.     $services = $configurator->services();
    11.     $services->set(WsseProvider::class)
    12.         ->arg('$cachePool', ref('cache.app'))
    13.     ;
    15.     $services->set(WsseListener::class)
    16.         ->args([
    17.             ref('security.token_storage'),
    18.             ref('security.authentication.manager'),
    19.         ])
    20.     ;
    21. };

Now that your services are defined, tell your security context about your factory in the kernel:

  1. // src/Kernel.php
  2. namespace App;
  4. use App\DependencyInjection\Security\Factory\WsseFactory;
  5. // ...
  7. class Kernel extends BaseKernel
  8. {
  9.     public function build(ContainerBuilder $container): void
  10.     {
  11.         $extension = $container->getExtension('security');
  12.         $extension->addSecurityListenerFactory(new WsseFactory());
  13.     }
  15.     // ...
  16. }

You are finished! You can now define parts of your app as under WSSE protection.

  • YAML

    1. # config/packages/security.yaml
    2. security:
    3.     # ...
    5.     firewalls:
    6.         wsse_secured:
    7.             pattern:   ^/api/
    8.             stateless: true
    9.             wsse:      true

  • XML

    1. <!-- config/packages/security.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <srv:container xmlns="http://symfony.com/schema/dic/security"
    4.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    5.     xmlns:srv="http://symfony.com/schema/dic/services"
    6.     xsi:schemaLocation="http://symfony.com/schema/dic/services
    7.         https://symfony.com/schema/dic/services/services-1.0.xsd">
    9.     <config>
    10.         <!-- ... -->
    12.         <firewall
    13.             name="wsse_secured"
    14.             pattern="^/api/"
    15.             stateless="true"
    16.             wsse="true"
    17.         />
    18.     </config>
    19. </srv:container>

  • PHP

    1. // config/packages/security.php
    2. $container->loadFromExtension('security', [
    3.     // ...
    5.     'firewalls' => [
    6.         'wsse_secured' => [
    7.             'pattern'   => '^/api/',
    8.             'stateless' => true,
    9.             'wsse'      => true,
    10.         ],
    11.     ],
    12. ]);

Congratulations! You have written your very own custom security authentication provider!

A little Extra

How about making your WSSE authentication provider a bit more exciting? The possibilities are endless. Why don’t you start by adding some sparkle to that shine?

Configuration

You can add custom options under the wsse key in your security configuration. For instance, the time allowed before expiring the Created header item, by default, is 5 minutes. Make this configurable, so different firewalls can have different timeout lengths.

You will first need to edit WsseFactory and define the new option in the addConfiguration() method:

  1. // src/DependencyInjection/Security/Factory/WsseFactory.php
  2. namespace App\DependencyInjection\Security\Factory;
  4. // ...
  6. class WsseFactory implements SecurityFactoryInterface
  7. {
  8.     // ...
  10.     public function addConfiguration(NodeDefinition $node): void
  11.     {
  12.         $node
  13.             ->children()
  14.                 ->scalarNode('lifetime')->defaultValue(300)
  15.             ->end();
  16.     }
  17. }

Now, in the create() method of the factory, the $config argument will contain a lifetime key, set to 5 minutes (300 seconds) unless otherwise set in the configuration. Pass this argument to your authentication provider in order to put it to use:

  1. // src/DependencyInjection/Security/Factory/WsseFactory.php
  2. namespace App\DependencyInjection\Security\Factory;
  4. use App\Security\Authentication\Provider\WsseProvider;
  6. class WsseFactory implements SecurityFactoryInterface
  7. {
  8.     public function create(ContainerBuilder $container, $id, $config, $userProvider, $defaultEntryPoint): array
  9.     {
  10.         $providerId = 'security.authentication.provider.wsse.'.$id;
  11.         $container
  12.             ->setDefinition($providerId, new ChildDefinition(WsseProvider::class))
  13.             ->setArgument(0, new Reference($userProvider))
  14.             ->setArgument(2, $config['lifetime']);
  15.         // ...
  16.     }
  18.     // ...
  19. }

Note

The WsseProvider class will also now need to accept a third constructor argument - the lifetime - which it should use instead of the hard-coded 300 seconds. This step is not shown here.

The lifetime of each WSSE request is now configurable, and can be set to any desirable value per firewall.

  • YAML

    1. # config/packages/security.yaml
    2. security:
    3.     # ...
    5.     firewalls:
    6.         wsse_secured:
    7.             pattern:   ^/api/
    8.             stateless: true
    9.             wsse:      { lifetime: 30 }

  • XML

    1. <!-- config/packages/security.xml -->
    2. <?xml version="1.0" encoding="UTF-8" ?>
    3. <srv:container xmlns="http://symfony.com/schema/dic/security"
    4.     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    5.     xmlns:srv="http://symfony.com/schema/dic/services"
    6.     xsi:schemaLocation="http://symfony.com/schema/dic/services
    7.         https://symfony.com/schema/dic/services/services-1.0.xsd">
    9.     <config>
    10.         <!-- ... -->
    12.         <firewall name="wsse_secured" pattern="^/api/" stateless="true">
    13.             <wsse lifetime="30"/>
    14.         </firewall>
    15.     </config>
    16. </srv:container>

  • PHP

    1. // config/packages/security.php
    2. $container->loadFromExtension('security', [
    3.     // ...
    5.     'firewalls' => [
    6.         'wsse_secured' => [
    7.             'pattern'   => '^/api/',
    8.             'stateless' => true,
    9.             'wsse'      => [
    10.                 'lifetime' => 30,
    11.             ],
    12.         ],
    13.     ],
    14. ]);

The rest is up to you! Any relevant configuration items can be defined in the factory and consumed or passed to the other classes in the container.

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