Customizing CTS-Based Session Quota Exhaustion Actions
This section demonstrates a custom session quota exhaustion action plugin. AM calls a session quota exhaustion action plugin when a user tries to open more CTS-based sessions than their quota allows. Note that session quotas are not available for client-based sessions.
You only need a custom session quota exhaustion action plugin if the built-in actions are not flexible enough for your deployment. See "Configuring Session Quotas".
Creating & Installing a Custom Session Quota Exhaustion Action
You build custom session quota exhaustion actions into a .jar that you then plug in to AM. You must also add your new action to the Session service configuration, and restart AM in order to be able to configure it for your use.
Your custom session quota exhaustion action implements the com.iplanet.dpro.session.service.QuotaExhaustionAction interface, overriding the action method. The action method performs the action when the session quota is met, and returns true only if the request for a new session should not be granted.
The example in this section simply removes the first session it finds as the session quota exhaustion action.
[/home/jenkins/workspace/ipelines_product-docs-qa-release/src/main/docbkx/resources/SampleQuotaExhaustionAction.java]
If you have not already done so, download and build the sample code.
For information on downloading and building AM sample source code, see How do I access and build the sample code provided for AM (All versions)? in the Knowledge Base.
In the sources, you find the following files:
pom.xmlApache 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.javaCore class for the sample quota exhaustion action plugin
Once built, copy the .jar to WEB-INF/lib/ where AM is deployed.
$ cp target/*.jar /path/to/tomcat/webapps/openam/WEB-INF/lib/Using the ssoadm command, update the Session Service configuration:
$ssoadm \ set-attr-choicevals \ --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org \ --password-file /tmp/pwd.txt \ --servicename iPlanetAMSessionService \ --schematype Global \ --attributename iplanet-am-session-constraint-handler \ --add \ --choicevalues myKey=\ org.forgerock.openam.examples.quotaexhaustionaction.SampleQuotaExhaustionActionChoice Values were set.
Extract amSession.properties and if necessary the localized versions of this file from openam-core-7.1.4.jar to WEB-INF/classes/ where AM is deployed. For example, if AM is deployed under /path/to/tomcat/webapps/openam, then you could run the following commands.
$cd /path/to/tomcat/webapps/openam/WEB-INF/classes/$jar -xvf ../lib/openam-core-7.1.4.jar amSession.propertiesinflated: amSession.properties
Add the following line to amSession.properties.
myKey=Randomly Destroy Session
Restart AM or the container in which it runs.
You can now use the new session quota exhaustion action. In the AM console, go to Configure > Global Services, click Session, scroll to Resulting behavior if session quota exhausted, and then choose an option.
Before moving to your test and production environments, be sure to add your .jar file and updates to amSession.properties into a custom .war file that you can then deploy. You must still update the Session service configuration in order to use your custom session quota exhaustion action.
Listing Session Quota Exhaustion Actions
List session quota exhaustion actions by using the ssoadm command:
$ssoadm \ get-attr-choicevals \ --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org \ --password-file /tmp/pwd.txt \ --servicename iPlanetAMSessionService \ --schematype Global \ --attributename iplanet-am-session-constraint-handlerI18n Key Choice Value ------------------------- ---...----------------------------------------- choiceDestroyOldSession org...session.service.DestroyOldestAction choiceDenyAccess org...session.service.DenyAccessAction choiceDestroyNextExpiring org...session.service.DestroyNextExpiringAction choiceDestroyAll org...session.service.DestroyAllAction myKey org...examples...SampleQuotaExhaustionAction
Removing a Session Quota Exhaustion Action
Remove a session quota exhaustion action by using the ssoadm command:
$ssoadm \ remove-attr-choicevals \ --adminid uid=amAdmin,ou=People,dc=openam,dc=forgerock,dc=org \ --password-file /tmp/pwd.txt \ --servicename iPlanetAMSessionService \ --schematype Global \ --attributename iplanet-am-session-constraint-handler \ --choicevalues \ org.forgerock.openam.examples.quotaexhaustionaction.SampleQuotaExhaustionActionChoice Values were removed.