---
title: Customize session quota exhaustion actions
description: 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.
component: pingam
version: 8.1
page_id: pingam:security:custom-quota-exhaustion-action
canonical_url: https://docs.pingidentity.com/pingam/8.1/security/custom-quota-exhaustion-action.html
llms_txt: https://docs.pingidentity.com/pingam/llms.txt
docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md
keywords: ["Security", "Sessions", "Setup & Configuration"]
page_aliases: ["security-guide:custom-quota-exhaustion-action.adoc"]
section_ids:
  sample-plugin: Sample plugin
  build_the_sample_plugin: Build the sample plugin
  try_the_sample_session_quota_exhaustion_action: Try the sample session quota exhaustion action
---

# Customize session quota exhaustion actions

AM provides built-in [session quota exhaustion actions](session-quotas.html) 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](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/ServiceLoader.html) 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?](https://support.pingidentity.com/s/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.

> **Collapse: 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

1. 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?](https://support.pingidentity.com/s/article/How-do-I-access-and-build-the-sample-code-provided-for-PingAM).

2. When the build completes, copy the `quotaexhaustionaction-8.1.1.jar` file to the `WEB-INF/lib` directory where you deployed AM:

   ```bash
   $ cp target/quotaexhaustionaction-8.1.1.jar /path/to/tomcat/webapps/am/WEB-INF/lib/
   ```

3. 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`:

   ```bash
   $ cd /path/to/tomcat/webapps/am/WEB-INF/classes/
   $ jar -xvf ../lib/openam-core-8.1.1.jar amSession.properties
   inflated: amSession.properties
   ```

4. Add the following line to `amSession.properties`:

   ```properties
   customActionI18nKey=Randomly Destroy Session
   ```

5. Restart AM or the container in which it runs to load the plugin.

## Try the sample session quota exhaustion action

1. In the AM admin UI, go to Configure > Global Services, click Session, and select the Session Quotas tab.

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

3. Open multiple browser windows and log in with the same user until you exceed the session quota.

4. Observe that one of the sessions is removed when the session quota is met.