How To
ForgeRock Identity Platform
Does not apply to Identity Cloud

How do I configure login page session timeouts in AM (All versions) when using authentication modules?

Last updated Apr 13, 2021

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:

  1. 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.
  2. 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: 110

This 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 XUI 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:

  1. 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/openam/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/openam/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" >
  2. Update the overall login page session timeout using either the console or ssoadm, ensuring it is set to a value greater than the overall authentication process (including any multi-page authentication processes):
    • Console: 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.
  3. 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 default configuration suffix (dc=openam,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 openam or openam_en directory, the openam prefix refers to the RDN of the configuration suffix dc=openam,dc=forgerock,dc=org.
  • Localization: where the instructions refer to creating an openam_en directory, the _en refers to the English locale. If you want to change timeouts for a different locale, you should create an openam_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/openam/config/auth directory.

Depending on your deployment, you may need to make both of these changes by substituting the example directory names openam and openam_en in the instructions to match your RDN and Locale. For example, if you have changed the default configuration suffix to dc=acme,dc=com and you want to change timeouts for the French locale in the employees realm, you would create a directory named acme_fr/services/employees/html directory:

/path/to/tomcat/webapps/openam/config/auth/acme_fr/services/employees/html
Note

It is best practice to make your changes in both the openam directory and the openam_en directory as this ensures all users will see your changes regardless of their locale. Customizations in the openam 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 openam 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:

  1. Create a directory in the path that AM will use to look up your customized files. Navigate to the /path/to/tomcat/webapps/openam/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
openam Top level realm openam/html  /path/to/tomcat/webapps/openam/config/auth/openam/html 
openam Individual realm openam/services/realmname/html  /path/to/tomcat/webapps/openam/config/auth/openam/services/realmname/html 
openam All or the majority of realms openam/services/html  /path/to/tomcat/webapps/openam/config/auth/openam/services/html 
openam_en  Top level realm openam_en/html  /path/to/tomcat/webapps/openam/config/auth/openam_en/html 
openam_en  Individual realm openam_en/services/realmname/html  /path/to/tomcat/webapps/openam/config/auth/openam_en/services/realmname/html  
openam_en  All or the majority of realms openam_en/services/html  /path/to/tomcat/webapps/openam/config/auth/openam_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.

  1. Copy the contents of the /path/to/tomcat/webapps/openam/config/auth/default and/or /path/to/tomcat/webapps/openam/config/auth/default_en directory to your new /html directories.
  2. 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/openam_en/config/auth/openam/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/openam_en/config/auth/openam/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">
  3. Update the overall login page session timeout using either the console or ssoadm, ensuring it is set to a value greater than the overall authentication process in any realms (including any multi-page authentication processes):
    • Console: 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.
  4. 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 XUI Login page for one or more realms in AM (All versions)?

FAQ: Customizing, branding and localizing XUI 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)?

Reference › Deployment Configuration

Related Training

ForgeRock Access Management Core Concepts (AM-400)

Related Issue Tracker IDs

N/A


Copyright and Trademarks Copyright © 2021 ForgeRock, all rights reserved.