feat: Add support for device code grant

Author: SimonVanacco

docs/basic-setup.md

@@ -97,14 +97,17 @@ security:
         api_token:
             pattern: ^/token$
             security: false
+        api_device_code:
+            pattern: ^/device-code$
+            security: false
         api:
             pattern: ^/api
             security: true
             stateless: true
             oauth2: true
 ```
 
-* The `api_token` firewall will ensure that anyone can access the `/api/token` endpoint in order to be able to retrieve their access tokens.
+* The `api_token` and `api_device_code` firewall will ensure that anyone can access the `/token` and `/device-code` endpoint respectively in order to be able to retrieve their access tokens or device codes.
 * The `api` firewall will protect all routes prefixed with `/api` and clients will require a valid access token in order to access them.
 
 Basically, any firewall which sets the `oauth2` parameter to `true` will make any routes that match the selected pattern go through our OAuth 2.0 security layer.

docs/device-code-grant.md

@@ -0,0 +1,76 @@
+# Password grant handling
+
+The device code grant type is designed for devices without a browser or with limited input capabilities. In this flow, the user authenticates on another device—like a smartphone or computer—and receives a code to enter on the original device.
+
+Initially, the device sends a request to /device-code with its client ID and scope. The server then returns a device code, a user code, and a verification URL. The user takes the code to a secondary device, opens the verification URL in a browser, and enters the user code.
+
+Meanwhile, the original device continuously polls the /token endpoint with the device code. Once the user approves the request on the secondary device, the token endpoint returns the access token to the polling device.
+
+## Requirements
+
+You need to implement the verification URL yourself and handle the user code input : this bundle does not provide a route or UI for this.
+
+## Example
+
+### Controller
+
+This is a sample Symfony 7 controller to handle the user code input
+
+```php
+<?php
+
+namespace App\Controller;
+
+use League\Bundle\OAuth2ServerBundle\Repository\DeviceCodeRepository;
+use League\OAuth2\Server\Exception\OAuthServerException;
+use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\Form\Extension\Core\Type\SubmitType;
+use Symfony\Component\Form\Extension\Core\Type\TextType;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Attribute\Route;
+
+class DeviceCodeController extends AbstractController
+{
+
+    public function __construct(
+        private readonly DeviceCodeRepository $deviceCodeRepository
+    ) {
+    }
+
+    #[Route(path: '/verify-device', name: 'app_verify_device', methods: ['GET', 'POST'])]
+    public function verifyDevice(
+        Request $request
+    ): Response {
+        $form = $this->createFormBuilder()
+                     ->add('userCode', TextType::class, [
+                         'required' => true,
+                     ])
+                     ->getForm()
+                     ->handleRequest($request);
+
+        if ($form->isSubmitted() && $form->isValid()) {
+            try {
+                $this->deviceCodeRepository->approveDeviceCode($form->get('userCode')->getData(), $this->getUser()->getId());
+                // Device code approved, show success message to user
+            } catch (OAuthServerException $e) {
+                // Handle exception (invalid code or missing user ID)
+            }
+        }
+
+        return $this->render(
+            'verify_device.html.twig',
+            ['form' => $form]
+        );
+    }
+
+}
+```
+
+### Configuration
+
+```yaml
+league_oauth2_server:
+    authorization_server:
+        device_code_verification_uri: 'https://your-domain.com/verify-device'
+```

docs/index.md

@@ -6,7 +6,7 @@ For implementation into Symfony projects, please see [bundle documentation](basi
 
 ## Features
 
-* API endpoint for client authorization and token issuing
+* API endpoint for client authorization, device code and token issuing
 * Configurable client and token persistance (includes [Doctrine](https://www.doctrine-project.org/) support)
 * Integration with Symfony's [Security](https://symfony.com/doc/current/security.html) layer
 
@@ -75,6 +75,15 @@ For implementation into Symfony projects, please see [bundle documentation](basi
             # Whether to enable access token saving to persistence layer (default to true)
             persist_access_token: true
 
+            # Whether to enable the device code grant
+            enable_device_code_grant: true
+
+            # The full URI the user will need to visit to enter the user code
+            device_code_verification_uri: ''
+
+            # How soon (in seconds) can the device code be used to poll for the access token without being throttled
+            device_code_polling_interval: 5
+
         resource_server:      # Required
 
             # Full path to the public key file

src/Command/ClearExpiredTokensCommand.php

@@ -6,6 +6,7 @@
 
 use League\Bundle\OAuth2ServerBundle\Manager\AccessTokenManagerInterface;
 use League\Bundle\OAuth2ServerBundle\Manager\AuthorizationCodeManagerInterface;
+use League\Bundle\OAuth2ServerBundle\Manager\DeviceCodeManagerInterface;
 use League\Bundle\OAuth2ServerBundle\Manager\RefreshTokenManagerInterface;
 use Symfony\Component\Console\Attribute\AsCommand;
 use Symfony\Component\Console\Command\Command;
@@ -32,16 +33,23 @@ final class ClearExpiredTokensCommand extends Command
      */
     private $authorizationCodeManager;
 
+    /**
+     * @var DeviceCodeManagerInterface
+     */
+    private $deviceCodeManager;
+
     public function __construct(
         AccessTokenManagerInterface $accessTokenManager,
         RefreshTokenManagerInterface $refreshTokenManager,
         AuthorizationCodeManagerInterface $authorizationCodeManager,
+        DeviceCodeManagerInterface $deviceCodeManager,
     ) {
         parent::__construct();
 
         $this->accessTokenManager = $accessTokenManager;
         $this->refreshTokenManager = $refreshTokenManager;
         $this->authorizationCodeManager = $authorizationCodeManager;
+        $this->deviceCodeManager = $deviceCodeManager;
     }
 
     protected function configure(): void
@@ -66,6 +74,12 @@ protected function configure(): void
                 InputOption::VALUE_NONE,
                 'Clear expired auth codes.'
             )
+            ->addOption(
+                'device-codes',
+                'dc',
+                InputOption::VALUE_NONE,
+                'Clear expired device codes.'
+            )
         ;
     }
 
@@ -76,11 +90,13 @@ protected function execute(InputInterface $input, OutputInterface $output): int
         $clearExpiredAccessTokens = $input->getOption('access-tokens');
         $clearExpiredRefreshTokens = $input->getOption('refresh-tokens');
         $clearExpiredAuthCodes = $input->getOption('auth-codes');
+        $clearExpiredDeviceCodes = $input->getOption('device-codes');
 
-        if (!$clearExpiredAccessTokens && !$clearExpiredRefreshTokens && !$clearExpiredAuthCodes) {
+        if (!$clearExpiredAccessTokens && !$clearExpiredRefreshTokens && !$clearExpiredAuthCodes && !$clearExpiredDeviceCodes) {
             $this->clearExpiredAccessTokens($io);
             $this->clearExpiredRefreshTokens($io);
             $this->clearExpiredAuthCodes($io);
+            $this->clearExpiredDeviceCodes($io);
 
             return 0;
         }
@@ -97,6 +113,10 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             $this->clearExpiredAuthCodes($io);
         }
 
+        if ($clearExpiredDeviceCodes) {
+            $this->clearExpiredDeviceCodes($io);
+        }
+
         return 0;
     }
 
@@ -129,4 +149,14 @@ private function clearExpiredAuthCodes(SymfonyStyle $io): void
             1 === $numOfClearedAuthCodes ? '' : 's'
         ));
     }
+
+    private function clearExpiredDeviceCodes(SymfonyStyle $io): void
+    {
+        $numberOfClearedDeviceCodes = $this->deviceCodeManager->clearExpired();
+        $io->success(\sprintf(
+            'Cleared %d expired device code%s.',
+            $numberOfClearedDeviceCodes,
+            1 === $numberOfClearedDeviceCodes ? '' : 's'
+        ));
+    }
 }

src/Controller/DeviceCodeController.php

@@ -0,0 +1,96 @@
+<?php
+
+declare(strict_types=1);
+
+namespace League\Bundle\OAuth2ServerBundle\Controller;
+
+use League\Bundle\OAuth2ServerBundle\Converter\UserConverterInterface;
+use League\Bundle\OAuth2ServerBundle\Event\AuthorizationRequestResolveEventFactory;
+use League\Bundle\OAuth2ServerBundle\Manager\ClientManagerInterface;
+use League\Bundle\OAuth2ServerBundle\Model\AbstractClient;
+use League\Bundle\OAuth2ServerBundle\OAuth2Events;
+use League\OAuth2\Server\AuthorizationServer;
+use League\OAuth2\Server\Exception\OAuthServerException;
+use Psr\Http\Message\ResponseFactoryInterface;
+use Symfony\Bridge\PsrHttpMessage\HttpFoundationFactoryInterface;
+use Symfony\Bridge\PsrHttpMessage\HttpMessageFactoryInterface;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;
+
+final class DeviceCodeController
+{
+    /**
+     * @var AuthorizationServer
+     */
+    private $server;
+
+    /**
+     * @var EventDispatcherInterface
+     */
+    private $eventDispatcher;
+
+    /**
+     * @var AuthorizationRequestResolveEventFactory
+     */
+    private $eventFactory;
+
+    /**
+     * @var UserConverterInterface
+     */
+    private $userConverter;
+
+    /**
+     * @var ClientManagerInterface
+     */
+    private $clientManager;
+
+    /**
+     * @var HttpMessageFactoryInterface
+     */
+    private $httpMessageFactory;
+
+    /**
+     * @var HttpFoundationFactoryInterface
+     */
+    private $httpFoundationFactory;
+
+    /**
+     * @var ResponseFactoryInterface
+     */
+    private $responseFactory;
+
+    public function __construct(
+        AuthorizationServer $server,
+        EventDispatcherInterface $eventDispatcher,
+        AuthorizationRequestResolveEventFactory $eventFactory,
+        UserConverterInterface $userConverter,
+        ClientManagerInterface $clientManager,
+        HttpMessageFactoryInterface $httpMessageFactory,
+        HttpFoundationFactoryInterface $httpFoundationFactory,
+        ResponseFactoryInterface $responseFactory,
+    ) {
+        $this->server = $server;
+        $this->eventDispatcher = $eventDispatcher;
+        $this->eventFactory = $eventFactory;
+        $this->userConverter = $userConverter;
+        $this->clientManager = $clientManager;
+        $this->httpMessageFactory = $httpMessageFactory;
+        $this->httpFoundationFactory = $httpFoundationFactory;
+        $this->responseFactory = $responseFactory;
+    }
+
+    public function indexAction(Request $request): Response
+    {
+        $serverRequest = $this->httpMessageFactory->createRequest($request);
+        $serverResponse = $this->responseFactory->createResponse();
+
+        try {
+            $response = $this->server->respondToDeviceAuthorizationRequest($serverRequest, $serverResponse);
+        } catch (OAuthServerException $e) {
+            $response = $e->generateHttpResponse($serverResponse);
+        }
+
+        return $this->httpFoundationFactory->createResponse($response);
+    }
+}

src/DependencyInjection/Configuration.php

@@ -79,6 +79,11 @@ private function createAuthorizationServerNode(): NodeDefinition
                     ->cannotBeEmpty()
                     ->defaultValue('PT10M')
                 ->end()
+                ->scalarNode('device_code_ttl')
+                    ->info("How long the issued device code should be valid for.\nThe value should be a valid interval: http://php.net/manual/en/dateinterval.construct.php#refsect1-dateinterval.construct-parameters")
+                    ->cannotBeEmpty()
+                    ->defaultValue('PT10M')
+                ->end()
                 ->booleanNode('enable_client_credentials_grant')
                     ->info('Whether to enable the client credentials grant')
                     ->defaultTrue()
@@ -111,6 +116,19 @@ private function createAuthorizationServerNode(): NodeDefinition
                     ->info('Define a custom ResponseType')
                     ->defaultValue(null)
                 ->end()
+                ->booleanNode('enable_device_code_grant')
+                    ->info('Whether to enable the device code grant')
+                    ->defaultTrue()
+                ->end()
+                ->scalarNode('device_code_verification_uri')
+                    ->info('The full URI the user will need to visit to enter the user code')
+                    ->defaultValue('')
+                ->end()
+                ->scalarNode('device_code_polling_interval')
+                    ->info('How soon (in seconds) can the device code be used to poll for the access token without being throttled')
+                    ->defaultValue(5)
+                ->end()
+
             ->end()
         ;
 
@@ -223,6 +241,11 @@ private function createPersistenceNode(): NodeDefinition
                             ->cannotBeEmpty()
                             ->isRequired()
                         ->end()
+                        ->scalarNode('device_code_manager')
+                            ->info('Service id of the custom device code manager')
+                            ->cannotBeEmpty()
+                            ->isRequired()
+                        ->end()
                         ->scalarNode('credentials_revoker')
                             ->info('Service id of the custom credentials revoker')
                             ->cannotBeEmpty()