OIDC Automatic token refresh

[pmaciek]

Hi
I am wondering how automatic code refreshment works internally. Is it some cron/quartz job which checks available tokens in session against expiration time ? Can you clarify it to me or point out relevant source code area ?
Thanks

[quarkus-bot[bot]]

/cc @pedroigor (oidc), @sberyozkin (oidc)

[sberyozkin]

Hi @pmaciek

When an already authenticated user accesses Quarkus, the expiry time of the ID token associated with the session cookie is checked, if the token has expired then if the refresh token is available and refreshing tokens is allowed, the tokens will be refreshed.

To minimize the possibility of the browser dropping the session cookie when the cookie has expired, one can extend the session cookie lifespan with the configuration. Extending the cookie age does not extend the ID token age, only makes sure the tokens associated with the session cookie are made available to Quarkus, for it to check the ID token's expiry date, etc

One can also use a proactive refreshment of the ID token which is still valid but has nearly expired by configuring a refresh skew - it requires a script using a background thread to ping the Quarkus endpoint every few mins or so.

See https://quarkus.io/guides/security-oidc-code-flow-authentication#session-management for more info

[pmaciek]

Thanks @sberyozkin for reply.
So setting only refresh skew time param has no effect itself. It requires pinging Quarkus endpoint with proper ratio as well to make it working, right ?

Regarding extending cookie age, does it guarantee that token will be refreshed within current request without 401 error ?
I want to avoid 401 errors and wondering which strategy gives more guarantee for thatt ?

[sberyozkin]

@pmaciek Refreshing the token is driven by the authenticated user accessing the Quarkus endpoint and letting it analyze the tokens associated with the session cookie, there is no any crone/quartz job running on the server.
As I said, there are 2 options generally available:

• User accesses the endpoint, Quarkus finds out the ID token has expired, it refreshes the tokens. Extending the cookie age which you asked about is only about making sure there is a higher chance of the browser not dropping the expired session cookie, so that it can make it back to Quarkus when the user accesses it and for the ID token expiry time be checked
• Refresh skew time param does make it possible to refresh the session while ID token is still valid, but it requires SPA ping Quarkus periodically. It works, if enabled, in tandem with the first option, and minimizes even further the possibility of the browser dropping the expired session cookie.

Howevee, despite whatever is configured, there is always a small window that for example a user will stay idle for too long, longer than the extended cookie age, or, the OIDC provider restricts a number of times the tokens can be refreshed, etc, if for whatever reasons the tokens can not be refreshed, all that should happen is that the user will be redirected to the OIDC provider to re-authenticate, which is a normal procedure when the user is idle for too long.

401 must not be happening with the latest released Quarkus versions, if you are seeing 401 after the token has expired then please open a bug issue with a reproducer and I'll have a look

[sberyozkin]

Tokens are kept by default in the encrypted form in the session cookie, so a Quartz job approach does not really work.
It might be considered when the tokens are stored in the DB with the quarkus-oidc-db-token-state-manager, but if the user just closes the browser this timer will keep going forever, and then another question, is, how it will manage 1000s of authenticated users. So all in all, IMHO, it is not really a practical option even in when the tokens are stored in the DB

[pmaciek]

@sberyozkin thank you for clarifications.
I don't know whether is bug or not. I am using quarkus 3.2.3.Final and I am getting 401 error occasionally with enabled flag quarkus.oidc-client.token.refresh-expired=true

14:02:48.152 DEBUG [io.qu.oi.cl.ru.OidcClientImpl] (vert.x-eventloop-thread-0) OidcClient has acquired the tokens, uuid=xxx
14:12:48.003 ERROR [] (executor-thread-2) api error: 401
14:12:49.165 DEBUG [io.qu.oi.cl.ru.OidcClientImpl] (vert.x-eventloop-thread-1) OidcClient has acquired the tokens, uuid=xxx

10 min lifespan I have

Setting quarkus.oidc.token.refresh-token-time-skew seems to eliminate this error fully but in fact this depends on pinging ratio. After setting this one I can see logs with message "OidcClient has refreshed the tokens" which is not visible for previous case with refresh-expired=true only. So seems for me that with refresh-expired=true refresh doesn't work for some reasons.
Is my understanding correct ?

[sberyozkin]

@pmaciek Unfortunately everything what I said can be ignored because now that you have given the example, I see that you don't use quarkus-oidc but use quarkus-oidc-client, I should've asked for more details earlier.

OIDC client is totally independent from the server side OIDC adapter which is what I thought you were using.

So OIDC client checks if the access token has expired and if yes it refreshes it. But what can happen is that it can propagate a nearly expired token and 401 will be returned as by the time it reaches the target, it will be expired possibly due to the clock issues.

To minimise the risk of 401, you can also use the refresh skew, but in the quarkus.oidc-client namespace, and that should bring the possibility of 401 to nearly 0.

HTH

[sberyozkin]

OIDC client can run in scope of the request which was verified with quarkus-oidc, but these extensions are totally independent

[pmaciek]

Yes, sorry for confusion, I tried with quarkus.oidc-client.refresh-token-time-skew, not quarkus.oidc.token.refresh-token-time-skew as in my preview message.
Now I see that I used "refresh-expired" incorrectly because it doesn't exist on "oidc-client" namespace. That's why it doesn't work :-)
Thanks for help

[sberyozkin]

@pmaciek Np, so do you have it working now as expected with quarkus.oidc-client.refresh-token-time-skew ? I read it as yes but let me know please if you continue seeing too many 401s.
FYI, even with the refresh skew, there could be some very small window where a nearly expired token is sent to the target, so a REST client should be prepared to retry in such cases where 401 does trickle through, OIDC Client filter itself can't do it, it is a ClientRequestFilter and even if it implemented ClientResponseFilter it would still not be able to rewind the request chain. So, 401 can be handled with a fault tolerance retry or simply with a single manual retry which should do since if 401 was caused by the expired token then this time OIDC client will definitely get a new token