Throttling Policies
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:
MappedThrottlingPolicy
Maps different throttling rates to different groups of requests, according to
the evaluation of throttlingRateMapper.
Usage
{
"name": string,
"type": "ThrottlingFilter",
"config": {
"requestGroupingPolicy": expression,
"throttlingRatePolicy": {
"type": "MappedThrottlingPolicy",
"config": {
"throttlingRateMapper": runtime expression<string>,
"throttlingRatesMapping": {
"mapping1": {
"numberOfRequests": integer,
"duration": duration string
},
"mapping2": {
"numberOfRequests": integer,
"duration": duration string
}
},
"defaultRate": {
"numberOfRequests": integer,
"duration": duration string
}
}
}
}
}Properties
"throttlingRateMapper": runtime expression<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, 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": integer, required-
The number of requests allowed through the filter in the time specified by
"duration".
"duration": duration string, required-
A time interval during which the number of requests passing through the filter is counted.
"defaultRate": 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": integer, required-
The number of requests allowed through the filter in the time specified by
"duration".
"duration": duration string, 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.
{
"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://openam.example.com:8088/openam/",
"version": "7.1"
}
}
],
"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"
}
}
}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<ThrottlingRate, Exception> or a ThrottlingRate.
This section describes the usage of ScriptableThrottlingPolicy, and refers to the following sections of the documentation:
-
For information about script properties, available global objects, and automatically imported classes, see Scripts.
-
For an example of how to create a ScriptableThrottlingPolicy in Studio, see Configure Scriptable Throttling.
Usage
{
"type": "ThrottlingFilter",
"config": {
"requestGroupingPolicy": expression,
"throttlingRatePolicy": {
"name": string,
"type": "ScriptableThrottlingPolicy",
"config": {
"type": string,
"file": string, // Use either "file"
"source": string or array of strings, // or "source", but not both
"args": object
}
}
}
}Properties
For information about properties for ScriptableThrottlingPolicy, see Scripts.
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.
{
"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://openam.example.com:8088/openam/",
"version": "7.1"
}
}
],
"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"
}
}
}DefaultRateThrottlingPolicy
=
Provides a default throttling rate if the delegating throttling policy returns
null.
Usage
{
"name": string,
"type": "ThrottlingFilter",
"config": {
"requestGroupingPolicy": expression,
"throttlingRatePolicy": {
"type": "DefaultRateThrottlingPolicy",
"config": {
"delegateThrottlingRatePolicy": reference or inline declaration,
"defaultRate": {
"numberOfRequests": integer,
"duration": duration string
}
}
}
}
}Properties
"delegateThrottlingRatePolicy": reference, required-
The policy to which the default policy delegates the throttling rate. The
DefaultRateThrottlingPolicydelegates management of throttling to the policy specified bydelegateThrottlingRatePolicy.If
delegateThrottlingRatePolicyreturnsnull, thedefaultRateis used.For information about policies to use, see MappedThrottlingPolicy and ScriptableThrottlingPolicy.
"defaultRate": object, required-
The default throttling rate to apply if the delegating policy returns
null.
"numberOfRequests": integer, required-
The number of requests allowed through the filter in the time specified by
"duration".
"duration": duration string, 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.