Add introspection implementation

README.md

@@ -24,6 +24,7 @@ The following RFCs are implemented:
 * [RFC6750 " The OAuth 2.0 Authorization Framework: Bearer Token Usage"](https://tools.ietf.org/html/rfc6750)
 * [RFC7519 "JSON Web Token (JWT)"](https://tools.ietf.org/html/rfc7519)
 * [RFC7636 "Proof Key for Code Exchange by OAuth Public Clients"](https://tools.ietf.org/html/rfc7636)
+* [RFC7662 "OAuth 2.0 Token Introspection"](https://tools.ietf.org/html/rfc7662)
 
 This library was created by Alex Bilbie. Find him on Twitter at [@alexbilbie](https://twitter.com/alexbilbie).
 

examples/public/introspect.php

@@ -0,0 +1,59 @@
+<?php
+
+use League\OAuth2\Server\AuthorizationServer;
+use League\OAuth2\Server\Exception\OAuthServerException;
+use OAuth2ServerExamples\Repositories\AccessTokenRepository;
+use OAuth2ServerExamples\Repositories\ClientRepository;
+use OAuth2ServerExamples\Repositories\ScopeRepository;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+use Slim\App;
+
+include __DIR__ . '/../vendor/autoload.php';
+
+$app = new App([
+    // Add the authorization server to the DI container
+    AuthorizationServer::class => function () {
+
+        // Setup the authorization server
+        $server = new AuthorizationServer(
+            new ClientRepository(),                 // instance of ClientRepositoryInterface
+            new AccessTokenRepository(),            // instance of AccessTokenRepositoryInterface
+            new ScopeRepository(),                  // instance of ScopeRepositoryInterface
+            'file://' . __DIR__ . '/../private.key',    // path to private key
+            'lxZFUEsBCJ2Yb14IF2ygAHI5N4+ZAUXXaSeeJm6+twsUmIen'      // encryption key
+        );
+
+        return $server;
+    },
+]);
+
+$app->post(
+    '/introspect',
+    function (ServerRequestInterface $request, ResponseInterface $response) use ($app) {
+
+        /* @var \League\OAuth2\Server\AuthorizationServer $server */
+        $server = $app->getContainer()->get(AuthorizationServer::class);
+
+        try {
+            // Validate the given introspect request
+            $server->validateIntrospectionRequest($request);
+
+            // Try to respond to the introspection request
+            return $server->respondToIntrospectionRequest($request, $response);
+        } catch (OAuthServerException $exception) {
+
+            // All instances of OAuthServerException can be converted to a PSR-7 response
+            return $exception->generateHttpResponse($response);
+        } catch (\Exception $exception) {
+
+            // Catch unexpected exceptions
+            $body = $response->getBody();
+            $body->write($exception->getMessage());
+
+            return $response->withStatus(500)->withBody($body);
+        }
+    }
+);
+
+$app->run();

src/AuthorizationServer.php

@@ -14,12 +14,16 @@
 use League\Event\EmitterAwareTrait;
 use League\OAuth2\Server\Exception\OAuthServerException;
 use League\OAuth2\Server\Grant\GrantTypeInterface;
+use League\OAuth2\Server\IntrospectionValidators\BearerTokenValidator;
+use League\OAuth2\Server\IntrospectionValidators\IntrospectionValidatorInterface;
 use League\OAuth2\Server\Repositories\AccessTokenRepositoryInterface;
 use League\OAuth2\Server\Repositories\ClientRepositoryInterface;
 use League\OAuth2\Server\Repositories\ScopeRepositoryInterface;
 use League\OAuth2\Server\RequestTypes\AuthorizationRequest;
 use League\OAuth2\Server\ResponseTypes\AbstractResponseType;
+use League\OAuth2\Server\ResponseTypes\BearerTokenIntrospectionResponse;
 use League\OAuth2\Server\ResponseTypes\BearerTokenResponse;
+use League\OAuth2\Server\ResponseTypes\IntrospectionResponse;
 use League\OAuth2\Server\ResponseTypes\ResponseTypeInterface;
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
@@ -53,6 +57,21 @@ class AuthorizationServer implements EmitterAwareInterface
      */
     protected $responseType;
 
+    /**
+     * @var null|IntrospectionResponse
+     */
+    protected $introspectionResponseType;
+
+    /**
+     * @var null|IntrospectionValidatorInterface
+     */
+    protected $introspectionValidator;
+
+    /**
+     * @var null|Introspector
+     */
+    protected $introspector;
+
     /**
      * @var ClientRepositoryInterface
      */
@@ -197,6 +216,103 @@ public function respondToAccessTokenRequest(ServerRequestInterface $request, Res
         throw OAuthServerException::unsupportedGrantType();
     }
 
+    /**
+     * Set the introspection response type.
+     *
+     * @param IntrospectionResponse $reponseType
+     */
+    public function setIntrospectionReponseType(IntrospectionResponse $reponseType)
+    {
+        $this->introspectionResponseType = $reponseType;
+    }
+
+    /**
+     * Set the validator used for introspection requests.
+     *
+     * @param IntrospectionValidatorInterface $introspectionValidator
+     */
+    public function setIntrospectionValidator(IntrospectionValidatorInterface $introspectionValidator)
+    {
+        $this->introspectionValidator = $introspectionValidator;
+    }
+
+    /**
+     * Get the introspection response.
+     *
+     * @return IntrospectionResponse
+     */
+    protected function getIntrospectionResponseType()
+    {
+        if ($this->introspectionResponseType instanceof IntrospectionResponse === false) {
+            $this->introspectionResponseType = new BearerTokenIntrospectionResponse();
+        }
+
+        return $this->introspectionResponseType;
+    }
+
+    /**
+     * Get the introspection response
+     *
+     * @return IntrospectionValidatorInterface
+     */
+    protected function getIntrospectionValidator()
+    {
+        if ($this->introspectionValidator instanceof IntrospectionValidatorInterface === false) {
+            $this->introspectionValidator = new BearerTokenValidator($this->accessTokenRepository);
+        }
+
+        return $this->introspectionValidator;
+    }
+
+    /**
+     * Return an introspection response.
+     *
+     * @param ServerRequestInterface $request
+     * @param ResponseInterface      $response
+     *
+     * @return ResponseInterface
+     */
+    public function respondToIntrospectionRequest(ServerRequestInterface $request, ResponseInterface $response)
+    {
+        $introspector = $this->getIntrospector();
+
+        $introspectionResponse = $introspector->respondToIntrospectionRequest(
+            $request,
+            $this->getIntrospectionResponseType()
+        );
+
+        return $introspectionResponse->generateHttpResponse($response);
+    }
+
+    /**
+     * Validate an introspection request.
+     *
+     * @param ServerRequestInterface $request
+     */
+    public function validateIntrospectionRequest(ServerRequestInterface $request)
+    {
+        $introspector = $this->getIntrospector();
+        $introspector->validateIntrospectionRequest($request);
+    }
+
+    /**
+     * Returns the introspector.
+     *
+     * @return Introspector
+     */
+    private function getIntrospector()
+    {
+        if (!isset($this->introspector)) {
+            $this->introspector = new Introspector(
+                $this->accessTokenRepository,
+                $this->privateKey,
+                $this->getIntrospectionValidator()
+            );
+        }
+
+        return $this->introspector;
+    }
+
     /**
      * Get the token type that grants will return in the HTTP response.
      *

src/IntrospectionValidators/BearerTokenValidator.php

@@ -0,0 +1,126 @@
+<?php
+
+namespace League\OAuth2\Server\IntrospectionValidators;
+
+use InvalidArgumentException;
+use Lcobucci\JWT\Parser;
+use Lcobucci\JWT\Signer\Keychain;
+use Lcobucci\JWT\Signer\Rsa\Sha256;
+use Lcobucci\JWT\Token;
+use Lcobucci\JWT\ValidationData;
+use League\OAuth2\Server\CryptKey;
+use League\OAuth2\Server\Repositories\AccessTokenRepositoryInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+class BearerTokenValidator implements IntrospectionValidatorInterface
+{
+    /**
+     * @var AccessTokenRepositoryInterface
+     */
+    private $accessTokenRepository;
+
+    /**
+     * @var \League\OAuth2\Server\CryptKey
+     */
+    protected $privateKey;
+
+    /**
+     * @param AccessTokenRepositoryInterface $accessTokenRepository
+     */
+    public function __construct(AccessTokenRepositoryInterface $accessTokenRepository)
+    {
+        $this->accessTokenRepository = $accessTokenRepository;
+    }
+
+    /**
+     * Set the private key.
+     *
+     * @param \League\OAuth2\Server\CryptKey $key
+     */
+    public function setPrivateKey(CryptKey $key)
+    {
+        $this->privateKey = $key;
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public function validateIntrospection(ServerRequestInterface $request)
+    {
+        try {
+            $token = $this->getTokenFromRequest($request);
+        } catch (InvalidArgumentException $e) {
+            return false;
+        }
+
+        if (
+            $this->isTokenRevoked($token) ||
+            $this->isTokenExpired($token) ||
+            $this->isTokenUnverified($token)
+        ) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Gets the token from the request body.
+     *
+     * @param ServerRequestInterface $request
+     *
+     * @return Token
+     */
+    public function getTokenFromRequest(ServerRequestInterface $request)
+    {
+        $jwt = $request->getParsedBody()['token'] ?? null;
+
+        return (new Parser())
+            ->parse($jwt);
+    }
+
+    /**
+     * Checks whether the token is unverified.
+     *
+     * @param Token $token
+     *
+     * @return bool
+     */
+    private function isTokenUnverified(Token $token)
+    {
+        $keychain = new Keychain();
+
+        $key = $keychain->getPrivateKey(
+            $this->privateKey->getKeyPath(),
+            $this->privateKey->getPassPhrase()
+        );
+
+        return $token->verify(new Sha256(), $key->getContent()) === false;
+    }
+
+    /**
+     * Ensure access token hasn't expired.
+     *
+     * @param Token $token
+     *
+     * @return bool
+     */
+    private function isTokenExpired(Token $token)
+    {
+        $data = new ValidationData(time());
+
+        return !$token->validate($data);
+    }
+
+    /**
+     * Check if the given token is revoked.
+     *
+     * @param Token $token
+     *
+     * @return bool
+     */
+    private function isTokenRevoked(Token $token)
+    {
+        return $this->accessTokenRepository->isAccessTokenRevoked($token->getClaim('jti'));
+    }
+}

src/IntrospectionValidators/IntrospectionValidatorInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+namespace League\OAuth2\Server\IntrospectionValidators;
+
+use Psr\Http\Message\ServerRequestInterface;
+
+interface IntrospectionValidatorInterface
+{
+    /**
+     * Determine wether the introspection request is valid.
+     *
+     * @param ServerRequestInterface $request
+     *
+     * @return bool
+     */
+    public function validateIntrospection(ServerRequestInterface $request);
+}