Add documentation for API rate limiting (#4287)

* fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> * fix#4171 api rate limit Signed-off-by: cwillum <[email protected]> --------- Signed-off-by: cwillum <[email protected]>
opensearch-project · Jun 13, 2023 · 9a8995d · 9a8995d
1 parent 492cddd
commit 9a8995d
Showing 1 changed file with 78 additions and 1 deletion.
diff --git a/_security/configuration/configuration.md b/_security/configuration/configuration.md
@@ -136,7 +136,84 @@ In most cases, you set the `challenge` flag to `true`. The flag defines the beha
 
 If `challenge` is set to `true`, the Security plugin sends a response with status `UNAUTHORIZED` (401) back to the client. If the client is accessing the cluster with a browser, this triggers the authentication dialog box, and the user is prompted to enter a user name and password.
 
-If `challenge` is set to `false` and no `Authorization` header field is set, the Security plugin does not send a `WWW-Authenticate` response back to the client, and authentication fails. You might want to use this setting if you have another challenge `http_authenticator` in your configured authentication domains. One such scenario is when you plan to use basic authentication and OpenID Connect together.
+If `challenge` is set to `false` and no `Authorization` header field is set, the Security plugin does not send a `WWW-Authenticate` response back to the client, and authentication fails. Consider using this setting if you have more than one challenge `http_authenticator` keys in your configured authentication domains. This might be the case, for example, when you plan to use basic authentication and OpenID Connect together.
+
+
+## API rate limiting
+
+API rate limiting is typically used to restrict the number of API calls that users can make in a set span of time, thereby helping to manage the rate of API traffic. For security purposes, rate limiting features have the potential to defend against DoS attacks, or repeated login attempts to gain access through trial and error, by restricting failed login attempts.
+
+You have the option to configure the Security plugin for username rate limiting, IP address rate limiting, or both. These configurations are made in the `config.yml` file. See the following sections for information about each type of rate limiting configuration.
+
+
+### Username rate limiting
+
+This configuration limits login attempts by username. When a login fails, the username is blocked for any machine in the network. The following example shows `config.yml` file settings configured for username rate limiting:
+
+```yml
+auth_failure_listeners:
+      internal_authentication_backend_limiting:
+        type: username
+        authentication_backend: internal
+        allowed_tries: 3
+        time_window_seconds: 60
+        block_expiry_seconds: 60
+        max_blocked_clients: 100000
+        max_tracked_clients: 100000
+```
+{% include copy.html %}
+
+The following table describes the individual settings for this type of configuration.
+
+| Setting | Description |
+| :--- | :--- |
+| `type` |  The type of rate limiting. In this case, `username`. |
+| `authentication_backend` | The internal backend. Enter `internal`. |
+| `allowed_tries` |  The number of login attempts allowed before login is blocked. Be aware that increasing the number increases heap usage. |
+| `time_window_seconds` | The window of time in which the value for `allowed_tries` is enforced. For example, if `allowed_tries` is `3` and `time_window_seconds` is `60`, a username has three attempts to log in successfully within a 60-second time span before login is blocked. |
+| `block_expiry_seconds` | The duration of time that login remains blocked after a failed login. After this time elapses, login is reset and the username can attempt successful login again. |
+| `max_blocked_clients` |  The maximum number of blocked usernames. This limits heap usage to avoid a potential DoS. |
+| `max_tracked_clients` | The maximum number of tracked usernames that have failed login. This limits heap usage to avoid a potential DoS. |
+
+
+### IP address rate limiting
+
+This configuration limits login attempts by IP address. When a login fails, the IP address specific to the machine being used for login is blocked. 
+
+There are two steps for configuring IP address rate limiting. First, set the `challenge` setting to `false` in the `http_authenticator` section of the `config.yml` file.
+
+```yml
+http_authenticator:
+  type: basic
+  challenge: false
+```
+
+For more information about this setting, see [HTTP basic authentication](#http-basic-authentication).
+
+Second, configure the IP address rate limiting settings. The following example shows a completed configuration:
+
+```yml
+auth_failure_listeners:
+      ip_rate_limiting:
+        type: ip
+        allowed_tries: 1
+        time_window_seconds: 20
+        block_expiry_seconds: 180
+        max_blocked_clients: 100000
+        max_tracked_clients: 100000
+```
+{% include copy.html %}
+
+The following table describes the individual settings for this type of configuration.
+
+| Setting | Description |
+| :--- | :--- |
+| `type` |  The type of rate limiting. In this case, `ip`. |
+| `allowed_tries` |  The number of login attempts allowed before login is blocked. Be aware that increasing the number increases heap usage. |
+| `time_window_seconds` | The window of time in which the value for `allowed_tries` is enforced. For example, if `allowed_tries` is `3` and `time_window_seconds` is `60`, an IP address has three attempts to log in successfully within a 60-second time span before login is blocked. |
+| `block_expiry_seconds` | The duration of time that login remains blocked after a failed login. After this time elapses, login is reset and the IP address can attempt successful login again. |
+| `max_blocked_clients` |  The maximum number of blocked IP addresses. This limits heap usage to avoid a potential DoS. |
+| `max_tracked_clients` | The maximum number of tracked IP addresses that have failed login. This limits heap usage to avoid a potential DoS. |
 
 
 ## Backend configuration examples