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

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:

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).

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/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" >
2. 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.
3. Restart the web application container in which AM runs to apply these configuration changes.

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 suffix dc=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:

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/am/config/auth directory and create one or more directories as follows depending on where you want your customizations to apply:

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.

2. 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.
3. 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">
4. 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.
5. 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.

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)?

Deployment configuration

Related Training

ForgeRock Access Management Deep Dive (AM-410)

Related Issue Tracker IDs

N/A