Implement Token Introspection Endpoint

[jgrandja]

This will deliver OAuth 2.0 Token Introspection, which provides support for opaque access tokens.

[lspil]

Hi @jgrandja Can I take this issue?

[jgrandja]

Thanks for the offer @lspil. This feature is further down the backlog so we're holding off for now. I'm in the process of setting up the next set of work that will deliver the authorization_code grant. I should be organized with the plan by either this Friday or early next week, at which point there will be a few issues you can choose from. I'll be sure to reach out to you when things are ready to go. Thanks!

[dfcoffin]

@jgrandja Please reach out to me as well, once the plan has been completed.

[jgrandja]

You are definitely on my list @dfcoffin 👍

[lspil]

Thanks @jgrandja !

[rozagerardo]

Hi @jgrandja! I'm just starting to dedicate some time to this project now, and since I don't see many issues logged to work on, maybe I can help define the specs for the base ticket for this Epic (even maybe work on a draft implementation just to analyze this better, for when we're ready to tackle it)? Or are we planning to move forward with a different track of work?

Here it goes:

======

An Authorization Server should provide an endpoint to determine the active state of an OAuth 2.0 token and to determine meta-information about this token.

An OAuth2TokenIntrospectionEndpointFilter should be implemented as a Filter.

Implementation requirements:

• The Filter should process POST requests for the (default) path /oauth2/introspect
• Request parameters are expected to be sent as application/x-www-form-urlencoded data:
  • token (required): can be an Access Token or a Refresh Token
  • token_type_hint (optional): can be either access_token or refresh_token (defined in OAuth 2.0 Token Revocation spec)
• The client must be authenticated Implement Client Authentication #39 before the Token Introspection Request can be accepted
• Conditions to consider the token 'active':
  • issued by this Authorization Server
  • not expired (and not before the nbf timestamp)
  • not revoked or invalidated
  • valid signature (if the token is a JWT)
  • valid resource server introspecting the token
• The metadata included in the response should contain:
  • active (required): boolean indicator of whether or not the presented token is currently active.
  • scope (optional): a list of space-delimited, case-sensitive strings
  • client_id (optional): OAuth 2.0 client that requested this token
  • username (optional): identifier for the resource owner who authorized this token
  • token_type (optional): information required to successfully utilize the access token to make a protected resource request (defined in the OAuth 2.0 Authorization Framework). In our case, the value will be OAuth2AccessToken.TokenType.BEARER.
  • exp (optional): Integer Epoch timestamp, indicating when this token will expire
  • iat (optional): Integer Epoch timestamp, indicating when this token was originally issued
  • nbf (optional): Integer Epoch timestamp, indicating when this token is not to be used before
  • sub (optional): Subject of the token
  • aud (optional): string or list of string identifiers representing the intended audience for this token
  • iss (optional): issuer of this token
  • jti (optional): identifier for the token
    Note: we should rely on the existing JWT-related classes for support for these last fields, since the spec itself indicates these are defined in the JWT spec.
• If the token is not active, the endpooint should retrieve a 200 response, with just the active response metadata field, and with a false value.
• javadoc class and public methods
• Unit tests

Specification References

OAuth 2.0 Token Introspection

======

Of course, some of these specs might not be critical for a first approach (like checking the signature), and some might not be achievable with the current status (e.g. validating that the Resource Server introspecting the token is 'accepted'/enabled for the corresponding token), but I decided to include all the constraints for a better analysis.

Hope this helps with the process, looking forward to any comment. Naturally, let me know if there is anything else I can get my hands on.

Cheers!
Ger

[jgrandja]

Excellent summary of the spec @rozagerardo. I couldn't have summarized it better myself :)

We're currently working on some higher priority features so this one is getting pushed back to at least 0.0.4.

Let me know if you're interested on working on this and if so, a draft PR would be best place to start.

[rozagerardo]

Thanks @jgrandja.

Definitely, I'll start working on a draft PR for this 👍

I'll also keep an eye on the new tickets and PRs in case I can assist with anything.