This rule uses a token bucket to control the number of incoming requests.

The configuration defines a number of requests and an interval that must elapse between requests. The allowed number of requests within the time window is controlled by the Max Burst Requests setting, which is visible when you click Show Advanced. For example, if the Max Burst Requests value is 1, two requests are allowed in the request interval, one normal request and one burst request.

If a request wasn't received, the number of allowed requests is incremented by one at the end of each Request Interval. This continues until the number of allowed requests equals the Max Burst Requests value.

Note:

Using the rate limiting rule in a clustered PingAccess environment can impose stricter clock synchronization requirements for requests processed by multiple engine nodes. Alternatively, you can configure a load balancer sitting in front of a PingAccess cluster to stick the session to a specific engine, ensuring that the rate limiting rule is applied by a single PingAccess engine node. For more information, see Configuring load balancing strategies.

  1. Click Access and then go to Rules > Rules.
  2. Click + Add Rule.
  3. In the Name field, enter a unique name, up to 64 characters long.

    Special characters and spaces are allowed.

  4. In the Type list, select Rate Limiting.
  5. Select a Policy Granularity, as defined in the following table.
    Policy GranularityDefinition

    Resource

    Restricts the rate of requests based on the resource requested.

    Identity

    Restricts the rate of requests to the identity associated with the current authentication token, such as a PingAccess cookie or an OAuth token. This is the default value.

    IP

    Restricts the number of requests based on the source IP address. The IP address used to apply this policy comes from the HTTP request's IP source configuration options, or any options that override that configuration, if those options are configured.

    OAuth Client

    Restricts the number of requests to all OAuth tokens obtained by a specific Client ID.

    Note:

    If you select OAuth Client as the policy granularity for a rate limiting rule, the rule will not work if it's applied to a web application.
  6. Define, in milliseconds, a Request Interval.
  7. Optional: Click Show Advanced Settings to configure advanced options:
    Advanced SettingDescription

    Max Burst Requests

    If more than one request should be allowed in a request interval, enter the number of requests to allow in the Max Burst Requests field.

    Note:

    PingAccess increases the number of available requests only after a request interval that serves no requests to the client. As a result, in the period following a cycle where the remaining allowed burst requests is reduced to 0, no burst requests are allowed, regardless of this setting.

    Set Retry-After Header

    If PingAccess should reply to the client with a Retry-After header instructing the client to wait for a period of time, select the Set Retry-After Header check box.

    Rejection Handling

    To configure rejection handling, select a rejection handling method:

    If you select Default, use the Rejection Handler list to select an existing rejection handler that defines whether to display an error template or redirect to a URL.

    If you select Basic, you can customize an error message to display as part of the default error page rendered in the end-user's browser if rule evaluation fails. This page is among the templates you can modify with your own branding or other information. If you select Basic, provide the following:

    1. In the Error Response Code field, enter the HTTP status response code to send if rule evaluation fails.

      The default is 403.

    2. In the Error Response Status Message field, enter the HTTP status response message to send if rule evaluation fails.

      The default is Forbidden.

    3. In the Error Response Template File field, enter the HTML template page for customizing the error message that displays if rule evaluation fails.

      This template file is located in the <PA_HOME>/conf/template/ directory.

    4. In the Error Response Content Type list, select the type of content for the error response.

      This lets the client properly display the response.
  8. Click Save.