The implementation of 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 was not 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 value defined by the Max Burst Requests setting.

Note:

The rate limiting rule might benefit from the configuration of a PingAccess Runtime State Cluster to ensure rate limits are enforced properly if the front-end load balancer does not provide a sticky session.

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.

  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. From the Type list, select Rate Limiting.
  5. Select a Policy Granularity, as defined in the following table.
    Policy Granularity Definition
    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 Requests IP Source configuration options, or 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.
  6. Enter, in milliseconds, a Request Interval.
  7. Optional: Click Show Advanced Settings to configure advanced options:
    1. If more than 1 request should be allowed 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.

    2. 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 option.
    3. Optional: 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 this information:
      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. From 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.