Session Timeout

Overview

For security reasons, applications that require user authentication will typically end the user’s session after the user has been inactive for a certain period of time. Some applications end the user’s session after the user has been logged in for a certain period of time, regardless of user activity.

In many cases the user interface has advance knowledge of this session timeout — it may even be enforcing that timeout — and can warn the user ahead of time.

In other cases, the session timeout happens at lower levels of the software; the user interface only discovers that the user’s session has timed out after the fact.

We discuss both of these cases below.

Timeouts where the user interface has advance knowledge

If the user interface has knowledge that the user’s session will time out soon, it should warn the user before the timeout occurs.

Most timeouts are based on user inactivity, so each action taken by the user should reset the inactivity timer.

• Some apps consider any interaction with the user interface to count as user activity, including moving the mouse and typing. This is the preferred approach.
• Other apps may only consider actions that trigger interactions with the back end as user activity.

Other timeouts are a time limit based on when the user authenticated and cannot be reset by user activity. In these circumstances, the app should warn the user of the impending timeout but cannot reset the timeout.

Regardless of the type of timeout, the session timeout warning should:

• Be highly visible
• Persist until the timeout occurs, user activity resets the timeout, or the user logs out
• Should not prevent the user from continuing to work in the app
• If known, display the time remaining before the timeout occurs
• Optionally provide a way for the user to extend their session
• Optionally provide a way for the user to log out immediately

After a user’s session times out, the app should:

• Hide the session timeout warning if displayed.
• Notify the user that their session has timed out.
• Provide a way for the user to log back in.

Timeouts where the user interface does not have advance knowledge

Some user interfaces don’t have advance knowledge of impending session timeouts and only discover that the user’s session has timed out when they attempt to communicate with lower levels of the software. In these cases it isn’t possible to warn the user in advance.

These apps should notify the user that their session has timed out and provide a way for the user to log back in.

Development

Web component development

There are two parts to properly handling session timeouts for your users:

• If your application has advance notice of an upcoming session timeout, it should warn the user of this.
• After the user’s session has timed out, your application should notify the user that a session timeout occurred and offer them a quick link to log in again.

The following sections show how to implement these two activities.

Displaying a session timeout warning

Use custom events to warn the user about an upcoming session timeout.

Your app must use the jha-app component in app.component.html in order to display a session timeout warning. The jha-app component manages the session timeout interface internally based on custom events you fire.

Showing the session timeout warning

To show a session timeout warning, send the rui-show-session-timeout custom event.

The event’s detail is an object with the following fields:

• timeoutRemaining: This is a string that identifies the approximate number of seconds left before the user’s session times out. Pass a value of ’none’ if you don’t know how much time is left in the user’s session.
• extendSessionCallback: This is a callback function that will be called when the user presses the optional “Extend my Session” button.
  • Pass a value of null if you don’t want to offer this functionality, otherwise pass a callback function. Only display this button if this warning is for an inactivity timeout that your application is able to extend.
  • If you display this button, the callback function will need to perform logic appropriate for your application in order to extend the user’s session when the user presses it.
  • The session timeout warning will automatically hide when the user presses this button.
  • If your callback functions reference “this” within your TypeScript, you must either use lambda notation or pass the value of “this” to a standard callback function. Otherwise “this” will refer to a context other than your TypeScript component, which is typically not what you want.
  • IMPORTANT: You should still display the “Extend my Session” button even if your app extends the user’s session automatically based on mouse movements or keystrokes. This button gives the user something visible to “reach for” during an impending session timeout, otherwise they may not understand that simple mouse movements will extend their session time and be frustrated about how they can continue their session.
• logOutCallback: This is a callback function that will be called when the user presses the optional “Log Out” button.
  • Pass a value of null if you don’t want to offer this functionality, otherwise pass a callback function.
  • If you display this button, you’ll need to log the user out when the user presses it.
  • The session timeout warning will automatically hide when the user presses this button.
  • If your callback functions reference “this” within your TypeScript, you must either use lambda notation or pass the value of “this” to a standard callback function. Otherwise “this” will refer to a context other than your TypeScript component, which is typically not what you want.
  • It’s a nice touch to include this button within the session timeout warning, even though your app provides a Log Out option in the header or nav. This local Log Out option makes it quick and easy for the user to respond to the session timeout warning without having to look for the primary Log Out option.

In the example below, we fire the rui-show-session-timeout custom event with detail specifying the remaining number of seconds, a callback for the “Extend my Session” button, and a callback for the “Log Out” button. The jha-app component receives this event and shows the session timeout.

let showSessionTimeoutEvent = new CustomEvent('rui-show-session-timeout',
{
    detail: {
        timeoutRemaining: this.getRemainingTimeText(),
        extendSessionCallback: () => { this.extendSession() },
        logOutCallback: () => { this.logOut() }
    },
    bubbles: true,
    composed: true
});
dispatchEvent(showSessionTimeoutEvent);

