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

@@ -10,6 +10,7 @@
 namespace League\OAuth2\Server;
 
 use Defuse\Crypto\Key;
+use Lcobucci\JWT\Parser;
 use League\Event\EmitterAwareInterface;
 use League\Event\EmitterAwareTrait;
 use League\OAuth2\Server\Exception\OAuthServerException;
@@ -20,6 +21,7 @@
 use League\OAuth2\Server\RequestTypes\AuthorizationRequest;
 use League\OAuth2\Server\ResponseTypes\AbstractResponseType;
 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 +55,16 @@ class AuthorizationServer implements EmitterAwareInterface
      */
     protected $responseType;
 
+    /**
+     * @var null|IntrospectionResponse
+     */
+    protected $introspectionResponseType;
+
+    /**
+     * @var null|Introspector
+     */
+    protected $introspector;
+
     /**
      * @var ClientRepositoryInterface
      */
@@ -197,6 +209,73 @@ public function respondToAccessTokenRequest(ServerRequestInterface $request, Res
         throw OAuthServerException::unsupportedGrantType();
     }
 
+    /**
+     * @param IntrospectionResponse $reponseType
+     */
+    public function setIntrospectionReponseType(IntrospectionResponse $reponseType)
+    {
+        $this->introspectionResponseType = $reponseType;
+    }
+
+    /**
+     * Get the introspection response
+     *
+     * @return IntrospectionResponse
+     */
+    protected function getIntrospectionResponseType()
+    {
+        if ($this->introspectionResponseType instanceof IntrospectionResponse === false) {
+            $this->introspectionResponseType = new IntrospectionResponse;
+        }
+
+        return $this->introspectionResponseType;
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * Return an introspection response.
+     *
+     * @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, new Parser);
+        }
+
+        return $this->introspector;
+    }
+
     /**
      * Get the token type that grants will return in the HTTP response.
      *

src/Introspector.php

@@ -0,0 +1,153 @@
+<?php
+
+namespace League\OAuth2\Server;
+
+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\Exception\OAuthServerException;
+use League\OAuth2\Server\Repositories\AccessTokenRepositoryInterface;
+use League\OAuth2\Server\ResponseTypes\IntrospectionResponse;
+use Psr\Http\Message\ServerRequestInterface;
+
+class Introspector
+{
+    /**
+     * @var AccessTokenRepositoryInterface
+     */
+    private $accessTokenRepository;
+
+    /**
+     * @var CryptKey
+     */
+    private $privateKey;
+
+    /**
+     * @var Parser
+     */
+    private $parser;
+
+    /**
+     * New Introspector instance.
+     *
+     * @param AccessTokenRepositoryInterface $accessTokenRepository
+     * @param CryptKey                       $privateKey
+     * @param Parser                         $parser
+     */
+    public function __construct(
+        AccessTokenRepositoryInterface $accessTokenRepository,
+        CryptKey $privateKey,
+        Parser $parser
+    ) {
+        $this->accessTokenRepository = $accessTokenRepository;
+        $this->privateKey = $privateKey;
+        $this->parser = $parser;
+    }
+
+    /**
+     * Validate the request
+     *
+     * @param ServerRequestInterface $request
+     *
+     * @throws OAuthServerException
+     */
+    public function validateIntrospectionRequest(ServerRequestInterface $request)
+    {
+        if ($request->getMethod() !== 'POST') {
+            throw OAuthServerException::accessDenied('Invalid request method');
+        }
+    }
+
+    /**
+     * Return an introspection response.
+     *
+     * @param ServerRequestInterface $request
+     * @param IntrospectionResponse  $responseType
+     *
+     * @return IntrospectionResponse
+     */
+    public function respondToIntrospectionRequest(
+        ServerRequestInterface $request,
+        IntrospectionResponse $responseType
+    ) {
+        $jwt = $request->getParsedBody()['token'] ?? null;
+
+        try {
+            $token = $this->parser->parse($jwt);
+        } catch (InvalidArgumentException $e) {
+            return $responseType;
+        }
+
+        return $this->isTokenValid($token) ?
+            $this->setTokenOnResponse($token, $responseType) :
+            $responseType;
+    }
+
+    /**
+     * Validate the JWT and make sure it has not expired or been revoked
+     *
+     * @return bool
+     */
+    private function isTokenValid(Token $token)
+    {
+        return $this->verifyToken($token) && !$this->isTokenExpired($token) && !$this->isTokenRevoked($token);
+    }
+
+    /**
+     * Validate the JWT token.
+     *
+     * @param Token $token
+     *
+     * @return bool
+     */
+    private function verifyToken(Token $token)
+    {
+        $keychain = new Keychain();
+        $key = $keychain->getPrivateKey($this->privateKey->getKeyPath(), $this->privateKey->getPassPhrase());
+
+        return $token->verify(new Sha256, $key->getContent());
+    }
+
+    /**
+     * 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 access token is revoked.
+     *
+     * @param Token $token
+     *
+     * @return bool
+     */
+    private function isTokenRevoked(Token $token)
+    {
+        return $this->accessTokenRepository->isAccessTokenRevoked($token->getClaim('jti'));
+    }
+
+    /**
+     * Create active introspection response.
+     *
+     * @param Token $token
+     *
+     * @return IntrospectionResponse
+     */
+    private function setTokenOnResponse(Token $token, IntrospectionResponse $responseType)
+    {
+        $responseType->setToken($token);
+
+        return $responseType;
+    }
+}