Support token revocation and introspection #1473

hafezdivandari · 2025-02-14T20:17:34Z

Fixes #806
Fixes #1350
Closes #1255
Closes #1135
Closes #995
Closes #925

It's much easier to implement Token Revocation RFC7009 and Token Introspection RFC7662 at the same time! These 2 RFCs have most of the logic in common:

The same HTTP POST request with the same parameters sent as
"application/x-www-form-urlencoded" data:
- token is required, accepts either an access token or a refresh token.
- token_type_hint is optional to help the server optimize the token lookup. access_token or refresh_token.
The same client authentication:
- Via Authorization: Basic {client_credentials} header
- Or via client_id and client_secret parameters.
The same access/refresh token validation:
- The token was issued to the client making the request,
- and is valid/active (has valid signature/encryption, is not expired, and is not revoked).
The same HTTP status responses:
- 400: invalid_request the required token parameter was not sent.
- 401: invalid_client the request is not authorized. Client credentials were not sent or invalid.
- 200: The token is revoked, expired, doesn't exists, or was not issued to the client making the request:
  - "Token revocation": The response body is empty.
  - "Token Introspection": The JSON response has the active field set to false. { "active": false }
- 200: The token is valid, active, and was issued to the client making the request:
  - "Token revocation": The response body is empty.
  - "Token Introspection": The JSON response has the active field set to true. { "active": true, ... }

Implementation

Fully backward-compatible (No BC breaking changes at all!).
Fully consistent with the current code style and project structure.
Uses the existing code within the package without adding any redundancy.
Fully customizable. Defines interfaces and allow injecting customized instances.
Fully tested.

Summary

Summary of file changes in order of appearance.

New AbstractHandler class

Extended by AbstractGrant and AbstractTokenHandler classes.
clientRepository, accessTokenRepository, and refreshTokenRepository properties have been moved to this class from child AbstractGrant class.
setClientRepository, setAccessTokenRepository, setRefreshTokenRepository, getClientCredentials, parseParam, getRequestParameter, getBasicAuthCredentials, getQueryStringParameter, getCookieParameter, getServerParameter, and validateEncryptedRefreshToken methods have been moved to this class from child AbstractGrant class without any change.
validateClient method from child AbstractGrant has been moved to this class with a minor change: The call to getIdentifier() is GrantTypeInterface specific.
getClientEntityOrFail method from child AbstractGrant has been moved to this class. This method is also overridden on child AbstractGrant: Call to supportsGrantType method is AbstracGrant specific.
New validateEncryptedRefreshToken is extracted from RefreshTokenGrant::validateOldRefreshToken method.

Change AuthorizationValidators\BearerTokenValidator class

Now implements new JwtValidatorInterface interface.
Extract the JWT validation logic from validateAuthorization method into a new validateJwt method.
The new validateJwt method also accepts optional $clientId argument. If a $clientId is provided, it verifies whether the token was issued to the given client.

New AuthorizationValidators\JwtValidatorInterface interface

Implemented by BearerTokenValidator class.
Defines validateJwt method.
Used by AbstractTokenHandler::setJwtValidator() method.

Change Exception\OAuthServerException class

Define new unsupportedTokenType method.

Change Grant\AbstractGrant class

Now extends new AbstractHandler class.
All removed liens are moved to the parent AbstractHandler class.
Overrides getClientEntityOrFail method.

Change Grant\RefreshTokenGrant class

The encrypted refresh token validation logic from validateOldRefreshToken method has been extracted into a new parent AbstractHandler::validateEncryptedRefreshToken method.

New Handlers\AbstractTokenHandler class

Extends new AbstractHandler class.
Implements new TokenHandlerInterface interface.
Defines setPublicKey and setJwtValidator methods that to allow injecting a customized JWT validator.
Defines validateToken, validateAccessToken and validateRefreshToken methods that have been used by TokenIntrospectionHandler and TokenRevocationHandler classes.

New Handlers\TokenHandlerInterface interface

Implemented by new AbstractTokenHandler class.
Used by setTokenRevocationHandler and setTokenIntrospectionHandler methods of the TokenServer class.

New Handlers\TokenIntrospectionHandler class

