What is middleware?¶
HQ uses a number of types of middleware, defined in
For background on middleware, see the Django docs
TimeoutMiddleware controls a session-based inactivity timeout, where the user is logged out after a period of inactivity.
The default timeout, defined in
INACTIVITY_TIMEOUT, is two weeks, long enough that regular
users will not encounter it.
TimeoutMiddleware deals with domains that enforce a shorter timeout for security purposes.
The shorter timeout is enabled using the “Shorten Inactivity Timeout” checkbox in Project Settings > Privacy, and
stored as the
secure_sessions. This document wil refer to domains using this feature as “secure” domains.
By default, secure domains time their users out after 30 minutes of inactivity. This duration is controlled by
“Activity” refers to web requests to HQ. This includes formplayer requests, as formplayer issues a request to HQ
for session details that extends the user’s session; see
SessionDetailsView. In secure domains,
hqwebapp/js/inactivity that periodically pings HQ for the purpose of
extending the session, provided that the user has recently pressed a key or clicked their mouse.
When a user’s session times out, they are logged out, so their next request will redirect them to the login page.
This works acceptably for most of HQ but is a bad experience when in an area that relies heavily on ajax requests, which
will all start to fail without indicating to the user why. To avoid this there is a logout UI, also
hqwebapp/js/inactivity, which tracks when the user’s session is scheduled to expire. This UI pops
up a warning dialog when the session is close to expiring. When the session does expire, the UI pops up a dialog
that allows the user to re-login without leaving the page. This UI is enabled whenever the user is on a
domain-specific page and has a secure session. Note that the user’s session may be secure even if the domain they
are viewing is not secure; more on this below.
A user’s session is marked secure is any of the following are true:
The user is viewing a secure domain.
The user is a member of any domain that uses secure sessions.
The session has already been marked secure by a previous request.
This behavior makes secure sessions “sticky”, following the user around after they visit a secure domain. Note that the session is cleared when the user logs out or is forced out due to inactivity.
The feature flag
SECURE_SESSION_TIMEOUT allows domains to customize the length of their timeout. When this is
on, the domain can specify a number of minutes, which will be used in place of the default 30-minute
SECURE_TIMEOUT. When a user is affected by multiple domains, with different timeout durations, the minimum
duration is used. As with the secure session flag itself, the relevant durations are the current domain, and other
domains where the user is a member, and the duration value currently stored in the session. So a user who belongs
to two secure domains, one with the standard 30-minute timeout and one with a 15-minute timeout, will always
experience a 15-minute timeout. A user who belongs to no secure domains but who visits a domain with a 45-minute
timeout will then experience a 45-minute timeout until the next time they log out and back in.