Add documentation topic to authentication backends section for HTTP basic authentication

_security/authentication-backends/basic-authc.md

@@ -0,0 +1,48 @@
+---
+layout: default
+title: HTTP basic authentication
+parent: Authentication backends
+nav_order: 46
+redirect_from:
+---
+
+
+# HTTP basic authentication
+
+HTTP basic authentication provides a simple challenge-and-response process for gaining access to OpenSearch and its resources that prompts you to sign in with a username and password. You enable HTTP basic authentication in the `http_authenticator` section of the configuration by specifying `type` as `basic`, as shown in the following example:
+
+```yml
+authc:
+  basic_internal_auth_domain:
+    description: "Authenticate using HTTP basic against the internal users database"
+    http_enabled: true
+    transport_enabled: true
+    order: 1
+    http_authenticator:
+      type: basic
+      challenge: true
+    authentication_backend:
+      type: internal
+```
+
+Additionally, you can specify the internal user database as the authentication backend by specifying `internal` as the type for `authentication_backend`. See [The internal user database](#the-internal-user-database) for information about this backend.
+
+Once `basic` is specified for the type of HTTP authenticator and `internal` is specified for the type of authentication backend, no further configuration in `config.yml` is needed, unless you plan to use additional authentication backends with HTTP basic authentication. Continue reading for considerations related to this type of setup and more information about the `challenge` setting.
+
+
+## The challenge setting
+
+In most cases, it's appropriate to set `challenge` to `true` for basic authentication. This setting defines the behavior of the Security plugin when the `Authorization` field in the HTTP header is not specified. By default, the setting is `true`. 
+
+When `challenge` is set to `true`, the Security plugin sends a response with the 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 username and password. This is a common configuration when HTTP basic authentication is the only backend being used.
+
+When `challenge` is set to `false` and an `Authorization` header has not been specified in the request, the Security plugin does not send a `WWW-Authenticate` response back to the client, and authentication fails. This configuration is often used when you have multiple challenging `http_authenticator` settings included in your configured authentication domains. This might be the case, for example, when you plan to use basic authentication and SAML together. For an example and a more complete explanation of this configuration, see [Running multiple authentication domains]({{site.url}}{{site.baseurl}}/security/authentication-backends/saml/#running-multiple-authentication-domains) in the SAML documentation.
+
+When you define multiple HTTP authenticators, make sure to order non-challenging authenticators first---such as `proxy` and `clientcert`---and order challenging HTTP authenticators last. For example, in a configuration where a non-challenging HTTP basic authentication backend is paired with a challenging SAML backend, you might specify `order: 0` in the HTTP basic `authc` domain and `order: 1` in the SAML domain.
+{: .note }
+
+
+## The internal user database
+
+When using HTTP basic authentication, the internal user database stores the internal users and includes their hashed passwords and other user attributes, such as roles. Users and their settings are kept in the `internal_users.yml` configuration file. For more information about this file, see [internal_users.yml]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#internal_usersyml) in the security configuration documentation.
+

_security/configuration/api-rate-limiting.md

@@ -0,0 +1,84 @@
+---
+layout: default
+title: API rate limiting
+parent: Configuration
+nav_order: 30
+---
+
+
+# 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, by restricting failed login attempts, have the potential to defend against denial of service (DoS) attacks or repeated login attempts intended to gain access through trial and error.
+
+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
+
+The username rate limiting configuration limits login attempts by username. When a login fails, the username is blocked from use by 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 attempts are blocked. Be aware that increasing the number increases heap usage. |
+| `time_window_seconds` | The window of time during which the value for `allowed_tries` is enforced. For example, if `allowed_tries` is `3` and `time_window_seconds` is `60`, a username has 3 attempts to log in successfully within a 60-second time span before login attempts are blocked. |
+| `block_expiry_seconds` | The window of time during which login attempts remain blocked after a failed login. After this time elapses, login is reset and the username can attempt to log in again. |
+| `max_blocked_clients` | The maximum number of blocked usernames. This limits heap usage to avoid a potential DoS attack. |
+| `max_tracked_clients` | The maximum number of tracked usernames with failed login attempts. This limits heap usage to avoid a potential DoS attack. |
+
+
+## IP address rate limiting
+
+The IP address rate limiting configuration limits login attempts by IP address. When a login fails, the IP address specific to the machine being used for login is blocked. 
+
+Configuring IP address rate limiting involves two steps. 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]({{site.url}}{{site.baseurl}}/security/authentication-backends/basic-authc/).
+
+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 attempts are blocked. Be aware that increasing the number increases heap usage. |
+| `time_window_seconds` | The window of time during 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 3 attempts to log in successfully within a 60-second time span before login attempts are blocked. |
+| `block_expiry_seconds` | The window of time during which login attempts remain blocked after a failed login. After this time elapses, login is reset and the IP address can attempt to log in again. |
+| `max_blocked_clients` | The maximum number of blocked IP addresses. This limits heap usage to avoid a potential DoS attack. |
+| `max_tracked_clients` | The maximum number of tracked IP addresses with failed login attempts. This limits heap usage to avoid a potential DoS attack. |
+