How to specify refresh tokens lifespan in Keycloak

As pointed out in the comments by @Kuba Šimonovský the accepted answer is missing other important factors:

Actually, it is much much much more complicated.

TL;DR One can infer that the refresh token lifespan will be equal to the smallest value among (SSO Session Idle, Client Session Idle, SSO Session Max, and Client Session Max).


After having spent some time looking into this, and now looking back at this thread, I feel that the previous answers felt short to explain in detail what is going on (one might even argue that they are wrong actually).

Let us assume for now that we only have SSO Session Idle and SSO Session Max:

  • and SSO Session Max > SSO Session Idle in this case the refresh token lifetime is the same as SSO Session Idle. Why? because if the application is idle for SSO Session Idle time the user gets logout and that is why the refresh token is bound to that value. Whenever the application requests a new token, both the refresh token lifetime and SSO Session Idle countdown values will be reset again;
  • and SSO Session Max <= SSO Session Idle then the refresh token lifetime will be the same as SSO Session Max. Why? because regardless of what the user does (i.e., idle or not) the user gets logout after SSO Session Max time, and thus why the refresh token is bound to that value.

From here we conclude that the refresh token lifespan is bound to the lowest of the two values SSO Session Idle and SSO Session Max.

Both those values are related to Single Sign-ON (SSO). We still need to consider the values of the Client Session Idle and Client Session Max fields of the realm settings, which when NOT set are the same as SSO Session Idle and SSO Session Max, respectively.

If those values are set, in the context of the refresh token, they will override the values from SSO Session Idle and SSO Session Max, BUT only if they are lower than the values from SSO Session Idle and SSO Session Max.

Let us see the following examples: SSO Session Idle = 1800 seconds, SSO Session Max = 10 hours and:

  1. Client Session Idle = 600 seconds and Client Session Max = 1 hour. In this case, the refresh token lifespan is the same as Client Session Idle;
  2. Client Session Idle = 600 seconds and Client Session Max = 60 seconds. In this case, the refresh token lifespan is the same as Client Session Max.
  3. Client Session Idle = 1 day and Client Session Max = 10 Days. In this case, the refresh token lifespan is the same as SSO Session Idle;

So in short you can infer that refresh token lifespan will be equal to the smallest value between (SSO Session Idle, Client Session Idle, SSO Session Max, and Client Session Max).

So the claim from previous answers that you can simply use the Client Session Max to control the refresh token lifespan is FALSE. One just needs to look at the previous examples 1) and 3).

Finally, the fields Client Session Idle and Client Session Max from the realm settings can be overwritten by the Client Session Idle and Client Session Max in the clients themselves, which will affect the refresh token lifespan for that client in particular.

The same logic applies but instead of considering the values Client Session Idle and Client Session Max from the realm settings one needs to consider those from the client advance settings.


The refresh token lifetime is controlled by the SSO Session Idle Setting. 30 minutes = 30 * 60 = 1800 seconds (the refresh_expires_in value)