Add support for proxying introspection requests

[NicolasLiampotis]

Extend Keycloak introspection endpoint with support for checking the validity and signatures of OAuth tokens for trusted OAuth2 authorisation servers.

Keycloak will only introspect JWT access tokens that contain the iss claim.

It assumes that Keycoak is registered as a client at one (or more) trusted OAuth authorization servers, and is used by client applications as a gateway for token validation and introspection.

Keycloak will perform local JWT validation checks and leverage the introspection endpoints at trusted AS to inspect a submitted token.

The result of a token introspection will be cached, if caching is enabled.

[cgeorgilakis]

In case of error in Keycloak part (f.e. issuer does not exist in OIDC IdPs) should I return only active field with value false?
Keycloak do it for many error cases ( f.e VerificationException, Client does not exist etc).

[NicolasLiampotis]

In case of error in Keycloak part (f.e. issuer does not exist in OIDC IdPs) should I return only active field with value false? Keycloak do it for many error cases ( f.e VerificationException, Client does not exist etc).

What is the vanilla behaviour if you supply an unknown token to the introspection endpoint?

[cgeorgilakis]

It returns {active: 'false'}. I keep the same behaviour if I can not get issuer from token.

[NicolasLiampotis]

Related to caching:

• It should be possible to enable caching (defaults to disabled)
• If enabled it should be possible to configure
  • the max number of tokens stored in the cache before evicting old entries (defaults to 1000)
  • the eviction time policy (defaults to 60 sec)

We also need to investigate whether we should validate tokens (i.e. check that the token has been signed by the identified issuer) before proxying the request to the remote introspection endpoint

[cgeorgilakis]

We need to decide if we will implement as an extension or keep it separate branch. Although changes are lot, they are not combined with Keycloak code ( only in AccessTokenProvider). So, this is an acceptable solution.

For an extension :

• Maybe remove AccessTokenProvider and add our custom AccessTokenProvider. It is possible with configuration. If we do it dynamically, we should investigate if it is working with Keycloak X
• redirect url for our custom introspection endpoint
• custom introspection endpoint - change .well-known endpoint.

Cache implementation - ideally support for cluster - need further investigation and core/ extension must be taken into account.

[cgeorgilakis]

First implementation( without cache - validation) is ready in branch 140-introspection and deployed in https://kctestserver.ddns.net/auth.

[cgeorgilakis]

• Validity check before calling remote trust authorities
• Cache token - response for a period ( 5 minutes?)

[NicolasLiampotis]

For the Access Token JWT structure our implementation should comply with https://www.rfc-editor.org/rfc/rfc9068.html#name-data-structure

Does the Keycloak and the MITREid Connect implementation already follow that RFC at least for the token expiration information?

[cgeorgilakis]

From documentation part '2.2. Data Structure' Keycloak AccessToken class only does not have client_id. It has also auth_time and acr from '2.2.1' and other fields.

From my part I use only fields iss and exp for external access tokens.

[cgeorgilakis]

Moreover, Keycloak for any token problem including expired token return only

{"active" : false}

I return the same for expired token. Is it ok?

[NicolasLiampotis]

Moreover, Keycloak for any token problem including expired token return only

{"active" : false}

I return the same for expired token. Is it ok?

Yes this should be sufficient.

Do we need some other claim for validating the signature of the token?

[cgeorgilakis]

No. Taken into account that we agree that Keycloak will only check token expiration.
Further token process is done by external service. We will cache Map with key the token and value the response.

[cgeorgilakis]

Main implementation is done.
We need to see how we will configure cache parameters and if it is possible to make it extension.