Customize session quota exhaustion actions

AM provides built-in session quota exhaustion actions that you can configure for your deployment. If none of the built-in actions address your use case, you can build a custom session quota exhaustion action plugin. The plugin is a Java class that implements the QuotaExhaustionAction interface and is dynamically loaded by AM using the ServiceLoader mechanism.

Only build a custom session quota exhaustion action plugin if the built-in actions aren’t flexible enough for your deployment.

Session quotas aren’t available for client-side sessions.

This page demonstrates a custom session quota exhaustion action plugin.

Sample plugin

The sample plugin demonstrates a simple session quota exhaustion action that removes the first session it finds when the session quota is met.

Learn about downloading and building PingAM sample source code in the following Knowledge Base article: How do I access and build the sample code provided for PingAM?.

Get a local clone so that you can try the sample on your system. You’ll find the relevant files in the /path/to/openam-samples/openam-examples-quotaexhaustionaction directory.

Files in the sample

pom.xml

Apache Maven project file for the module.

This file specifies how to build the sample plugin, and also specifies its dependencies on AM components and on the Servlet API.

src/main/java/org/forgerock/openam/examples/quotaexhaustionaction/SampleQuotaExhaustionAction.java

Core class for the sample quota exhaustion action plugin.

This file:

Implements the QuotaExhaustionAction interface.
Annotates the implementation class with @I18nKey("customActionI18nKey").
Overrides the action method to perform the action when the session quota is met.

src/main/resources/META-INF/services/com.iplanet.dpro.session.service.QuotaExhaustionAction

Service provider configuration file.

This file is used by the ServiceLoader mechanism to load the plugin class. It contains the fully qualified name of the plugin class, which is org.forgerock.openam.examples.quotaexhaustionaction.SampleQuotaExhaustionAction in the sample.

Build the sample plugin

If you haven’t already done so, download and build the sample code.

Learn about downloading and building PingAM sample source code in the following Knowledge Base article: How do I access and build the sample code provided for PingAM?.
When the build completes, copy the quotaexhaustionaction-8.1.1.jar file to the WEB-INF/lib directory where you deployed AM:
```
$ cp target/quotaexhaustionaction-8.1.1.jar /path/to/tomcat/webapps/am/WEB-INF/lib/
```
Extract amSession.properties (and, if necessary, the localized versions of this file) from openam-core-8.1.1.jar to WEB-INF/classes/ where AM is deployed. For example, if AM is deployed under /path/to/tomcat/webapps/am:
```
$ cd /path/to/tomcat/webapps/am/WEB-INF/classes/
$ jar -xvf ../lib/openam-core-8.1.1.jar amSession.properties
inflated: amSession.properties
```
Add the following line to amSession.properties:
```
customActionI18nKey=Randomly Destroy Session
```
Restart AM or the container in which it runs to load the plugin.

Try the sample session quota exhaustion action

In the AM admin UI, go to Configure > Global Services, click Session, and select the Session Quotas tab.
Select the custom session quota exhaustion action (Randomly Destroy Session) from the Resulting behavior if session quota exhausted list, and click Save Changes.

If you don’t provide a value for the customActionI18nKey in amSession.properties, the plugin class name is used instead.
Open multiple browser windows and log in with the same user until you exceed the session quota.
Observe that one of the sessions is removed when the session quota is met.