Skip to main content

Token-renewed Sessions

Once the End User is logged in to the Impact Finance Web App, the authenticated session must be

  1. kept alive as long as the End User is actively using the app, and
  2. (optionally) closed after a period of inactivity.

This document describes how to achieve these two tasks with "token-renewed" sessions.

Keep-alive​

On log in, the session gets an expiration timestamp which is the same as the IDToken's exp claim. With 30 seconds margin before this expiration time, the Web App notifies your Bank App that that token expiration is about to happen by sending an onIdTokenDidExpire event. In order to keep the session alive, the Bank App must now generate a new ID Token and hand back to the Web App with the updateToken event to renew the session. If a new valid ID token is not handed back to the Web App in time, the End User will be logged out and the Web App will request to be closed down by sending an onExitRequested event.

sequenceDiagram participant bfe as Bank App participant sdk as DES SDK + Web App Frontend participant des as DES Backend participant bbe as Bank Backend sdk ->>+ bfe: callback: onIdTokenDidExpire bfe --> bbe: Get new token bfe -->>- sdk: completion success: updateToken sdk ->> des: update session (w. token) des ->> des: Validate token note over des: update session expiry to new token `exp` alt invalid des -->> sdk: Unauthorized sdk ->> bfe: callback: Exist Requested bfe ->> bfe: close down Impact Finance Web App else valid des -->> sdk: OK end

Signing Out on Inactivity​

To provide a fail-safe mechanism to detect inactivity, the Impact Finance Web App does not track absence of activity itself. Instead, it relies on sending positive indications of activity to your Bank App through TelemetryEvents. As long as your Bank App receives these events, the End User can be considered to be actively using the Web App. Conversely, the absence of such events is indicating inactivity. This makes sure that inactivity can be detected even in the case of communication failure between the Web App and the embedding application.

We assume that your Bank App already has measures and functionality in place to handle inactivity (e.g. asking the user "Are you there?") and leave it up to you to jack in to this functionality for a seamless and coherent user experience.

NOTE: The TokenDidExpire event is not an indicator of activity from the End User. If the ID Token expiration time is shorter than the inactivity time limit, the inactivity timer must not be reset on token renewal to prevent the session from being extended indefinitely.

sequenceDiagram participant bfe as Bank App participant sdk as DES SDK + Web App Frontend participant des as DES Backend participant bbe as Bank Backend note over bfe: Start inactivity timer sdk ->> bfe: TelemetryEvent note over bfe: Restart inactivity timer sdk ->> bfe: TelemetryEvent note over bfe: Restart inactivity timer bfe -->> bfe: time passes sdk ->>+ bfe: TokenDidExpire note over bfe: renew the token, but do not<br />reset inactivity timer bfe -->>- sdk: token bfe -->> bfe: time passes note over bfe: inactivity timer times out:<br />show "Are you there?" prompt alt yes note over bfe: restart inactivity timer else no response bfe -->> bfe: wait note over bfe: Log out end