public extendSession() {
    // Code to extend the user session goes here...
}

public logOut() {
    // Code to log out the user goes here...

    // Navigate to the Logged Out Due to Inactivity view
    this.router.navigate(['InactivityTimeout']);
}

public getRemainingTimeText() {
    return this.sessionTimeoutRemaining + ' second' + (this.sessionTimeoutRemaining != 1 ? 's' : '');
}

Counting down the remaining time

If you know how much time is remaining in the user’s session, the approach above works fine for displaying the initial number of seconds left, but if you want to count down the remaining seconds in the user’s session, you’ll need to fire the rui-update-session-timeout custom event. The event’s detail is an object with a timeoutRemaining field that specifies the amount of time left. The jha-app component receives this event and updates the remaining time displayed.

In the example below, we count down the user’s remaining session time every second, from the current value down to 0. If there is more time left in the session, the code fires the rui-update-session-timeout custom event to update the remaining time shown. Otherwise the code fires the rui-hide-session-timeout custom event to hide the session timeout.

this.sessionTimeoutInterval = setInterval(() => {
    // Count down by 1
    this.sessionTimeoutRemaining--;

    if (this.sessionTimeoutRemaining> 0) {
        // Update the session timeout warning with the remaining countdown
        let updateSessionTimeoutEvent = new CustomEvent('rui-update-session-timeout',
            {
                detail: {
                    timeoutRemaining: this.getRemainingTimeText(),
                },
                bubbles: true,
                composed: true
            });
        dispatchEvent(updateSessionTimeoutEvent);
    } else {
        // Hide any existing session timeout warning already displayed
        this.hideSessionTimeout();

        // Log out the user
        this.logOut()
    }
}, 1000);

public hideSessionTimeout() {
    let hideSessionTimeoutEvent = new CustomEvent('rui-hide-session-timeout',
        {
            detail: {},
            bubbles: true,
            composed: true
        });
    dispatchEvent(hideSessionTimeoutEvent);
}

Hiding the session timeout warning

The session timeout warning hides itself automatically when the user presses either the “Extend my Session” or “Log Out” buttons, but your app must programmatically hide the session timeout warning:

• After the user’s session times out. The session timeout warning does not automatically hide itself when the timeout countdown reaches zero, since that is only an approximation and only displays when timeout seconds are passed.
• If the user logs out of their session independent of the session timeout warning. If the user uses your primary Log Out option instead of the Log Out button in the session timeout warning, you must manually hide the session timeout warning since it doesn’t know that a separate log out is in progress.

To programmatically hide a session timeout warning, fire the rui-hide-session-timeout custom event. The jha-app component receives this event and hides the session timeout.

let hideSessionTimeoutEvent = new CustomEvent('rui-hide-session-timeout',
{
    detail: {},
    bubbles: true,
    composed: true
});
dispatchEvent(hideSessionTimeoutEvent);

After the user’s session times out

If the user’s session ends up timing out, your app must hide the session timeout warning and take whatever other steps are needed to end the user’s session. It must also notify the user that their session has timed out and provide a way for the user to log back in, using the techniques described in the next section.

Notifying the user that their session has timed out

After the user’s session has timed out, whether your application displayed a session timeout warning beforehand or not, your app should:

• Programmatically hide the session timeout warning if your app displayed this.
• Notify the user that their session has timed out.
• Offer the user a quick link to log in again.

Notifying the user that their session has timed out can be implemented two different ways:

• Navigate to a special view that lets the user know that their session has timed out. This view should contain a link to your Log In view.
• Navigate to your Log In view and display a timed out warning in an inline notification above the login form.

Angular wrapper development

There are two parts to properly handling session timeouts for your users:

• If your application has advance notice of an upcoming session timeout, it should warn the user of this.
• After the user’s session has timed out, your application should notify the user that a session timeout occurred and offer them a quick link to log in again.

The following sections show how to implement these two activities.

Displaying a session timeout warning

Use the JhaSessionTimeoutService to warn the user about an upcoming session timeout.

Your app must use the jha-app component in app.component.html in order to display a session timeout warning. The jha-app component manages the session timeout interface internally based on custom events you fire.

Begin by including noty in your package.json, where x.y.z is the currently supported version number for this framework specified here. Use npm install to install this framework.

"dependencies": {
    ...
    "noty": "x.y.z",
    ...
},

Once the package has been installed, add it to your scripts bundle in the angular.json file.

"scripts": [
    ...
    "node_modules/noty/js/noty/packaged/jquery.noty.packaged.min.js"
]

Import the JhaNotificationsModule into your application.

// import into app.module
import { JhaNotificationsModule } from '@jkhy/responsive-ui-angular/jha-notifications';

@NgModule({
    imports: [
        ...
        JhaNotificationsModule,
        ...
    ]
})

export class AppModule(){}