Extends new AbstractTokenHandler class.
Defines respondToRequest method that responds to "Token Introspection RFC7662" request.
Defines setResponseType method that allows injecting a customized response type.

New Handlers\TokenRevocationHandler class

Extends new AbstractTokenHandler class.
Defines respondToRequest method that responds to "Token Revocation RFC7009" request.

New ResponseTypes\IntrospectionResponse class

Implements new IntrospectionResponseTypeInterface interface.
Defines generateHttpResponse method to generate "Token Revocation RFC7009" response.

New ResponseTypes\IntrospectionResponseTypeInterface class

Implemented by new IntrospectionResponse class.
Used by TokenIntrospectionHandler::setResponseType method that allows injecting a customized response type.

New TokenServer class

Defines respondToTokenRevocationRequest and respondToTokenIntrospectionRequest methods to respond to the respective request.
Defines setTokenRevocationHandler and setTokenIntrospectionHandler methods that allows injecting customized handlers.

ezequidias · 2025-02-14T21:16:41Z

@Sephster , as mentioned #1453 (comment), it would be great to have more maintainers for this repository! @hafezdivandari is an excellent professional with extensive knowledge of OAuth2. Having more people to support the project would certainly help its growth and maintenance! 🚀

hafezdivandari · 2025-02-16T22:45:35Z

src/AbstractHandler.php

+    use EmitterAwarePolyfill;
+    use CryptTrait;
+
+    protected ClientRepositoryInterface $clientRepository;
+
+    protected AccessTokenRepositoryInterface $accessTokenRepository;
+
+    protected RefreshTokenRepositoryInterface $refreshTokenRepository;


From AbstractGrant class.

hafezdivandari · 2025-02-16T22:47:09Z

src/AbstractHandler.php

+    public function setClientRepository(ClientRepositoryInterface $clientRepository): void
+    {
+        $this->clientRepository = $clientRepository;
+    }
+
+    public function setAccessTokenRepository(AccessTokenRepositoryInterface $accessTokenRepository): void
+    {
+        $this->accessTokenRepository = $accessTokenRepository;
+    }
+
+    public function setRefreshTokenRepository(RefreshTokenRepositoryInterface $refreshTokenRepository): void
+    {
+        $this->refreshTokenRepository = $refreshTokenRepository;
+    }


From AbstractGrant class.

hafezdivandari · 2025-02-16T22:48:04Z

src/AbstractHandler.php

+    /**
+     * Validate the client.
+     *
+     * @throws OAuthServerException
+     */
+    protected function validateClient(ServerRequestInterface $request): ClientEntityInterface
+    {
+        [$clientId, $clientSecret] = $this->getClientCredentials($request);
+
+        $client = $this->getClientEntityOrFail($clientId, $request);
+
+        if ($client->isConfidential()) {
+            if ($clientSecret === '') {
+                throw OAuthServerException::invalidRequest('client_secret');
+            }
+
+            if (
+                $this->clientRepository->validateClient(
+                    $clientId,
+                    $clientSecret,
+                    $this instanceof GrantTypeInterface ? $this->getIdentifier() : null
+                ) === false
+            ) {
+                $this->getEmitter()->emit(new RequestEvent(RequestEvent::CLIENT_AUTHENTICATION_FAILED, $request));
+
+                throw OAuthServerException::invalidClient($request);
+            }
+        }
+
+        return $client;
+    }


Moved from AbstractGrant class.

hafezdivandari · 2025-02-16T22:49:32Z

src/AbstractHandler.php

