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 · 2025-03-05T17:00:38Z

Hi @Sephster, by any chance, did you have the time to check this PR? I'd appreciate any comments or feedback.

Sephster · 2025-03-07T01:25:56Z

Sorry I hadn't realised it was ready for review. I'll get to it as soon as I can but am going to clear some outstanding issues prior. Thanks for your work on this

adnweedon · 2025-06-04T10:24:39Z

@Sephster thanks so much for all your work maintaining this library! I was just wondering whether you had even a rough idea of when you might get to looking at this PR? It would be super helpful for the problem I'm currently trying to solve! 😅

hafezdivandari · 2025-09-11T16:49:06Z

Hey @Sephster, I feel the OAuth Server is a bit incomplete without this. When you have a chance, could you take a look? The PR is large, but I did my best to make it easy to review. It’s also difficult to keep it open for too long since other merged PRs may cause conflicts. Thanks.

Sephster · 2025-09-15T09:02:01Z

I'll be picking this up next. Thanks

hafezdivandari · 2025-09-27T17:50:11Z

Thanks @Sephster! I have the implementation PR ready for Laravel Passport if you’d like to see it in action: laravel/passport#1858

Sephster · 2025-10-14T16:43:55Z

I'm on holiday with the family for a few days but still reviewing and hoping to get a first response to you soon. Thanks for the patience

brayniverse · 2025-10-20T15:50:21Z

src/Exception/OAuthServerException.php

+    public static function unsupportedTokenType(?string $hint = null): static
+    {
+        return new static(
+            'The authorization server does not support the revocation of the presented token type.',


This method name implies the error isn't specifically related to token revocation, but the message itself does. Should the message be reworded to make it more generic, or should the method name be updated to imply it's specifically for token revocation?

Thanks for the review. Like other existing exception methods, the method name is based on the error code and message is based on its description according to the revocation RFC.

This error code has not been mentioned on the introspection RFC.

Although this new exception is added on this PR, it is not been used because at the current implementation, we support revocation of both access and refresh tokens. But I decided to add it anyway as it is defined on the RFC and we may have a config property to disable revocation of access token type in the future.

hafezdivandari · 2025-10-30T18:19:03Z

Hey @Sephster Any updates on this one?

Sephster · 2025-10-31T08:13:01Z

Was working on this last night. There are quite a few aspects to this so it is taking a while. I have two RFCs I need to check for compliance, significant architecture changes, and tagged issues I need to ensure are satisfied. It is a big review but am quietly plugging away on it. I'm going to try dedicate an evening to it soon

related to thephpleague#1483

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

hafezdivandari mentioned this pull request Aug 16, 2025

Still maintained? #1487

Closed

This was referenced Sep 29, 2025

Enable JWKS-based JWT verification via kid header laravel/passport#1856

Draft

[13.x] Support Token Revocation RFC7009 and Token Introspection RFC7662 laravel/passport#1858

Draft

brayniverse reviewed Oct 20, 2025

View reviewed changes

This was referenced Oct 22, 2025

Token Revocation question #806

Open

Access token introspection RFC7662 #1350

Closed

Add introspection implementation - updated #1255

Open

Add token revocation support (RFC 7009) #1135

Open

Add token revocation support #995

Open

hafezdivandari mentioned this pull request Oct 22, 2025

Add introspection implementation #925

Open

hafezdivandari added 2 commits November 6, 2025 16:59

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

bed1164

add SensitiveParameter attribute

a3f0080

related to thephpleague#1483


		use Psr\Http\Message\ResponseInterface;

		interface IntrospectionResponseTypeInterface

Uh oh!

Support token revocation and introspection #1473

Are you sure you want to change the base?

Support token revocation and introspection #1473

Uh oh!

Conversation

hafezdivandari commented Feb 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Implementation

Summary

Uh oh!

ezequidias commented Feb 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hafezdivandari Feb 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hafezdivandari commented Mar 5, 2025

Uh oh!

Sephster commented Mar 7, 2025

Uh oh!

adnweedon commented Jun 4, 2025

Uh oh!

hafezdivandari commented Sep 11, 2025

Uh oh!

Sephster commented Sep 15, 2025

Uh oh!

hafezdivandari commented Sep 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Sephster commented Oct 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hafezdivandari Oct 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hafezdivandari commented Oct 30, 2025

Uh oh!

Sephster commented Oct 31, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

hafezdivandari commented Feb 14, 2025 •

edited

Loading

hafezdivandari Feb 16, 2025 •

edited

Loading

hafezdivandari commented Sep 27, 2025 •

edited

Loading

hafezdivandari Oct 20, 2025 •

edited

Loading