Allow to customize Token Introspection response

[nbulaj]

Allow to customize introspection response

Fixes #1194

[ZilvinasKucinskas]

@nbulaj Is there an option to protect token introspection for specific clients only (some kind of condition)? This is required for the use case when only internal services can use the endpoint.

BTW, I have written an extension for this particular case (restricting token introspection). Having this option in doorkeeper would be great! 🎉

[nbulaj]

Hi @ZilvinasKucinskas . Currently Doorkeeper doesn't have such option. It some sort of authorization server customization that isn't forbidden by the spec, but I don't sure we need to have all of it directly in the gem core. It would be great if in some day I can plan and implement modular plugin system that will allow to introduce small gem plugins (like for Sequel) that will give all the required set of functionality.

[nbulaj]

Hi @ZilvinasKucinskas . I reread OAuth 2 specs and now I think it would be great to introduce such restriction. RFC doesn't say anything about it except some security considerations with suggestion to use some firewall, but I think we can be opinionated enough and allow developers to easily restrict access to this endpoint. WDYT ?

[ZilvinasKucinskas]

Hi @nbulaj.

To give some more insights for doorkeeper, I just reread RFC 7662 too.

To prevent token scanning attacks, the endpoint MUST also require
some form of authorization to access this endpoint, such as client
authentication as described in OAuth 2.0 [RFC6749] or a separate
OAuth 2.0 access token such as the bearer token described in OAuth
2.0 Bearer Token Usage

So we already have Client Authentication and Bearer Token Authentication in Doorkeeper::OAuth::TokenIntrospection. Doorkeeper can accept both and that's great. However, we have limitations/issues described below.

If the token can be used only at certain resource servers, the
authorization server MUST determine whether or not the token can
be used at the resource server making the introspection call

This is the place we want to improve our doorkeeper implementation. Doorkeeper makes a very opinionated decision to return token introspection response only if token is not associate with application (public) or token is connected to the same application as implemented here. That is only true for Client Authentication right now. For Bearer Authentication no checks are performed for valid Bearer token (as you already know from the public issue) - and I have added additional test to check it out in this gist.

Looking at the Doorkeeper code here, it doesn’t perform any additional checks on Bearer Token Authentication. Usual use case would be probably checking authorized token scopes. By having client credentials, client is able to make access token and call token introspection without checking that introspectable token belongs to client application. It can also open up possibilities for token scanning attacks or expose sensitive details (PII, server details) if token introspection was customized by someone.

To solve this, there could be an option to make customisable strategies for both Bearer Token Authentication and Client Authentication flows. My idea how these strategies are being used in the wild (production):

• Bearer Token Authentication - scope on the token is being checked
• Client Authentication - additional boolean database column is being added to Doorkeeper::Application and it is being checked in order to return token introspection response. More complex use cases could include multiple levels of different token introspection responses based on level.

However there is a question what should be the default behaviour? There could be clients that rely on Bearer Authentication and after fixing this, their logic could break. Personally I have disabled Bearer Authentication for token introspection in my projects from the beginning.

The authorization server MAY respond differently to different
protected resources making the same request. For instance, an
authorization server MAY limit which scopes from a given token are
returned for each protected resource to prevent a protected resource
from learning more about the larger network than is necessary for its
operation.

This is another change that could be added to token instrospection endpoint. There could be multiple permission levels for resource servers. And for each permission, token introspection can return a different response.

[nbulaj]

Hi @ZilvinasKucinskas . Thanks for such good clarification!

For Bearer Authentication no checks are performed for valid Bearer token

Yep, it's already added here ( 3295d62 / #1209)

What about else (protecting endpoint and so on) - it's a good idea 👍 . And I think I can work on it when I have free time.