In this article we share examples of offline token usage in Keycloak.

As mentioned previously, it is possible to generate offline either through direct access grant or authorization code flow.

Both way are going to be illustrated in this chapter

Using offline Token through direct access grant flow
Requirement

The requirement is to have:

  • a client application deployed within a realm
  • a user created in this realm, who has got off_line role
Token lifespan

For the example, token lifespan has been adjusted as follows:

  • SSO session Idele Timeout: 1mn
    (a.k.a Refresh token validity is 1minute)
  • Access token: 1 min
  • OffLine Tokens: 60 days
Examples of offline token usage in Keycloak
Setting the maximum invokation of refresh token

It is possible to the maximum number amount of times a refresh token can be reused, before being ineffective

This is done using:

  • The revoke refresh token toggle
  • indicates the maximum number of times a refresh token can be reused
Examples of offline token usage in Keycloak

If limit was to be reached, following error message would be issued:

Script used to offline token
Explanation of the script

Part 1

Within this part:

  • The user is connecting to keycloak through direct access grant flow
  • the request contains scope=openid info offline_access
    • This allows to generate an refresh tokenof type offline
  • The refresh token is extracted from the request

The refresh token issued from such a request is JWT token, and has got
« typ »: « Offline ».
(For normal refresh token, the typ is “Refresh”)

Part 2

The script is using the refresh token generated in first step

  • It is reusing the same refresh token
  • Each time time, a new access token is issued
Revoking the offline token

The revokation of the offline token can be done in 2 places:

  • Through the admin console
  • By the the user himself
Revokation of the offline token through the admin UI
Examples of offline token usage in Keycloak

The admin user has select the “Revoke” action to revoke the offline token.

Through the user self service panel

The user access to the self-service panel, from where he can revoke the grant “offline access”, as action

Examples of offline token usage in Keycloak
Necessity of adding offline in client request scope

Request without client scope

Normal refresh token request

TO be noticed:

  • The payload of the refresh token is of type “Refresh”
  • The “exp” (expiry date) is 60s larger than the “iat” (issuance time)
Request with client scope

Resuest with scope=offline to request an offline token

TO be noticed:

  • The payload of the refresh token is of type “OffLine”
  • The “exp” (expiry date) is 0
Keycloak offline example

Keycloak provides an offline demo example to showcase, how it is possible to used offline tokens with Java performing authorization code flow.

The example is available at:

Step1 – User needs to log to the app – An offline access token is generated
Examples of offline token usage in Keycloak
Step 2 – user logs out from app

The off line access token is still valid

step3 – the app can access to the resources using the offline access token
Examples of offline token usage in Keycloak
Olivier Rivat

Olivier Rivat

Senior Software Engineer with over 25 years of experience doing Software Development, Support and Consulting in Identity and Access Management Solutions.
Specialised in IAM (security, access control, identity management) and Open Source integration, settled in 2004 by IAM industry veteran, JANUA offers high value-added products and services to businesses and governements with a concern for Identity Management and Open Source components.
JANUA provides better security, build relationships, and enable new cloud, mobile, and IoT offerings from any device or connected thing.
Olivier Rivat