DoS Protection¶

The Curity Identity Server provides built-in DoS (Denial of Service) protection designed for relatively simpler deployments.

Hint

For comprehensive DoS protection that can handle very large attacks, we recommend using specialized services instead of, or together with, the built-in DoS feature.

The DoS protection feature attempts to reject excessive requests from certain clients while minimizing server resource usage. For the system to work, it has to track client addresses, which introduces some memory overhead and may affect performance. For this reason, it is recommended that before enabling this feature, tests are used to validate that this protection mechanism meets your specific performance requirements.

Note

The DoS protection data is local to each Curity instance. In other words, Curity cluster nodes do not share information about clients between themselves. If a load balancer is placed in front of the Curity servers, then a single client will be able to make more requests over time than it could make against a single server instance. That is important to consider when configuring this feature.

Implementation Details¶

The DoS Protection feature uses the Leaky Bucket Algorithm.

This algorithm works as follows:

Each client has a virtual “bucket” that collects incoming requests.
Initially empty, the bucket allows clients to make short bursts of requests.
If requests continue at a high rate for some time, the bucket fills up.
When the bucket is full, excess requests are rejected.
The bucket gradually “leaks” (empties) over time as request volume decreases.

The system tracks clients by their IP address or host. To resolve the client address, Curity may take into consideration the X-Forwarded-For header, but that requires configuring White-listed-proxies. If the header is not set, the client IP address is used directly, which may not work correctly if a reverse proxy is always used before Curity receives any requests (because all requests will appear to come from a single IP address), hence it is highly recommended to configure appropriate white-listed proxies.

The maximum number of tracked clients can be configured. When the limit is reached, new clients receive a 503 (Service Unavailable) status code.

Requests rejected due to rate limiting receive a 429 (Too Many Requests) status code.

Configuration¶

To enable DoS Protection, activate the dos-protection setting on the service role.

The following configuration parameters are available (all parameters have sensible default values):

Parameter	Default Value	Description
max-requests-per-second	25	Maximum number of requests allowed per client per second. This controls the rate at which the bucket drips.
max-trackers	150_000	Maximum number of unique client addresses that may be tracked (enforced approximately). If `0`, no limit is enforced.
bucket-size	100	Maximum capacity of each client’s leaky bucket. Higher values permit larger request bursts.
idle-timeout	10	Number of seconds to retain tracking information for inactive clients before releasing their resources.

Notice that because of the algorithm used, max-requests-per-second can be exceeded while the bucket for a client has not completely filled up.

Example¶

Given a bucket size of 50, and max-requests-per-second is 10:

at first, a client can send up to 50 requests nearly simultaneously.
that will fill up the client’s bucket, which leaks at a rate of 10 requests per second, or 1 request every 100ms.
hence, if the next request arrives within 100ms from the latest request, it will be rejected.
if the next request arrives more than 100ms from the latest successful request, it is also successful.
if the client stops making requests for around 5 seconds (i.e. 50 drips at the rate of 10/sec), the bucket will empty completely again.

In the above scenario, it is recommended that the idle-timeout should be at least 5 seconds, allowing the client’s bucket to completely empty before the client tracker is removed.