In this article Janua’s CTO shares tips and tricks about understanding token usage in Keycloak
Keycloak Token lifecycle is described at:
- Token lifecycle is defined on a per realm basis
Understanding Keycloak session scope
A keycloak session is created
- once a user authenticates to keycloak.
- The session is visible in the session list.
Once authenticated through a user session, the user can:
- navigate through the different application of the realm (SSO mechanism)
- user logout action
Session Idle Timeout
- This means that if the user has performed no actions during a predefined amount of time (called idle tile), the session expires by itself
- The default value is 30mn
Session max Duration
- This is the maximum time a session can last
- the default value is 10h
Importance of session control – potential security vulnerability
As mentioned earlier, a user session allows to navigate through all the different application of the realm.
It is very important being able to control user sessions, and to destroy the user session as soon a user no longer needs the session.
Session control can be enforced by:
- Session idle Timeout
- Session max duration
Keycloak Access Token
An access token is a token delivered by they keycloak server, and which allows an application to access to a resource.
Access token lifecycle operations are:
delivered by the keycloak server to the client
very short life-span
(usually not more than a few minutes) . 1 mn for keycloak
(1) Client app is presenting
access token to the resource server
(2) Resource Server validates the access token to verify if the client app is allowed to access resource or not.
Offline access token
Offline token is a specific usage of refresh token where refresh tokens have an indefinite timelifespan (By default 60 days in keycloak).
Methods to deliver an access token
There are 2 ways to deliver an access token:
user customer authenticating to keycloak throughout the
(This is generating a id_token and optionally access token as soon as user customer is authenticated)
- Using an offline token to request a refresh token, and from the refresh token an access token.
Offline token presentation
Below are the key definition provided for offline access
- 1st is for keycloak
- 2nd is the one pertaining to the openid core spec itself.
|Offline access is a feature described in OpenID Connect specification . The idea is that during login, your client application will request an Offline token instead of a classic Refresh token. The application can save this offline token in a database or on disk and can use it later even if user is logged out. This is useful if your application needs to do some « offline » actions on behalf of user even when the user is not online. An example is a periodic backup of some data every night. Your application is responsible for persisting the offline token in some storage (usually a database) and then using it to manually retrieve new access token from Keycloak server.
OpenID Connect defines the
following scope value to request offline access:
OPTIONAL. This scope value
requests that an OAuth 2.0 Refresh Token be issued that can be
used to obtain an Access Token that grants access to the
End-User’s UserInfo Endpoint even when the End-User is not present
(not logged in).
When offline access is
requested, a prompt parameter value of consent
MUST be used unless other conditions for processing the request
permitting offline access to the requested resources are in place.
The OP MUST always obtain consent to returning a Refresh Token
that enables offline access to the requested resources. A
previously saved user consent is not always sufficient to grant
Upon receipt of a scope
parameter containing the offline_access value, the
MUST ensure that the
prompt parameter contains consent unless other
conditions for processing the request permitting offline access
to the requested resources are in place; unless one or both of
these conditions are fulfilled, then it MUST ignore the
MUST ignore the
offline_access request unless the Client is using a
response_type value that would result in an
Authorization Code being returned,
MUST explicitly receive
or have consent for all Clients when the registered
application_type is web,
SHOULD explicitly receive
or have consent for all Clients when the registered
application_type is native.
The use of Refresh Tokens is not
exclusive to the offline_access use case. The
Authorization Server MAY grant Refresh Tokens in other contexts
that are beyond the scope of this specification.
How to use keycloak offline token
- Offline tokens can have very long living period (keycloak default is 1 month – but it can be much more)
- It is up to the customer to manage offline token (store in a database)
- A user needs to have offline security role to manipulate offline tokens
You needs to specify
in the OIDC request
to get an offline token
offline token can also be manipulated using direct authentication flow
Difference between an offline and refresh token
refresh token is subject to
SSO Session Idle timeout(30mn -default) and
SSO Session Max lifespan
(10hours-default) whereas offline token never expires
Session Max Limited
- When offline session max limited mode is activated, the offline token expires after 60 days regardless of using the offline token for a refresh token action.
Lifecycle of offline token
As explained before, offline tokens is a kind of special refresh token with an almost indefinite lifespan (offline session max).
Offline token creation
- Offline access token token are created when the user specify scope=offline in the OIDC request
Offline token flow operations
Offline tokens can be obtained either throughout
- authorization code flow
- Direct grant (Read only password credential)
Offline token usage – getting an access token
- Offline access token are “kind of special access token”, and have to be used in the way as regular “refresh token” to ask the keycloak server to deliver an access token
- The user has to store the offline token in his own environment
Revoking offline token
Off line tokens can be revoked either:
- by the console administrator going to the consent tab of a specific user, and checking for the for the consent tab all the offline tokens
- by the user himself, revoking the corresponding application