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

@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