--- title: Throttling policies description: To protect applications from being overused by clients, use a ThrottlingFilter with one of the following policies to limit how many requests clients can make in a defined time: component: pinggateway version: 7.2 page_id: pinggateway:reference:ThrottlingPolicies canonical_url: https://docs.pingidentity.com/pinggateway/2026/reference/ThrottlingPolicies.html llms_txt: https://docs.pingidentity.com/pinggateway/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2022-04-12T12:16:42Z superseded_by: https://docs.pingidentity.com/pinggateway/2026/reference/ThrottlingPolicies.html section_ids: MappedThrottlingPolicy: MappedThrottlingPolicy MappedThrottlingPolicy-usage: Usage MappedThrottlingPolicy-properties: Properties example-throttling-mapped: Example of a Mapped Throttling Policy MappedThrottlingPolicy-moreinfo: More information ScriptableThrottlingPolicy: ScriptableThrottlingPolicy ScriptableThrottlingPolicy-usage: Usage ScriptableThrottlingPolicy-properties: Properties example-throttling-scriptable: Example of a scriptable throttling policy ScriptableThrottlingPolicy-moreinfo: More information DefaultRateThrottlingPolicy: DefaultRateThrottlingPolicy DefaultRateThrottlingPolicy-usage: Usage DefaultRateThrottlingPolicy-properties: Properties DefaultRateThrottlingPolicy-example: Example DefaultRateThrottlingPolicy-moreinfo: More information --- # Throttling policies To protect applications from being overused by clients, use a [ThrottlingFilter](Filters.html#ThrottlingFilter) with one of the following policies to limit how many requests clients can make in a defined time: ## MappedThrottlingPolicy Maps different throttling rates to different groups of requests, according to the evaluation of `throttlingRateMapper`. ### Usage ```json { "name": string, "type": "ThrottlingFilter", "config": { "requestGroupingPolicy": runtime expression, "throttlingRatePolicy": { "type": "MappedThrottlingPolicy", "config": { "throttlingRateMapper": runtime expression, "throttlingRatesMapping": { "mapping1": { "numberOfRequests": configuration expression, "duration": configuration expression }, "mapping2": { "numberOfRequests": configuration expression, "duration": configuration expression } }, "defaultRate": { "numberOfRequests": configuration expression, "duration": configuration expression } } } } } ``` ### Properties * `"throttlingRateMapper"`: *runtime expression<[string](preface.html#definition-string)>, required* An expression to categorize requests for mapping to a throttling rate in the `throttlingRatesMapping`. If this parameter is null or does not match any specified mappings, the default throttling rate is applied. * `"throttlingRatesMapping"`: *[object](preface.html#definition-object), required* A map of throttling rate by request group. Requests are categorized into groups by the evaluation of the expression `"throttlingRateMapper"`. * `"mapping1"` and `"mapping2"`: *string, required* The evaluation of the expression `"throttlingRateMapper"`. The number of mappings is not limited to two. - `"numberOfRequests"`: *configuration expression\, required* The number of requests allowed through the filter in the time specified by `"duration"`. * `"duration"`: *configuration expression<[duration](preface.html#definition-duration)>, required* A time interval during which the number of requests passing through the filter is counted. * `"defaultRate"`: *[object](preface.html#definition-object), required* The default throttling rate to apply if the evaluation of the expression `"throttlingRateMapper"` is null or is not mapped to a throttling rate. - `"numberOfRequests"`: *configuration expression\, required* The number of requests allowed through the filter in the time specified by `"duration"`. * `"duration"`: *configuration expression<[duration](preface.html#definition-duration)>, required* A time interval during which the number of requests passing through the filter is counted. ### Example of a Mapped Throttling Policy In the following example, requests from users with different statuses are mapped to different throttling rates. For information about how to set up and test this example, see [Configure Mapped Throttling](../gateway-guide/throttling.html#throttling-mapped). ```json { "name": "00-throttle-mapped", "baseURI": "http://app.example.com:8081", "condition": "${find(request.uri.path, '^/home/throttle-mapped')}", "heap": [ { "name": "SystemAndEnvSecretStore-1", "type": "SystemAndEnvSecretStore" }, { "name": "AmService-1", "type": "AmService", "config": { "agent": { "username": "ig_agent", "passwordSecretId": "agent.secret.id" }, "secretsProvider": "SystemAndEnvSecretStore-1", "url": "http://am.example.com:8088/openam/", "version": "7.2" } } ], "handler": { "type": "Chain", "config": { "filters": [ { "name": "OAuth2ResourceServerFilter-1", "type": "OAuth2ResourceServerFilter", "config": { "scopes": [ "mail", "employeenumber" ], "requireHttps": false, "realm": "OpenIG", "accessTokenResolver": { "name": "token-resolver-1", "type": "TokenIntrospectionAccessTokenResolver", "config": { "amService": "AmService-1", "providerHandler": { "type": "Chain", "config": { "filters": [ { "type": "HttpBasicAuthenticationClientFilter", "config": { "username": "ig_agent", "passwordSecretId": "agent.secret.id", "secretsProvider": "SystemAndEnvSecretStore-1" } } ], "handler": "ForgeRockClientHandler" } } } } } }, { "name": "ThrottlingFilter-1", "type": "ThrottlingFilter", "config": { "requestGroupingPolicy": "${contexts.oauth2.accessToken.info.mail}", "throttlingRatePolicy": { "name": "MappedPolicy", "type": "MappedThrottlingPolicy", "config": { "throttlingRateMapper": "${contexts.oauth2.accessToken.info.status}", "throttlingRatesMapping": { "gold": { "numberOfRequests": 6, "duration": "10 s" }, "silver": { "numberOfRequests": 3, "duration": "10 s" }, "bronze": { "numberOfRequests": 1, "duration": "10 s" } }, "defaultRate": { "numberOfRequests": 1, "duration": "10 s" } } } } } ], "handler": "ReverseProxyHandler" } } } ``` ### More information [org.forgerock.openig.filter.throttling.MappedThrottlingPolicyHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/throttling/MappedThrottlingPolicyHeaplet.html) ## ScriptableThrottlingPolicy Uses a script to look up the throttling rates to apply to groups of requests. The script can store the mapping for the throttling rate in memory, and can use a more complex mapping mechanism than that used in the `MappedThrottlingPolicy`. For example, the script can map the throttling rate for a range of IP addresses. The script can also query an LDAP directory, an external database, or read the mapping from a file. Scripts must return a [Promise\](../_attachments/apidocs/org/forgerock/util/promise/Promise.html) or a [ThrottlingRate](../_attachments/apidocs/org/forgerock/openig/filter/throttling/ThrottlingRate.html). For information about script properties, available global objects, and automatically imported classes, see [Scripts](Scripts.html). * For an example of how to create a ScriptableThrottlingPolicy in Studio, see [Configure scriptable throttling](../gateway-guide/throttling.html#throttling-scriptable). ### Usage ```json { "type": "ThrottlingFilter", "config": { "requestGroupingPolicy": runtime expression, "throttlingRatePolicy": { "name": string, "type": "ScriptableThrottlingPolicy", "config": { "type": configuration expression, "file": configuration expression, // Use either "file" "source": [ string, ... ], // or "source", but not both "args": map, "clientHandler": Handler reference } } } } ``` ### Properties For information about properties for ScriptableThrottlingPolicy, see [Scripts](Scripts.html). ### Example of a scriptable throttling policy In the following example, the `DefaultRateThrottlingPolicy` delegates the management of throttling to the scriptable throttling policy. For information about how to set up and test this example, see [Configure scriptable throttling](../gateway-guide/throttling.html#throttling-scriptable). ```json { "name": "00-throttle-scriptable", "baseURI": "http://app.example.com:8081", "condition": "${find(request.uri.path, '^/home/throttle-scriptable')}", "heap": [ { "name": "SystemAndEnvSecretStore-1", "type": "SystemAndEnvSecretStore" }, { "name": "AmService-1", "type": "AmService", "config": { "agent": { "username": "ig_agent", "passwordSecretId": "agent.secret.id" }, "secretsProvider": "SystemAndEnvSecretStore-1", "url": "http://am.example.com:8088/openam/", "version": "7.2" } } ], "handler": { "type": "Chain", "config": { "filters": [ { "name": "OAuth2ResourceServerFilter-1", "type": "OAuth2ResourceServerFilter", "config": { "scopes": [ "mail", "employeenumber" ], "requireHttps": false, "realm": "OpenIG", "accessTokenResolver": { "name": "token-resolver-1", "type": "TokenIntrospectionAccessTokenResolver", "config": { "amService": "AmService-1", "providerHandler": { "type": "Chain", "config": { "filters": [ { "type": "HttpBasicAuthenticationClientFilter", "config": { "username": "ig_agent", "passwordSecretId": "agent.secret.id", "secretsProvider": "SystemAndEnvSecretStore-1" } } ], "handler": "ForgeRockClientHandler" } } } } } }, { "name": "ThrottlingFilter-1", "type": "ThrottlingFilter", "config": { "requestGroupingPolicy": "${contexts.oauth2.accessToken.info.mail}", "throttlingRatePolicy": { "type": "DefaultRateThrottlingPolicy", "config": { "delegateThrottlingRatePolicy": { "name": "ScriptedPolicy", "type": "ScriptableThrottlingPolicy", "config": { "type": "application/x-groovy", "source": [ "if (contexts.oauth2.accessToken.info.status == status) {", " return new ThrottlingRate(rate, duration)", "} else {", " return null", "}" ], "args": { "status": "gold", "rate": 6, "duration": "10 seconds" } } }, "defaultRate": { "numberOfRequests": 1, "duration": "10 s" } } } } } ], "handler": "ReverseProxyHandler" } } } ``` ### More information [org.forgerock.openig.filter.throttling.ScriptableThrottlingPolicy.Heaplet](../_attachments/apidocs/org/forgerock/openig/filter/throttling/ScriptableThrottlingPolicy.Heaplet.html) ## DefaultRateThrottlingPolicy Provides a default throttling rate if the delegating throttling policy returns `null`. ### Usage ```json { "name": string, "type": "ThrottlingFilter", "config": { "requestGroupingPolicy": expression, "throttlingRatePolicy": { "type": "DefaultRateThrottlingPolicy", "config": { "delegateThrottlingRatePolicy": ThrottlingRatePolicy reference, "defaultRate": { "numberOfRequests": configuration expression, "duration": configuration expression } } } } } ``` ### Properties * `"delegateThrottlingRatePolicy"`: *ThrottlingRatePolicy [reference](preface.html#definition-reference), required* The policy to which the default policy delegates the throttling rate. The `DefaultRateThrottlingPolicy` delegates management of throttling to the policy specified by `delegateThrottlingRatePolicy`. If `delegateThrottlingRatePolicy` returns `null`, the `defaultRate` is used. For information about policies to use, see [MappedThrottlingPolicy](#MappedThrottlingPolicy) and [ScriptableThrottlingPolicy](#ScriptableThrottlingPolicy). * `"defaultRate"`: *[object](preface.html#definition-object), required* The default throttling rate to apply if the delegating policy returns `null`. - `"numberOfRequests"`: *configuration expression\, required* The number of requests allowed through the filter in the time specified by `"duration"`. * `"duration"`: *configuration expression<[duration](preface.html#definition-duration)>, required* A time interval during which the number of requests passing through the filter is counted. ### Example For an example of how this policy is used, see [Example of a Scriptable Throttling Policy](#example-throttling-scriptable). ### More information [org.forgerock.openig.filter.throttling.DefaultRateThrottlingPolicyHeaplet](../_attachments/apidocs/org/forgerock/openig/filter/throttling/DefaultRateThrottlingPolicyHeaplet.html)