+                $this->clientRepository->validateClient(
+                    $clientId,
+                    $clientSecret,
+                    $this instanceof GrantTypeInterface ? $this->getIdentifier() : null


This line is the only change on this method, since getIdentifier() method is defined on GrantTypeInterface only.

hafezdivandari · 2025-02-16T22:51:14Z

src/AbstractHandler.php

+    /**
+     * Wrapper around ClientRepository::getClientEntity() that ensures we emit
+     * an event and throw an exception if the repo doesn't return a client
+     * entity.
+     *
+     * This is a bit of defensive coding because the interface contract
+     * doesn't actually enforce non-null returns/exception-on-no-client so
+     * getClientEntity might return null. By contrast, this method will
+     * always either return a ClientEntityInterface or throw.
+     *
+     * @throws OAuthServerException
+     */
+    protected function getClientEntityOrFail(string $clientId, ServerRequestInterface $request): ClientEntityInterface
+    {
+        $client = $this->clientRepository->getClientEntity($clientId);
+
+        if ($client instanceof ClientEntityInterface === false) {
+            $this->getEmitter()->emit(new RequestEvent(RequestEvent::CLIENT_AUTHENTICATION_FAILED, $request));
+            throw OAuthServerException::invalidClient($request);
+        }
+
+        return $client;
+    }


Moved from AbstractGrant class.

hafezdivandari · 2025-02-16T23:33:43Z

src/Handlers/TokenIntrospectionHandler.php

+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+class TokenIntrospectionHandler extends AbstractTokenHandler


This class implements "Token Introspection RFC7662". This class also allows customizing the introspection response by injecting a IntrospectionResponseTypeInterface instance.

hafezdivandari · 2025-02-16T23:34:34Z

src/Handlers/TokenRevocationHandler.php

+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+class TokenRevocationHandler extends AbstractTokenHandler


This class implements "Token Revocation RFC7009".

hafezdivandari · 2025-02-16T23:35:50Z

src/ResponseTypes/IntrospectionResponse.php

+use DateTimeInterface;
+use Psr\Http\Message\ResponseInterface;
+
+class IntrospectionResponse implements IntrospectionResponseTypeInterface


This class implements Introspection Response. RFC7662 section 2.2

hafezdivandari · 2025-02-16T23:37:03Z

src/ResponseTypes/IntrospectionResponseTypeInterface.php

+
+use Psr\Http\Message\ResponseInterface;
+
+interface IntrospectionResponseTypeInterface


Defines an interface for introspection response type.

hafezdivandari · 2025-02-16T23:39:20Z

src/TokenServer.php

+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+class TokenServer implements EmitterAwareInterface


This class defines 2 methods to respond to token revocation and token introspection requests. Also allows injecting customized token revocation/introspection handlers.

This class is inspired by AuthorizationServer and ResourceServer classes.

hafezdivandari added 2 commits February 14, 2025 23:46

support token revocation and introspection

fbc0289

formatting

704a3cf

hafezdivandari added 2 commits February 16, 2025 00:45

Merge branch 'master' into master-token-revocation-introspection

9555b91

formatting

3482d6f

hafezdivandari marked this pull request as ready for review February 16, 2025 17:49

hafezdivandari commented Feb 16, 2025

View reviewed changes

hafezdivandari mentioned this pull request Feb 17, 2025

Allow configuring the JWT builder when generating a token #1328

Open

hafezdivandari added 4 commits February 18, 2025 03:57

formatting

68eded0

update readme

f52f03d

add tests

09d284b

formatting

70bf835

cicnavi mentioned this pull request Feb 18, 2025

Consider implementing token introspection feature simplesamlphp/simplesamlphp-module-oidc#158

Open

formatting

3c574f2

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support token revocation and introspection #1473

Support token revocation and introspection #1473

hafezdivandari commented Feb 14, 2025 •

edited

Loading

ezequidias commented Feb 14, 2025

hafezdivandari Feb 16, 2025

hafezdivandari Feb 16, 2025

hafezdivandari Feb 16, 2025

hafezdivandari Feb 16, 2025 •

edited

Loading

hafezdivandari Feb 16, 2025

hafezdivandari Feb 16, 2025

hafezdivandari Feb 16, 2025

hafezdivandari Feb 16, 2025

hafezdivandari Feb 16, 2025

hafezdivandari Feb 16, 2025


		use Psr\Http\Message\ResponseInterface;

		interface IntrospectionResponseTypeInterface

Support token revocation and introspection #1473

Are you sure you want to change the base?

Support token revocation and introspection #1473

Conversation

hafezdivandari commented Feb 14, 2025 • edited Loading

Implementation

Summary

ezequidias commented Feb 14, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hafezdivandari Feb 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hafezdivandari commented Feb 14, 2025 •

edited

Loading

hafezdivandari Feb 16, 2025 •

edited

Loading