Session Timeout

This plugin adds a session timeout dialog to a CASA application to warn users their session is about to expire. It is based on the HMRC service timeout pattern, and uses hmrc-frontend's timeout-dialog nunjucks component.

Installation

npm install @dwp/casa-session-timeout-plugin

Usage

import { configure } from "@dwp/govuk-casa";
import sessionTimeoutPlugin from "@dwp/casa-session-timeout-plugin";

const casa = configure({
  ...
  plugins: [
    sessionTimeoutPlugin({
      // Optional configuration
      // 
      // Time left in seconds of the CASA session time to live before the
      // timeout dialog appears. Default: 300 (5 minutes).
      countdown: 300,
      // URL of user sign out / end session link. Default: ended-session route
      // provided by this plugin, will terminate the users session and send them
      // to the 'ended-session' page.
      signOutUrl: "/sign-out",
      // URL to start again, used on default ended-session page. Will default to
      // CASA mountUrl config option.
      startAgainUrl: "/start-page",
      // Whether to serve static assets and add styles and JavaScript to pages,
      // disable if you're building your own assets or are already including
      // HMRC Frontend. Default: true.
      includeAssets: false,
    }),
  ],
});

Overriding content

By adding a locale file named casa-session-timeout-plugin.json to your CASA application you can override the default content in the timeout dialog component.

By default, the component as the following content, you can replace any of it by including a file with the same locale message keys:

{
  "heading": "You’re about to be signed out",
  // In the component this message will end with the time remaining
  "message": "For your security, we will sign you out in",
  "keepAliveButtonText": "Stay signed in",
  "signOutButtonText": "Sign out"
}

For example, a service without a sign in/sign out user login process:

{
  "heading": "Your session is about to end",
  "message": "For your security, we will delete your answers in",
  "keepAliveButton": "Continue applying for Pension Credit",
  "deleteYourAnswers": "Delete your answers"
}

You can also override the content of the ended-session page by adding a locale file named casa-session-timeout-plugin-end-sesion.json:

{
  "pageTitle": "You deleted your answers",
  "startAgain": "Start again"
}

Or override the page completely by including a template in the following path:

└── your-views-folder
    └── casa-session-timeout-plugin
        └── end-session.njk

Disabling the timeout dialog

The dialog will be injected into every page, but you can disable it on a per page basis by setting timeoutDialogEnabled to false in your template:

{% extends "casa/layouts/journey.njk" %}

{# Disable the timeout dialog on this page #}
{% set timeoutDialogEnabled = false %}

{% block casaPageTitle %}
  Your claim has been submitted
{% endblock %}

Building your own frontend assets

If you're building your own frontend assets or already including hmrc-frontend in your application, you should disable the loading and serving of the assets bundled with this plugin:

const casa = configure({
  ...
  plugins: [sessionTimeoutPlugin({ includeAssets: false })],
});

This plugin includes a version of the HMRC Timeout Dialog component wrapped in a GOV.UK Frontend Component class, making it easier to integrate with an existing govuk-frontend based build:

import { Button, Radios, createAll } from "govuk-frontend";
import { HMRCTimeoutDialog } from "@dwp/casa-session-timeout-plugin/frontend";

createAll(Button);
createAll(Radios);
createAll(HMRCTimeoutDialog);

You can also include the hmrc-frontent SASS for the component directly from this package if you aren't installing hmrc-frontend already:

$assets: "govuk-frontend/dist/govuk/assets/";

@use "pkg:govuk-frontend" as * with ($govuk-assets-path: $assets);
@use "pkg:@dwp/casa-session-timeout-plugin" with ($govuk-assets-path: $assets);

This example requires node package resolution which can be built as follows:

sass --pkg-importer=node -I node_modules ./assets/my-styles.scss