[keycloak-user] token introspection

[Bill Burke]

On 8/10/17 9:45 AM, Doug Drouillard wrote:
> You don't necessarily 'need' it, but it makes the project an order of
> magnitude more complicated to understand.  The adapters are magic, but if
> we aren't already familiar with something like Spring, then we really have
> no way to fully understand what is going on. The other adapters such as
> undertow as equally as intense. We don't need to understand all
> infrastructure of course, but given there is an integration into an
> existing workflow it makes it hard to use.
You don't need token introspection if you are following the OAuth2 
protocol correctly.  Token introspection is redundant in this case. It 
is only potentially useful for validating bearer token requests 
depending on the access token implementation.
> I would contribute a simple / clean Java example but I am still not sure
> what that would even mean. Most threads I see around inspection say just
> use XXX and don't worry. But I have found that to be dubious.
>
> The aerogear team used using a Auth0 JWT inspection library which seems
> like it is working.
>
> The project is very well documented and there are tons of examples, but I
> see every 2 weeks or so someone asks about token introspection as they are
> trying to learn the best way to use Keycloak and basically get 3 responses
> in until they get a 'dont worry about it' response, which really doesn't
> help as it is rare to solve a more complicated problem without
> understanding the basic problem.
Keycloak access tokens are digitally signed by the realm.  This is 
spelled out in our documentation.  For bearer token requests, our 
adapters validate this signature against the public key of the realm.  
Keycloak token introspection is only useful for determining if the 
access token has been revoked within the allowable timeout of the 
token.  Our adapters don't support token introspection.  We do not 
recommend token introspection for bearer token requests because then the 
Keycloak auth server would basically have to scale one-to-one with all 
the bearer token requests of every single service on your network.

> We get the fear of missing using token inspection, but it sucks as a user
> not to be able to get a clear example of 'Here is how you used to do it
> with manually token inspection, now compare to the adapters' as opposed to
> 'read this intense doc and just simply integrate this adapter which you
> don't understand' which has been what I have personally seen in digging
> through 3 years of emails. Or the even better - "just google for industry
> best practices on token inspection and use the existing libraries". For you
> on the team it probably seems like such a trivial use case not even worth
> mentioning but if you are new to Oauth/Keycloak/JWT and adapters, a simple
> use case even if it was absolutely evil and going to cause WW3 would be
> useful. Even as a blog post.
>
> The use case is, I use keycloak to do a social sign-in, I get the token
> back, using only self-contained Java (so calling libraries but not using
> any json configs or adapters), how would I inspect the token to pull out
> the email address and verify that token is still valid and actually came
> from my keycloak server instead of being spoofed?
I think your complaints are misguided.  Either you trust the adapter's 
"magic" or you learn and completely understand the protocols yourself.  
In your particular example, you know that the email address, etc. that 
you pull out is not being spoofed because you are doing the OAuth2 auth 
code flow using HTTPS and your client HTTP library should be validating 
the cert when setting up an SSL connection to make the code to token 
exchange.   This is completely spelled out in the OAuth2 and OpenID 
Connect specifications.


>
> I know this is what adapters/json configs do for you (at least in theory, I
> never got adapters to work), and there are existing libraries, but an all
> in one laid out example direct from keycloak team would be awesome!
Sounds like you are implying that our adapters don't work?  Must be user 
error on your part.  If you want to criticize our docs and say they 
suck, that's perfectly fine.  But to imply our adapters don't work is 
just plain wrong.  Granted it can be difficult to debug setup issues at 
times, but our adapters don't work "in theory" ...The project is 4+ 
years old now and to imply that something as fundamental as our adapters 
don't work is well tiny bit insulting :)

As far as a "laid out example":  example on what?  There are a ton of 
examples for setting up adapters.  Keyclaok admin console can even 
generate a config file for you.  If you want a "laid out example" of 
manually coding the OpenID connect or SAML protocols in Java...well, 
there you are on your own.  We are OpenID Connect certified so, if you 
learn the protocol you should be able to manually code anything you 
want.  IMO, OAuth2 and OpenID connect specifications are easy enough to 
understand.

What is missing I think is documentation on how to validate bearer 
tokens if you are not using our adapters or security proxy. 
KEYCLOAK-5287 was just created and scheduled by me to track this.

Bill