Understanding token usage in Keycloak

par | Fév 19, 2019 | Gestion des Identités, SSO

In this article Janua’s CTO shares tips and tricks about understanding token usage in Keycloak

Keycloak Token lifecycle is described at:

Understanding Token usage in Keycloak
Token Lifecycle
  • Token lifecycle is defined on a per realm basis
Understanding Keycloak session scope
session creation

A keycloak session is created

  • once a user authenticates to keycloak.
  • The session is visible in the session list.
Session usage

Once authenticated through a user session, the user can:

  • navigate through the different application of the realm (SSO mechanism)
Session termination
  • 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.

https://tools.ietf.org/html/rfc6750

Understanding Token usage in Keycloak
Access token lifecycle operations are: delivered by the keycloak server to the client application very short life-span (usually not more than a few minutes) . 1 mn for keycloak access token (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 client app
    (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.

https://www.keycloak.org/docs/latest/server_admin/index.html#_offline-access

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.

https://openid.net/specs/openid-connect-core-1_0.html#OfflineAccess

Offline Access OpenID Connect defines the following scope value to request offline access: 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 offline access. Upon receipt of a scope parameter containing the offline_access value, the Authorization Server: 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 offline_access request, 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 scope=offline_accessin the OIDC requestto 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
Offline Session Max Limited
Understanding Token usage in Keycloak
  • 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
janua
Les derniers articles par janua (tout voir)