Offline access is a feature of OpenID Connect defined at https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess. It allows the application with an offline token (a kind of refresh token) to get access token and use resources without the user having to log in, for a long time or forever. Keycloak supports us to work with offline access using offline tokens. How is it in detail? Let’s find out together in this tutorial!
As an example, I will create a new client with the grant type Authorization Code in Keycloak as follows:
The first thing you need to know is how we get the offline token.
Very simply, in the request to get the authorization code for the client, we need to pass an additional scope of offline_access:
Keycloak will ask if we allow Client Application Offline Access or not?
If you agree, after having the authorization code, request to get the access token for this client:
parse the content of the refresh token, you will see the payload content as follows:
The type of this token is Offline instead of Refresh and you can see, there is no “exp” claim with expiration time like when we parse the access token:
We can use this offline token to get a new access token similar to a refresh token.
The example is as follows:
The difference between an offline token and a refresh token is that there is no expiration time for an offline token.
By default, the offline token is valid even if the user is not logged in or the server is restarted, unless it is revoked. However, you need to use this offline token at least once within the default period of 30 days from the last use. That’s because an offline token will associate with an offline session. And this offline session only has the default idle time of 30 days as I said above. At the Realm level, this 30-day value is configured in the Session tab of Realm Settings, Offline session settings section, the Offline Session Idle field:
In this Offline session settings section, as you can see, we have another field related to offline sessions, named Offline Session Max Limited. The meaning of this field is that if you enable it, the offline token will be expired in the default time of 60 days, no matter how many times we use this offline token:
In older versions, Keycloak allows us to override offline session related configurations at Client level and allows us to view all Offline tokens that have been issued to the client. But with the version that I am using v19.x, it seems that Keycloak has removed these features. If you know where these configurations are located, please let me know in the comments!
