[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

CHANGELOG.md

@@ -10,6 +10,7 @@ CHANGELOG
    erase credentials e.g. using `__serialize()` instead
  * Add ability for voters to explain their vote
  * Add support for voting on closures
+ * Add `OAuth2User` with OAuth2 Access Token Introspection support for `OAuth2TokenHandler`
 
 7.2
 ---

Tests/User/OAuth2UserTest.php

@@ -0,0 +1,51 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\Tests\User;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\Security\Core\User\OAuth2User;
+
+class OAuth2UserTest extends TestCase
+{
+    public function testCannotCreateUserWithoutSubProperty()
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage('The claim "sub" or "username" must be provided.');
+
+        new OAuth2User();
+    }
+
+    public function testCreateFullUserWithAdditionalClaimsUsingPositionalParameters()
+    {
+        $this->assertEquals(new OAuth2User(
+            scope: 'read write dolphin',
+            username: 'jdoe',
+            exp: 1419356238,
+            iat: 1419350238,
+            sub: 'Z5O3upPC88QrAjx00dis',
+            aud: 'https://protected.example.net/resource',
+            iss: 'https://server.example.com/',
+            client_id: 'l238j323ds-23ij4',
+            extension_field: 'twenty-seven'
+        ), new OAuth2User(...[
+            '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',
+        ]));
+    }
+}

User/OAuth2User.php

@@ -0,0 +1,70 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\Security\Core\User;
+
+/**
+ * UserInterface implementation used by the access-token security workflow with an OIDC server.
+ */
+class OAuth2User implements UserInterface
+{
+    public readonly array $additionalClaims;
+
+    public function __construct(
+        private array $roles = ['ROLE_USER'],
+        // Standard Claims (https://datatracker.ietf.org/doc/html/rfc7662#section-2.2)
+        public readonly ?string $scope = null,
+        public readonly ?string $clientId = null,
+        public readonly ?string $username = null,
+        public readonly ?string $tokenType = null,
+        public readonly ?int $exp = null,
+        public readonly ?int $iat = null,
+        public readonly ?int $nbf = null,
+        public readonly ?string $sub = null,
+        public readonly ?string $aud = null,
+        public readonly ?string $iss = null,
+        public readonly ?string $jti = null,
+
+        // Additional Claims ("
+        //    Specific implementations MAY extend this structure with
+        //    their own service-specific response names as top-level members
+        //    of this JSON object.
+        // ")
+        ...$additionalClaims,
+    ) {
+        if ((null === $sub || '' === $sub) && (null === $username || '' === $username)) {
+            throw new \InvalidArgumentException('The claim "sub" or "username" must be provided.');
+        }
+
+        $this->additionalClaims = $additionalClaims['additionalClaims'] ?? $additionalClaims;
+    }
+
+    /**
+     * OIDC or OAuth specs don't have any "role" notion.
+     *
+     * If you want to implement "roles" from your OIDC server,
+     * send a "roles" constructor argument to this object
+     * (e.g.: using a custom UserProvider).
+     */
+    public function getRoles(): array
+    {
+        return $this->roles;
+    }
+
+    public function getUserIdentifier(): string
+    {
+        return (string) ($this->sub ?? $this->username);
+    }
+
+    public function eraseCredentials(): void
+    {
+    }
+}