OIDC introspection endpoint #295

byewokko · 2023-10-03T15:07:05Z

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"
}

ateska

Ok from my side.

filipmelik · 2023-10-12T10:01:38Z

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 · 2023-10-12T10:52:37Z

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 · 2023-10-12T11:00:05Z

seacatauth/openidconnect/handler/introspect.py

@@ -80,12 +80,12 @@ async def introspect(self, request):
 		client_id = params.get("client_id")


As commented in the MR Overview, I would ditch this alltogether in favor of i.e. OAuth2.0 Client Basic Authz.

Including the client_id and client_secret in the POST body is actually a form of OAuth2.0 Client Basic Authentication. Although admittedly I haven't included the client_secret parameter, since we only support public clients, which do not need any secret (they can have one, but it adds little to no security since anyone can extract the secret).

Anyway, we will yet rethink the authentication.

Clarified on call

seacatauth/openidconnect/handler/introspect.py

filipmelik · 2023-10-12T12:40:28Z

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?

seacatauth/openidconnect/handler/introspect.py

filipmelik · 2023-10-13T06:44:04Z

seacatauth/openidconnect/handler/introspect.py

+		representing the meta information surrounding the token, including whether this token is currently active.
+
+		To protect this endpoint with authorization (as required by RFC7662), use NGINX reverse proxy
+		with auth_request to an NGINX introspection endpoint, for example:


I guess this need more documentation. So as a seacat user:

what endpoints should I call?

where do I get the credentials?

are those credentials different per each oauth client?

Clarified on call

ateska · 2023-10-16T08:23:10Z

@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?

filipmelik · 2023-10-16T11:57:48Z

seacatauth/openidconnect/handler/introspect.py

@@ -120,7 +120,8 @@ async def introspect(self, request):
 		if "preferred_username" in user_info:
 			response_data["username"] = user_info["preferred_username"]

-		# TODO: Verify that the token is  client_id is included in the aud claim
+		# TODO: Verify that the requesting client is part of the token's intended audience
+		#  (i.e. that their client_id is included in the aud claim).


This will break my usecase in mobile apps. Can we have a call about thiz plz?

i don't intend to implement this check within this merge request (or anytime soon, unless necessary). it would also require implementing a way for the client to influence the content of the audience claim somehow, possibly by scope.

i added the todo as a reminder that the authorization has some limitations and can be improved. the authorization server should not disclose id tokens to just any client. it is mostly fine in environments where there are few clients manually registered by an admin, but not in large environments with open client registration.

Clarified on call

# Conflicts: # CHANGELOG.md # seacatauth/openidconnect/handler/introspect.py # seacatauth/openidconnect/service.py

OIDC introspection draft

85022ea

byewokko added the enhancement New feature or request label Oct 3, 2023

byewokko self-assigned this Oct 3, 2023

byewokko marked this pull request as draft October 3, 2023 15:07

byewokko added 11 commits October 4, 2023 14:53

fix error responses

390d230

Merge branch 'main' into feature/openid-introspection-endpoint

c637efd

use openid issuer in www-authenticate bearer realm

31170b7

flake8

933beaa

require client_id, debugging

5a25408

Update CHANGELOG.md

c9fe28b

remove introspection from discovery

d9673ef

add openapi docs

19c9f14

include only the generic claims listed in the spec

3b9a48f

minimize info disclosure

f6d414b

more meaningful path

5b15b1b

byewokko marked this pull request as ready for review October 11, 2023 10:51

byewokko requested a review from ateska October 11, 2023 10:53

ateska approved these changes Oct 11, 2023

View reviewed changes

Merge branch 'main' into feature/openid-introspection-endpoint

25cbab0

filipmelik reviewed Oct 12, 2023

View reviewed changes

remove client_id parameter, extend docstring

4eb6372

filipmelik reviewed Oct 13, 2023

View reviewed changes

byewokko added 2 commits October 13, 2023 11:34

malformed requests return 400

eabb0a5

clarify TODO

ee68bf7

byewokko marked this pull request as draft October 13, 2023 11:03

byewokko added 2 commits October 13, 2023 13:09

update docstring

30f5dfa

username fallback

601cd9d

clarify TODO

5c8f733

filipmelik reviewed Oct 16, 2023

View reviewed changes

byewokko added 4 commits October 19, 2023 15:22

Merge branch 'main' into feature/openid-introspection-endpoint

129f82b

# Conflicts: # CHANGELOG.md # seacatauth/openidconnect/handler/introspect.py # seacatauth/openidconnect/service.py

Merge branch 'main' into feature/openid-introspection-endpoint

b73086b

fix example

e52f550

Update CHANGELOG.md

b2f2a13

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

OIDC introspection endpoint #295

OIDC introspection endpoint #295

byewokko commented Oct 3, 2023 •

edited

Loading

ateska left a comment

filipmelik commented Oct 12, 2023 •

edited

Loading

ateska commented Oct 12, 2023

filipmelik Oct 12, 2023

byewokko Oct 13, 2023 •

edited

Loading

filipmelik Oct 17, 2023

filipmelik commented Oct 12, 2023

filipmelik Oct 13, 2023

filipmelik Oct 17, 2023

ateska commented Oct 16, 2023 •

edited

Loading

filipmelik Oct 16, 2023

byewokko Oct 16, 2023

filipmelik Oct 17, 2023

		@@ -80,12 +80,12 @@ async def introspect(self, request):
		client_id = params.get("client_id")

OIDC introspection endpoint #295

Are you sure you want to change the base?

OIDC introspection endpoint #295

Conversation

byewokko commented Oct 3, 2023 • edited Loading

Changes

OAuth 2.0 Token Introspection

Example

ateska left a comment

Choose a reason for hiding this comment

filipmelik commented Oct 12, 2023 • edited Loading

ateska commented Oct 12, 2023

filipmelik Oct 12, 2023

Choose a reason for hiding this comment

byewokko Oct 13, 2023 • edited Loading

Choose a reason for hiding this comment

filipmelik Oct 17, 2023

Choose a reason for hiding this comment

filipmelik commented Oct 12, 2023

filipmelik Oct 13, 2023

Choose a reason for hiding this comment

filipmelik Oct 17, 2023

Choose a reason for hiding this comment

ateska commented Oct 16, 2023 • edited Loading

filipmelik Oct 16, 2023

Choose a reason for hiding this comment

byewokko Oct 16, 2023

Choose a reason for hiding this comment

filipmelik Oct 17, 2023

Choose a reason for hiding this comment

byewokko commented Oct 3, 2023 •

edited

Loading

filipmelik commented Oct 12, 2023 •

edited

Loading

byewokko Oct 13, 2023 •

edited

Loading

ateska commented Oct 16, 2023 •

edited

Loading