How do I configure login page session timeouts in AM (All versions) when using authentication modules?
The purpose of this article is to provide information on setting login page session timeouts in AM when you are using authentication modules and chains. You can set these at a global level or have realm specific timeouts. The XUI times out the login page session in the background and then automatically creates a new login page session to provide a seamless user experience.
6 readers recommend this article
Overview
The login page session timeout specifies the number of minutes before the AM login page timeouts if the user has not logged in. There are two components to this session timeout:
- The individual authentication module timeout - this can also be set in a localized version and/or in realm specific versions. The default session timeout for an authentication module is two minutes.
- The overall login page session timeout - this must be set to a value greater than the overall authentication process (including any multi-page authentication processes). The default for the overall login page session timeout is three minutes.
You can check the current timeout settings for a module by checking the Authentication debug log. For example, the following log snippet shows the default timeout for the DataStore module:
amAuth:04/07/2020 11:07:52:300 AM BST: Thread[http-bio-8080-exec-25,5,main]: TransactionId[83a32d22-f37e-4367-b9d5-7ebcd7f0bb31-30872] Returning page timeout :120 amCallback:04/07/2020 11:07:52:300 AM BST: Thread[http-bio-8080-exec-25,5,main]: TransactionId[83a32d22-f37e-4367-b9d5-7ebcd7f0bb31-30872] Page Timeout amLoginModule:04/07/2020 11:07:52:300 AM BST: Thread[http-bio-8080-exec-25,5,main]: TransactionId[83a32d22-f37e-4367-b9d5-7ebcd7f0bb31-30872] SETTING Failure Module name.... :DataStore amAuth:04/07/2020 11:07:52:300 AM BST: Thread[http-bio-8080-exec-25,5,main]: TransactionId[83a32d22-f37e-4367-b9d5-7ebcd7f0bb31-30872] Module name is .. DataStore amAuth:04/07/2020 11:07:52:10:300 AM BST: Thread[http-bio-8080-exec-25,5,main]: TransactionId[83a32d22-f37e-4367-b9d5-7ebcd7f0bb31-30872] failureModuleSet is : [DataStore] amLoginModule:04/07/2020 11:07:52:301 AM BST: Thread[http-bio-8080-exec-25,5,main]: TransactionId[83a32d22-f37e-4367-b9d5-7ebcd7f0bb31-30872] login timed out java.io.IOException: 110This log can also be useful to check that the new settings have been applied correctly.
Simple example
If you have two chained authentication modules, where one has a timeout of three minutes and one has a timeout of five minutes, you must set the overall login page session timeout to at least eight minutes to accommodate the overall authentication process.
Realm example
If you have two realms:
- employees, which has one authentication module with a timeout of three minutes.
- customers, which has two chained authentication modules that both have a timeout of two minutes.
You would need an overall login page session timeout of at least four minutes to accommodate the longest possible overall authentication process (in the customers realm).
Note
Updating timeouts for an authentication module uses the same process as updating the text shown on the login page; customizing the login text during testing can be a good way to check that you are seeing the updated module page. See How do I modify the text on the Login page for one or more realms in AM (All versions)? for further information.
Configuring login page session timeouts (global)
To set a global login page session timeout, that is, one that applies to all realms, you must set the timeout in each authentication module you use as well as the overall login page session timeout:
- Update the timeout value in the .xml files that correspond to the authentication modules you use. These files are are located in the /path/to/tomcat/webapps/am/config/auth/default_xx directory where AM is deployed (where _xx is the localized equivalent of the default directory). If you haven't localized any files, you should change the files located in the /path/to/tomcat/webapps/am/config/auth/default_en directory. For example, if you use the LDAP and Data Store modules, you would update these files as follows:
- LDAP.xml - in this file, you should look for the following timeout value and change it to the required number of seconds: <Callbacks length="0" order="4" timeout="120" template="user_inactive.jsp" error="true"/>
- Datastore.xml - in this file, you should look for the following timeout value and change it to the required number of seconds: <Callbacks length="2" order="1" timeout="120" header="Sign in" >
- Update the overall login page session timeout using either the AM admin UI or ssoadm, ensuring it is set to a value greater than the overall authentication process (including any multi-page authentication processes):
- AM admin UI: navigate to: Configure > Server Defaults > Session > Session Limits > Invalidate Session Max Time and enter the required number of minutes.
- ssoadm: enter the following command: $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.session.invalidsessionmaxtime=[minutes]replacing [adminID], [passwordfile] and [minutes] with appropriate values.
- Restart the web application container in which AM runs to apply these configuration changes.
Note
You should set the overall login page session timeout as a server default rather than for an individual server since the overall authentication process will be the same on all servers (as it is determined by authentication modules). If your timeout is not behaving as expected, you should check the Invalidate Session Max Time setting on individual servers to ensure the default value has not been overridden.
Configuring login page session timeouts (realm specific)
Assumptions
The following instructions assume you are using the configuration suffix dc=am,dc=forgerock,dc=org
and are changing timeouts for the English locale. You should be aware of the following if either or both of these assumptions are not true of your deployment:
-
Configuration Suffix: where the instructions refer to creating an am or am_en directory, the
am
prefix refers to the RDN of the configuration suffixdc=am,dc=forgerock,dc=org
. -
Localization: where the instructions refer to creating an am_en directory, the
_en
refers to the English locale. If you want to change timeouts for a different locale, you should create an am_xx directory that corresponds to your locale of choice. The default directories for supported locales can be found by navigating to the /path/to/tomcat/webapps/am/config/auth directory.
Depending on your deployment, you may need to make both of these changes by substituting the example directory names am and am_en in the instructions to match your RDN and Locale. For example, if you have changed the default configuration suffix to dc=login,dc=com
and you want to change timeouts for the French locale in the employees realm, you would create a directory named login_fr/services/employees/html directory:
Note
It is best practice to make your changes in both the am directory and the am_en directory as this ensures all users will see your changes regardless of their locale. Customizations in the am directory are seen by users whose locale does not match one of the available locales. However, depending on your requirements, it may be sufficient to just make changes in the am directory.
Instructions
You can set the timeout for authentication modules in the top level realm, an individual realm or all / the majority of realms depending on where you make your changes:
- Create a directory in the path that AM will use to look up your customized files. Navigate to the /path/to/tomcat/webapps/am/config/auth directory and create one or more directories as follows depending on where you want your customizations to apply:
Directory | Location | Directory to create | Resulting path |
---|---|---|---|
am | Top level realm | am/html | /path/to/tomcat/webapps/am/config/auth/am/html |
am | Individual realm | am/services/realmname/html | /path/to/tomcat/webapps/am/config/auth/am/services/realmname/html |
am | All or the majority of realms | am/services/html | /path/to/tomcat/webapps/am/config/auth/am/services/html |
am_en | Top level realm | am_en/html | /path/to/tomcat/webapps/am/config/auth/am_en/html |
am_en | Individual realm | am_en/services/realmname/html | /path/to/tomcat/webapps/am/config/auth/am_en/services/realmname/html |
am_en | All or the majority of realms | am_en/services/html | /path/to/tomcat/webapps/am/config/auth/am_en/services/html |
If you choose to make changes that affect all or the majority of realms, these customizations will affect all realms that do not have a corresponding realmname/html directory.
Note
The realmname directory must all be in lower case for the realm customizations to be located.
- Copy the contents of the /path/to/tomcat/webapps/am/config/auth/default and/or /path/to/tomcat/webapps/am/config/auth/default_en directory to your new /html directories.
- Update the timeout value in the .xml files that correspond to the authentication modules you use, ensuring you update the files in the correct location according to what you set up in step 1. For example, if you use the Data Store and HOTP modules in the employees realm, you would update these files as follows:
- Datastore.xml (located in /path/to/tomcat/webapps/am_en/config/auth/am/services/employees/html) - in this file, you should look for the following timeout value and change it to the required number of seconds: <Callbacks length="2" order="1" timeout="120" header="Sign in" >
- HOTP.xml (located in /path/to/tomcat/webapps/am_en/config/auth/am/services/employees/html)- in this file, you should look for the following timeout value and change it to the required number of seconds: <Callbacks length="2" order="2" timeout="120" header="Please enter your One Time Password, or request a new one">
- Update the overall login page session timeout using either the AM admin UI or ssoadm, ensuring it is set to a value greater than the overall authentication process in any realms (including any multi-page authentication processes):
- AM admin UI: navigate to: Configure > Server Defaults > Session > Session Limits > Invalidate Session Max Time and enter the required number of minutes.
- ssoadm: enter the following command: $ ./ssoadm update-server-cfg -s default -u [adminID] -f [passwordfile] -a com.iplanet.am.session.invalidsessionmaxtime=[minutes]replacing [adminID], [passwordfile] and [minutes] with appropriate values.
- Restart the web application container in which AM runs to apply these configuration changes.
You can have a combination of customizations, for example, you can have specific timeouts for the top level realm, different ones for the customers realm and separate ones for all other realms by changing the relevant .xml files in all three places.
Note
You should set the overall login page session timeout as a server default rather than for an individual server since the overall authentication process will be the same on all servers (as it is determined by authentication modules). If your timeout is not behaving as expected, you should check the Invalidate Session Max Time setting on individual servers to ensure the default value has not been overridden.
See Also
How do I modify the text on the Login page for one or more realms in AM (All versions)?
FAQ: Customizing, branding and localizing end user pages in AM
How do I configure session timeouts in AM (All versions)?
How do I configure realm level session timeouts in AM (All versions)?
How do I configure user-level session timeouts in AM (All versions)?
Related Training
ForgeRock Access Management Deep Dive (AM-410)
Related Issue Tracker IDs
N/A