Import the service into your TypeScript and inject it into the component’s constructor.

import { JhaSessionTimeoutService } from '@jkhy/responsive-ui-angular/jha-notifications';
...

constructor(
    private jhaSessionTimeoutService: JhaSessionTimeoutService
) { }

Showing the session timeout warning

To show a session timeout warning, call the ShowSessionTimeout method in JhaSessionTimeoutService.

This method has the following parameters:

• timeoutSeconds: This is a number that specifies the approximate number of seconds left before the user’s session times out.
  • The session timeout warning will visually count down the time remaining if you pass a value > 0. The countdown stops once it reaches zero.
  • Pass a value of 0 if you don’t know the remaining time and only know that a session timeout is coming sometime soon. No countdown is displayed in this case.
  • If you pass a value for the timeout seconds, your application must also keep track of the user’s remaining time. The session timeout warning is only for display purposes, it does not manage the user’s timeout for you.
• extendSessionCallback: This is a callback function that will be called when the user presses the optional “Extend my Session” button.
  • Pass a value of null if you don’t want to offer this functionality, otherwise pass a callback function. Only display this button if this warning is for an inactivity timeout that your application is able to extend.
  • If you display this button, the callback function will need to perform logic appropriate for your application in order to extend the user’s session when the user presses it.
  • The session timeout warning will automatically hide when the user presses this button.
  • If your callback functions reference “this” within your TypeScript, you must either use lambda notation or pass the value of “this” to a standard callback function. Otherwise “this” will refer to a context other than your TypeScript component, which is typically not what you want.
  • IMPORTANT: You should still display the “Extend my Session” button even if your app extends the user’s session automatically based on mouse movements or keystrokes. This button gives the user something visible to “reach for” during an impending session timeout, otherwise they may not understand that simple mouse movements will extend their session time and be frustrated about how they can continue their session.
• logOutCallback: This is a callback function that will be called when the user presses the optional “Log Out” button.
  • Pass a value of null if you don’t want to offer this functionality, otherwise pass a callback function.
  • If you display this button, you’ll need to log the user out when the user presses it.
  • The session timeout warning will automatically hide when the user presses this button.
  • If your callback functions reference “this” within your TypeScript, you must either use lambda notation or pass the value of “this” to a standard callback function. Otherwise “this” will refer to a context other than your TypeScript component, which is typically not what you want.
  • It’s a nice touch to include this button within the session timeout warning, even though your app provides a Log Out option in the header or nav. This local Log Out option makes it quick and easy for the user to respond to the session timeout warning without having to look for the primary Log Out option.

Hiding the session timeout warning

To programmatically hide a session timeout warning, call the HideSessionTimeout method in JhaSessionTimeoutService.

The session timeout warning hides itself automatically when the user presses either the “Extend my Session” or “Log Out” buttons, but your app must programmatically hide the session timeout warning:

• After the user’s session times out. The session timeout warning does not automatically hide itself when the timeout countdown reaches zero, since that is only an approximation and only displays when timeout seconds are passed.
• If the user logs out of their session independent of the session timeout warning. If the user uses your primary Log Out option instead of the Log Out button in the session timeout warning, you must manually hide the session timeout warning since it doesn’t know that a separate log out is in progress.

After the user’s session times out

If the user’s session ends up timing out, your app must hide the session timeout warning and take whatever other steps are needed to end the user’s session. It must also notify the user that their session has timed out and provide a way for the user to log back in, using the techniques described in the next section.

Examples

In the example below, we’re showing a session timeout warning 5 minutes (300 seconds) before the user’s session times out. We’re passing a lambda function for both the “Extend my Session” and “Log Out” callbacks, so both of those buttons display in the warning. We’re using lambda notation for the callbacks since they reference “this”.

this.jhaSessionTimeoutService.ShowSessionTimeout(300, () => { this.extendSession(); }, () => { this.logOut(); });

In the next example, we’re showing a session timeout warning sometime before the user’s session times out, but we’re not exactly sure when this will happen, so we pass a value of 0 for the timeout seconds parameter. We’re passing a value of null for the “Extend my Session” callback, so that button does not display. We’re passing a lambda function for the “Log Out” callback, so that buttons displays in the warning. We’re using lambda notation for the callback since it references “this”.

this.jhaSessionTimeoutService.ShowSessionTimeout(0, null, () => { this.logOut(); });

Notifying the user that their session has timed out

After the user’s session has timed out, whether your application displayed a session timeout warning beforehand or not, your app should:

• Programmatically hide the session timeout warning if your app displayed this.
• Notify the user that their session has timed out.
• Offer the user a quick link to log in again.

Notifying the user that their session has timed out can be implemented two different ways:

• Navigate to a special view that lets the user know that their session has timed out. This view should contain a link to your Log In view.
• Navigate to your Log In view and display a timed out warning in an inline notification above the login form.

Design

There are no specific design elements for session timeout.