Session Quota basics

What is Session Quota?

Session Quota provides a way to limit the number of active sessions for a given user. Basically in the session service you can configure how many active sessions could a user have. For simplicity let’s say that the active session limit is set to 5. If a user would log in for the 6th time, then based on the session quota settings a QuotaExhaustionAction gets executed, which will decide what happens with the new and the existing sessions.

How session quota is evaluated?

When session quota is enabled, OpenAM tracks the user sessions mapped by universal IDs, hence it can easily detect the number of active sessions for a given user (this mapping is only available when session quota is enabled or SFO is being used). There is 3 way how the session quota can be evaluated:

  • Single Server Mode: if there is only one OpenAM node (with or without a site), then the quota will be evaluated per that one server.
  • Local Server Only Mode: When the advanced property “openam.session.useLocalSessionsInMultiServerMode” is set to true, OpenAM will only evaluate session quota per local server (so a user can end up having number of servers * number of allowed concurrent sessions). This option has been introduced to provide a certain level of support for multiserver environments without SFO (see OPENAM-875)
  • Session Failover Mode: In multiserver setup when using SFO it is possible to enforce deployment-wide session quota

So we now know how OpenAM detects if the session quota is being exceeded by a given user, but we don’t know yet what to do when that happens. Here comes QuotaExhaustionAction into the picture. This interface allows deployers to customize the behavior of OpenAM for these cases. To understand this a bit more let’s look at the built-in session quota exhaustion actions:

  • DENY_ACCESS: basically it will deny the access for the new session, but will keep the old session alive.
  • DESTROY_NEXT_EXPIRING: destroys the next expiring session (based on min(full, idle) for all the sessions), and lets the new session live.
  • DESTROY_OLDEST_SESSION: destroys the session with the lowest expiration time, and lets the new session live.
  • DESTROY_OLD_SESSIONS: destroys all the existing sessions, and lets the new session live.

As you can see there are many different ways to handle session quota exhaustion, and it really depends on the requirements, which method really fits. In case none of these are good for you, you can simply implement a custom QuotaExhaustionAction, for that you can find the built-in implementations here, but there is also a sample GitHub project.
Once you are ready with your custom implementation follow the installation steps on the GitHub project README.

How to enable session quota?

On the admin console go to Configuration -> Global -> Session page and:

  • Set the number of “Active User Sessions” to your choosen value.
  • Turn ON “Enable Quota Constraints”.
  • Select the preferred exhaustion action under the “Resulting behavior if session quota exhausted” option.

Quite possibly you need to restart OpenAM for the changes to take effect, but after then it should work just as you would want it to. ;)

Rotating debug logs

Since OpenAM 10.0.0 it is possible to enable time based debug log rotation in order to make your log files a bit more managable. Time based as in the logs will be rotated periodically after a configurable amount of time has passed.
Now the problem with debug logs is that they get written to in the very early phase of the startup process: just think about the fact that an error can occur already while trying to connect to the configuration store. This means that to store the rotation config, we can’t actually use the service config system, as by the time those settings get loaded, files are already written. To overcome this problem, instead, you need to modify/create files in the WAR file to make these configurations accessible for startup as well.
To enable debug log rotation, you need to create/modify the WEB-INF/classes/debugconfig.properties file:

org.forgerock.openam.debug.prefix=mylogs-
org.forgerock.openam.debug.suffix=-MM.dd.yyyy-kk.mm
org.forgerock.openam.debug.rotation=

The properties in detail:

  • org.forgerock.openam.debug.prefix (optional): an arbitrary string that will be used as a filename prefix for every debug log
  • org.forgerock.openam.debug.suffix (optional): a valid Java dateformat string. Please note that if you set up rotation for every 5 minutes and you don’t include minutes in the format string, then you won’t really rotate the debug log every 5 minutes (the logs won’t get overwritten, you’ll just have one log file with all the content).
  • org.forgerock.openam.debug.rotation: rotation interval for the debug logs in minutes. If rotation interval is higher than 0, then rotation is enabled

Since this has been implemented in the shared Debug class, this also means, that you can put this properties file on ClassPath for any OpenAM component that is using the ClientSDK, so things like DAS and Java EE agents too.
Obviously after creating/modifying the properties file, you have to restart the container for the changes to take effect.