Throttling

Throttling, or rate-limiting, can be configured in many places in the Curity Identity Server. That makes it easy to ensure that only realistic request loads are allowed for each case, which has several advantages such as:

  • it reduces the attack surface (e.g. it becomes nearly impossible to try lots of different credentials in a short time).
  • users are not easily bombarded with communication originating from malicious services (e.g. attempting to register a victim’s email address multiple times).
  • the server quickly rejects requests from misbehaving/malicious clients that cause too much load, making it more resilient.

Here’s a list of places where a throttler may be used:

Note

A custom Plugin can utilize a Throttler by simply adding a getter for it in its configuration object.

Notice that different usages may “overlap”: if you configure a Throttler for the EmailSender Plugin, and another for the Email Authenticator, every time a user uses the Email Authenticator, they will be rate-limited by both Throttlers because both actions will occur: the user will be authenticating AND being sent an email message. This is intentional as it allows rate-limiting in a fine-grained way that takes context into consideration. Care must be taken so that the more “general” throttler (the Email Plugin, in this case) is more lenient than the more “specific” one (the Email Authenticator, in this case).

Configuration

A Throttler’s configuration consists of the following parameters:

  • id - identifier that can be used to reference the throttler.
  • bucket - data source (Bucket) to use to store state.
  • rate-intervals - list of rate intervals, each consisting of:
    • interval - the time interval.
    • max-allowed-attempts - maximum allowed attempts within the time interval.

All rate intervals are checked, one by one. If any of them is exceeded, then the action is throttled, i.e. the user will receive an error explaining that too many attempts have been made in a short period of time.

Custom Curity Plugins may need to handle the TooManyAttemptsException when a throttled service is called in order to report the error correctly to the end user.

Default Throttler

By default, no throttling is performed, but it’s easy to activate a default throttler so that anywhere a Throttler may be used, the default one will be automatically used if no throttling is configured explicitly.

Hint

It is recommended that a default throttler be configured in all Production Environments. That ensures that most sensitive operations are at least somewhat rate-limited by default.

There may be at most one default Throttler, but many more Throttler Services can be configured to be used in different contexts.

The default Throttler can only have a single rate-interval, unlike other Throttlers. By default, that rate-interval allows 1 attempt every 5 seconds.

Data Storage

The Throttler Service must be able to store information somewhere so that it can “remember” previous attempts at performing an action. For this reason, a Data Source that supports Bucket must be configured for a throttler.

Ideally, the data should automatically expire after the maximum period the throttlers are expected to use, as rate-limiting data is inherently ephemeral.

For reference, given the Throttler usages listed in this page, the following purposes are used:

  • sms-send
  • email-send
  • reset-password-email
  • email-auth
  • email-registration

This may be useful if you need to query (or cleanup) the data directly from the data-source used by the Throttler Service.

Privacy Information

Because in most cases, throttling is performed based on an user’s personal information, the throttler hashes the key provided to it (it currently uses SHA-256, but this may change in the future). This makes it safe to use in most cases.

The purpose is stored as listed in the previous section.

Email addresses are processed as follows before being hashed:

  • the local part (before @) is lowercased.
  • if the local part contains a +, anything after that is ignored.
  • the domain part (after @) is kept without changes.

Phone numbers are processed by removing all whitespaces before being hashed.

Legacy Throttlers

Curity has supported throttling in various ways since its very earliest releases. However, with the addition of the Throttler service in version 10.3, all the older ways to do throttling are considered legacy. We recommend migrating to the Throttler service at your earliest convenience.

One exception is the mechanism used to rate-limit credential verification, which still relies on ::ref::system_credential_managers_policies.