OIDC introspection endpoint

[byewokko]

closes #283

Changes

• Implement OAuth 2.0 Token Introspection endpoint according to https://datatracker.ietf.org/doc/html/rfc7662.
• Set default WWW-Authenticate Bearer realm to the value of OpenID issuer.

OAuth 2.0 Token Introspection

• Found at POST /openidconnect/token/introspect.
• The POST payload must be query-encoded and must include token with the token value and client_id.
• The endpoint must not be exposed to the public network since there is no client authentication implemented (except for the client_id query parameter requirement).

Example

Request

POST /openidconnect/token/introspect
client_id=example-app&token=HQHNO7fC8iFB0MuQJvohVIYaxC-KGIEMg6PyIBQUYmIf9jPbxM2oceM-A1U3v3hd

Response

{
    "active": true,
    "token_type": "access_token",
    "client_id": "example-app",
    "exp": 1697023308,
    "iat": 1697019708,
    "sub": "mongodb:ext:abcd....",
    "aud": "example-app",
    "iss": "https://auth.local.loc/seacat-auth/api",
    "username": "pepik"
}

[filipmelik]

The POST payload must be query-encoded and must include token with the token value and client_id.

Why the client_id? As far as I can see, it is a non standard field regarding the linked OAuth2.0 specs. If I understand correctly, this serves as a obscure security measure. Specs clearly states that

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](https://datatracker.ietf.org/doc/html/rfc6749)] or a separate
   OAuth 2.0 access token such as the bearer token described in OAuth
   2.0 Bearer Token Usage [[RFC6750](https://datatracker.ietf.org/doc/html/rfc6750)].

which is clearly broken here and instead you rely on this one sentence:

The endpoint must not be exposed to the public network since there is no client authentication implemented (except for the client_id query parameter requirement).

IMHO this is insufficient and breaking the spec.

[ateska]

AFAIK @filipmelik - if you want to expose it to public network, the NGINX introspection needs to be put in front of the SeaCat API and that will give you required access authorization.

It also means that the client_id will be handled by that introspection point.

@byewokko

[filipmelik]

AFAIK @filipmelik - if you want to expose it to public network, the NGINX introspection needs to be put in front of the SeaCat API and that will give you required access authorization.

It also means that the client_id will be handled by that introspection point.

not sure I understand TBH.

I (as an external party) see Seacat as an Authorization provider. I do not know (and also don't wanna know) the inner details of how seacat works, it it somehow uses nginx or whatever as a system component and if it have some private API endpoints and how they work. That's why I do not know what do you mean by NGINX introspection. 😊

I see it just as an OAuth2.0 Authorization provider and expect all the endpoints the OAuth2.0 spec supports. And AFAIK the OAuth2.0 endpoints should be by nature "publicly" available. That's why I do not see the point of having introspect endpoint "hidden". 🤔 Can you elaborate pls?

[ateska]

@filipmelik - in the nutshell, SeaCat Auth executes authorisation by "introspection" which is delegated to NGINX (that's NGINX introspection).

This is a high-level schema:

Frontend <---> NGINX <---> Backend
                 |   \
                 |    \
          SeaCat Auth - (private API)

How this apply to OIDC introspection endpoint?

In this case, the endpoint is exposed on the SeaCat Auth private API (hence Robin's remarks above); then the exposure to "frontends" happens thru "NGINX introspection" and you get the authorization. In other words, the SeaCat Auth private API is "just another backend". It could be easily two microservices.

Ok?