[Security] OAuth2 Introspection Endpoint (RFC7662)

In addition to the excellent work of @vincentchalamon #48272, this PR allows getting the data from the OAuth2 Introspection Endpoint. This endpoint is defined in the [RFC7662](https://datatracker.ietf.org/doc/html/rfc7662). It returns the following information that is used to retrieve the user:

* If the access token is active
* A set of claims that are similar to the OIDC one, including the `sub` or the `username`.

Author: Spomky

AccessToken/OAuth2/Oauth2TokenHandler.php

@@ -0,0 +1,100 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Http\AccessToken\OAuth2;
+
+use Psr\Log\LoggerInterface;
+use Symfony\Component\Security\Core\Exception\AuthenticationException;
+use Symfony\Component\Security\Core\Exception\BadCredentialsException;
+use Symfony\Component\Security\Core\User\OAuth2User;
+use Symfony\Component\Security\Http\AccessToken\AccessTokenHandlerInterface;
+use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+use function Symfony\Component\String\u;
+
+/**
+ * The token handler validates the token on the authorization server and the Introspection Endpoint.
+ *
+ * @see https://tools.ietf.org/html/rfc7662
+ *
+ * @internal
+ */
+final class Oauth2TokenHandler implements AccessTokenHandlerInterface
+{
+    public function __construct(
+        private readonly HttpClientInterface $client,
+        private readonly ?LoggerInterface $logger = null,
+    ) {
+    }
+
+    public function getUserBadgeFrom(string $accessToken): UserBadge
+    {
+        try {
+            // Call the Authorization server to retrieve the resource owner details
+            // If the token is invalid or expired, the Authorization server will return an error
+            $claims = $this->client->request('POST', '', [
+                'body' => [
+                    'token' => $accessToken,
+                    'token_type_hint' => 'access_token',
+                ],
+            ])->toArray();
+
+            $sub = $claims['sub'] ?? null;
+            $username = $claims['username'] ?? null;
+            if (!$sub && !$username) {
+                throw new BadCredentialsException('"sub" and "username" claims not found on the authorization server response. At least one is required.');
+            }
+            $active = $claims['active'] ?? false;
+            if (!$active) {
+                throw new BadCredentialsException('The claim "active" was not found on the authorization server response or is set to false.');
+            }
+
+            return new UserBadge($sub ?? $username, fn () => $this->createUser($claims), $claims);
+        } catch (AuthenticationException $e) {
+            $this->logger?->error('An error occurred on the authorization server.', [
+                'error' => $e->getMessage(),
+                'trace' => $e->getTraceAsString(),
+            ]);
+
+            throw new BadCredentialsException('Invalid credentials.', $e->getCode(), $e);
+        }
+    }
+
+    private function createUser(array $claims): OAuth2User
+    {
+        if (!\function_exists(\Symfony\Component\String\u::class)) {
+            throw new \LogicException('You cannot use the "OAuth2TokenHandler" since the String component is not installed. Try running "composer require symfony/string".');
+        }
+
+        foreach ($claims as $claim => $value) {
+            unset($claims[$claim]);
+            if ('' === $value || null === $value) {
+                continue;
+            }
+            $claims[u($claim)->camel()->toString()] = $value;
+        }
+
+        if ('' !== ($claims['updatedAt'] ?? '')) {
+            $claims['updatedAt'] = (new \DateTimeImmutable())->setTimestamp($claims['updatedAt']);
+        }
+
+        if ('' !== ($claims['emailVerified'] ?? '')) {
+            $claims['emailVerified'] = (bool) $claims['emailVerified'];
+        }
+
+        if ('' !== ($claims['phoneNumberVerified'] ?? '')) {
+            $claims['phoneNumberVerified'] = (bool) $claims['phoneNumberVerified'];
+        }
+
+        return new OAuth2User(...$claims);
+    }
+}

CHANGELOG.md

@@ -9,6 +9,7 @@ CHANGELOG
  * Add argument `$identifierNormalizer` to `UserBadge::__construct()` to allow normalizing the identifier
  * Support hashing the hashed password using crc32c when putting the user in the session
  * Add support for closures in `#[IsGranted]`
+ * Add `OAuth2TokenHandler` with OAuth2 Token Introspection support for `AccessTokenAuthenticator`
 
 7.2
 ---

Tests/AccessToken/OAuth2/OAuth2TokenHandlerTest.php

@@ -0,0 +1,52 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Http\Tests\AccessToken\OAuth2;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\HttpClient\MockHttpClient;
+use Symfony\Component\HttpClient\Response\MockResponse;
+use Symfony\Component\Security\Core\User\OAuth2User;
+use Symfony\Component\Security\Http\AccessToken\OAuth2\Oauth2TokenHandler;
+use Symfony\Component\Security\Http\Authenticator\Passport\Badge\UserBadge;
+
+class OAuth2TokenHandlerTest extends TestCase
+{
+    public static function testGetsUserIdentifierFromOAuth2ServerResponse(): void
+    {
+        $accessToken = 'a-secret-token';
+        $claims = [
+            'active' => true,
+            'client_id' => 'l238j323ds-23ij4',
+            'username' => 'jdoe',
+            'scope' => 'read write dolphin',
+            'sub' => 'Z5O3upPC88QrAjx00dis',
+            'aud' => 'https://protected.example.net/resource',
+            'iss' => 'https://server.example.com/',
+            'exp' => 1419356238,
+            'iat' => 1419350238,
+            'extension_field' => 'twenty-seven',
+        ];
+        $expectedUser = new OAuth2User(...$claims);
+
+        $client = new MockHttpClient([
+            new MockResponse(json_encode($claims, \JSON_THROW_ON_ERROR)),
+        ]);
+
+        $userBadge = (new Oauth2TokenHandler($client))->getUserBadgeFrom($accessToken);
+        $actualUser = $userBadge->getUserLoader()();
+
+        self::assertEquals(new UserBadge('Z5O3upPC88QrAjx00dis', fn () => $expectedUser, $claims), $userBadge);
+        self::assertInstanceOf(OAuth2User::class, $actualUser);
+        self::assertSame($claims, $userBadge->getAttributes());
+        self::assertSame($claims['sub'], $actualUser->getUserIdentifier());
+    }
+}