Description

The current handling in the introspect endpoint in FusionAuth is to validate the client_id and token parameters. Both of these parameters must be passed to the endpoint as application/x-www-form-urlencoded data currently.

The specification for RFC 7662 section 2.1 states that the introspect endpoint MUST support all options in the OAuth 2.0 specification for client authentication. The supported options are defined in RFC 6749 section 2.3. The options are:

• client_id and client_secret in the body as post data
• client_id and client_secret as the username/password for Basic authorization using the Authorization header

There is already a comment in the code regarding this, but I wanted to track it here as well. At a minimum, we should support these options and validate that the client credentials are correct. While the introspect specification does allow us to provide our own authentication, anyone using the standard OAuth client authentication methods will find that they cannot use our introspect endpoint. This could break use of OAuth libraries and other OAuth systems since we require client_id to be in the request body.

Details

• Some of the examples given in the RFC use a separate bearer token - separate from the one being "inspected". Once we support client credentials, this is likely a case that we would want to support. So the Bearer token presented in the Authorization header may be a Bearer token owned by an "entity" that has received an access token from a client credentials grant. This same "entity" could also just use their client_id and client_secret in a basic authorization header. There may be some benefit in using the Bearer token instead as it is short lived and if it leaks it is not permanently in the wild.
• It is unclear if we want to simply use the same "require authentication" setting we use for the token endpoint for this endpoint. The spec seems to indicate the same type of authorization can be done, but is there a case where we want to require authentication to complete the auth code grant, but not so much for the introspect endpoint? The user already has a JWT, and it can be inspected w/out calling this endpoint, so adding client authorization doesn't buy us much since you can already call the Validate JWT or the Userinfo endpoint w/out this same restriction.
• I don't think we'll break anyone passing in a Bearer or Basic Authorization header as it will be ignored currently - unless they omit the client_id in the request body and only provide it in a Basic authorization header. And because the spec does not require client_id in the request body, this is a FusionAuth requirement, we could break some integrations.

Related issues

• Add support for tokens obtained from the client credentials grant on the introspection endpoint #1434
• Allow Device Grant to be completed out of band #2218

Affects versions

1.x