Support token revocation and introspection

[hafezdivandari]

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 BearerTokenValidatorInterface interface.
• Extract the bearer token validation logic from validateAuthorization method into a new validateBearerToken method.
• The new validateBearerToken method also accepts optional $clientId argument. If a $clientId is provided, it verifies whether the token was issued to the given client.

New AuthorizationValidators\BearerTokenValidatorInterface interface

• Implemented by BearerTokenValidator class.
• Defines validateBearerToken method.
• Used by AbstractTokenHandler::setBearerTokenValidator() 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 setBearerTokenValidator methods that to allow injecting a customized token 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]

@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]

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

[Sephster]

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]

@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]

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]

I'll be picking this up next. Thanks

[hafezdivandari]

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

[Sephster]

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

[hafezdivandari]

Hey @Sephster Any updates on this one?

[Sephster]

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

[Sephster]

Sorry for the lengthy time with this @hafezdivandari - there was a lot to go through but here is my first pass. Apologies that there are quite a lot of comments but that comes with the extent of the changes I guess. Thanks for all your effort on this.

[hafezdivandari]

Hi @Sephster, thank you for reviewing the PR and for the detailed feedback. I’ve addressed the requested changes and replied to each comment. Please feel free to resolve any comment where you find my response satisfactory.

[hafezdivandari]

Hi @Sephster , would there be any chance of having this merged as a Christmas gift?

[Sephster]

That's my intention but my kids gifts are going to have to take priority 🐵 I aim to have this reviewed before Christmas though, all being well. Thanks @hafezdivandari

[Sephster]

Aiming to pick up and complete this this week @hafezdivandari - thanks for your patience

[LieutenantClone]

Hi @Sephster , any progress?

[Sephster]

Not yet - was working on dropping PHP 8.1 support last week but aim to pick this up, at least partially, this evening all being wel