Introduction
"I was away from my desk for five minutes and my session timed out ๐ "
It does seem that users perceive time โ๏ธ differently when it comes to application timeouts. A timeout of an hour can seem like five minutes, and it can be a frustrating experience for users. Unfortunately, we cannot do away with timeouts as they are critical to securing business applications. However, we can explain timeouts to our users more clearly and make minor changes to the UI to improve the user experience when a timeout occurs.
This post will tell you everything you need to know about timeouts in APEX. It will also show you where timeout values are configured and provide tips for improving the user experience when timeouts occur.
Available Timeout Settings in APEX
APEX allows you to configure five timeout-related settings.
Maximum Session Length in Seconds
This value determines how long a session can last (in seconds). No matter how active you are in a session, you will be logged out when this value is reached.
- If you leave the field blank, a value of 28800 (8 hours) is used.
Maximum Session Idle Time in Seconds
This value determines how long your session can remain idle before it is timed out. The idle timer is restarted after each page request. This setting guards against a user leaving their desk and someone else using the application.
- If you leave the field blank, a value of 3600 (1 hour) is used.
Session Timeout Warning in Seconds
This value determines how long before a Session or Idle timeout occurs that a warning should be displayed to the user. For example, if you set this value to 120 (2 minutes), the user will see a popup warning message 2 minutes before their session expires.
- If you leave the field blank, a value of 300 (5 minutes) is used
- Set to 0 to disable timeout warnings
Session Timeout URL
This setting determines where the user is directed when the Maximum Session Length is exceeded. If left empty, the user is directed to the login page; otherwise, they are directed to the URL defined by this setting.
- This setting can only be set at the Application Level.
Session Idle Timeout URL
This setting determines where the user is directed when the Maximum Session Idle Time is exceeded. If left empty, the user is directed to the login page; otherwise, they are directed to the URL defined by this setting.
- This setting can only be set at the Application Level.
Configuring Timeout Settings in APEX
Timeout settings can be made at three levels:
- Instance Level (INTERNAL Workspace)
- Workspace Level
- Application Level
The above 'levels' work like cascading defaults. Instance settings act as an Instance wide default, Workspace settings override Instance settings, and Application settings override Workspace settings.
The table below illustrates how the cascading effect of the timeouts work for three example scenarios. In these examples, I am using the Maximum Session Length in Seconds
setting, but it works the same for Maximum Session Idle Time in Seconds
and Session Timeout Warning in Seconds
.
Level | Example 1 | Example 2 | Example 3 |
---|---|---|---|
Instance | 36000 (10 Hrs) | 36000 (10 Hrs) | Not Set |
Workspace | Not Set | 18000 (5 Hrs) | 36000 (10 Hrs) |
Application | Not Set | Not Set | 18000 (5 Hrs) |
Value Used | 36000 (10 Hrs) | 18000 (5 Hrs) | 18000 (5 Hrs) |
Instance Timeout Settings
Workspace Timeout Settings
Application Timeout Settings
Session Idle Timeout Warning
This section describes how session idle timeout warnings work. These are enabled if you set Session Timeout Warning in Seconds
to any value except 0.
Idle Timeout Behavior
If an idle timeout triggers the session timeout warning, then the user will be given a chance to extend the session:
If the user fails to extend before time runs out, then they will lose any unsaved changes and see the following message:
- Clicking 'Sign In Again' will take the user to the login page, or the page identified in the Application Level Setting
Session Idle Timeout URL
- Clicking
Cancel
will take the user back to the page they were on, but as soon as they attempt to submit a page, they will be redirected to the login page or the page identified in the Application Level SettingSession Idle Timeout URL
Maximum Session Timeout Behavior
If the session is approaching the Maximum Session Length, then the user will see the following: They can click OK and continue to work until the Maximum Session Length is reached, at which point they will lose any unsaved changes and see the following:
- Clicking
Sign In Again
will take the user to the login page or the page identified in the Application Level SettingSession Timeout URL
- Clicking
Cancel
will take the user back to the page they were on, but as soon as they attempt to submit a page, they will be redirected to the login page or the page identified in the Application Level SettingSession Timeout URL
Disabling Session Timeout Warning
If you set Session Timeout Warning in Seconds
to 0, session timeout warnings are disabled. The Idle or Maximum Timeout will occur silently. When a timeout occurs, the next time the user attempts to submit a page, they will be automatically redirected to either the Session Timeout URL
, the Session Idle Timeout URL
, or the Login Page, depending on the setups.
Improving User Experience
Session Timeout Warnings help inform users of pending and expired timeouts, but we can do better. There are two things that I like to do to improve the timeout user experience.
Clarify Timeout Warning Messages
The warning and timeout popup messages can be confusing for users. Luckily, we can easily customize these messages by overriding their Message Text
.
We can query the apex_application_translations
table to search for APEX system translatable text. If we query using the text we see in the standard popup messages, we can get the appropriate translatable_message
values. Note: You must have the APEX_ADMINISTRATOR_ROLE
database role to run this SQL.
SELECT translatable_message
, message_text
FROM apex_application_translations
WHERE workspace = 'INTERNAL'
AND message_text LIKE '%Your session%';
From the result, it looks like we need to override APEX.SESSION.ALERT.EXPIRED
,
APEX.SESSION.ALERT.IDLE_WARN
, and APEX.SESSION.ALERT.MAX_WARN
.
We can enter our own text for these messages by creating Text Messages in our application. Shared Components > Text Messages. Here is a screenshot of three text messages I created to override the standard values:
With these in place, our idle timeout warning now looks like this:
The session timed-out message now looks like this:
Custom Timeout Page
As we know, if the user Cancels the timeout dialogues or if Timeout Warnings are disabled, the next time they attempt an action, these will be sent to the login page or one of the designated timeout URLs. Given this, we still want to let the user know that a timeout occurred and give them an easy way to log in again.
I typically create a public timeout page that displays an appropriate Session or Idle Timeout message and a button to take the user directly to the login page.
In the application security settings:
- Set
Session Timeout URL
tof?p=&APP_ID.:timeout:0:SESSION
- Set
Session Idle Timeout URL
tof?p=&APP_ID.:timeout:0:IDLE
These URLs set the REQUEST to SESSION
or IDLE
. I use the request value in the timeout page to show the appropriate message. e.g.
Monitoring Session Timeouts
As an administrator, it may be helpful to know when session and idle timeouts will occur for your users. You can monitor session timeouts using two methods:
APEX Builder Active Sessions
Navigation: Monitor Activity > Active Sessions
SQL Query
You can see all of the timeout-related values for a session using the SQL below:
SELECT user_name
, apex_session_id
, session_created
, sysdate
, session_idle_timeout_on
, session_life_timeout_on
, session_max_idle_sec
FROM apex_workspace_sessions
WHERE apex_session_id = 101665457767051;
Timeouts and Session Sharing
Session Sharing (configured for an Authentication Scheme) in APEX allows users to log in to Application A and then navigate to Application B without having to log in again. Session sharing uses a Workspace cookie to 'share' the session. The session ID does not change as the user moves between applications.
In this scenario, the session timeout is driven by the initial session, established when the user logs in to Application A. So, even if the user is in Application B, the timeout values in apex_workspace_sessions
are the same ones established when they logged into Application A.
What is interesting, however, is that the Session Timeout URL
and Session Idle Timeout URL
values used are based on the application the user is in when the timeout occurs. This behavior means it is important to set Session Timeout URL
and Session Idle Timeout URL
for all applications.
Furthermore, in most session-sharing scenarios, you have a primary 'Log In' App that you want to direct users back to if they need to log in again. In this case, you would want to point the Session Timeout URL
and Session Idle Timeout URL
to a page in the 'Log In' App, not the current App.
What Should the Timeout Values be?
Unfortunately, I have to answer this with 'It Depends'. For guidance on security-related matters, I typically refer to the Open Web Application Security Project (OWASP).
The OWASP Session Management Cheat Sheet says the following:
Both the idle and absolute timeout values are highly dependent on how critical the web application and its data are. Common idle timeouts ranges are 2-5 minutes for high-value applications and 15-30 minutes for low-risk applications. Absolute timeouts depend on how long a user usually uses the application. If the application is intended to be used by an office worker for a full day, an appropriate absolute timeout range could be between 4 and 8 hours.
Many of us use Social Media Apps, which seemingly never timeout, but many business or financial applications have very restrictive timeouts. This is part of the reason users find it frustrating when their APEX application times out. They are just not used to applications timing out.
Given this, you must evaluate each application based on the data it contains and the risk to your business if someone were able to take over an existing session because a timeout was set incorrectly. Once appropriate timeout values are decided, you should educate users on why it is essential for a particular application to have a timeout and why the timeout is set to a specific value.
Conclusion
Anything that interrupts productivity can be frustrating, and timeouts are no exception. As APEX developers, however, we have a responsibility to ensure our applications are as secure as possible. In these seemingly conflicting situations, we must make sure the application is secure first and then do what we can to make the user experience as seamless as possible.
I encourage you to log into your APEX environments and document the Timeouts you have set for all your Applications. Review them and verify that they are all set appropriately. You don't have an excuse not to do this, as the SQL statement below will document your existing setups for you!
Sample Output:
#JoelKallmanDay
This post is dedicated to Joel Kallman who made Oracle APEX the product it is today. More than that he was a great human being.
๐ Read More
- ๐ฉณ APEX Shorts
- #๏ธโฃ APEX Posts