diff --git a/admin_manual/configuration_server/bruteforce_configuration.rst b/admin_manual/configuration_server/bruteforce_configuration.rst index 212a40751..5b2c8fb7d 100644 --- a/admin_manual/configuration_server/bruteforce_configuration.rst +++ b/admin_manual/configuration_server/bruteforce_configuration.rst @@ -2,28 +2,112 @@ Brute force protection ====================== -Nextcloud has built-in protection against brute force attempts. This protects -your system from attackers trying for example a lot of different passwords. +Introduction +------------ -Brute force protection is enabled by default on Nextcloud. +Nextcloud has built-in protection against brute force attempts. +The brute force protection feature is meant to protect Nextcloud servers from attempts to guess +passwords and tokens in various ways. Besides the obvious "let's try a big list of commonly used +passwords" attack, it also makes it harder to use slightly more sophisticated attacks via the reset +password page or trying to find app password tokens. It is used throughout the Nextcloud ecosystem, +including by other apps, if they have sensitive entrypoints (and choose to enable support for it). How it works ------------ +Overview +~~~~~~~~ + +If triggered, brute force protection makes requests - coming from an IP address via a brute +force protected entrypoint - slower for up to a 24 hour period. In extreme circumstances it may prevent +access outright, for up to 30 minutes, from a problematic IP address. + +This protects your system from attackers trying, for example, a lot of different passwords. + +The primary filter is IP address-based. This means that any account - even one associated with +a given brute force attempt - is not impacted when it is connecting from a different IP address +than any brute force attempts. This helps minimize inadvertent denial of service attacks against +legitimate connections, while maximizing attack resistance from problematic IP sources. + +Nuisance triggers are minimized through reasonable built-in defaults appropriate to each type of action. + +The attempts history is automatically managed by a daily cronjob. Individual entries +expire after 48 hours (attempts, however, may be still *logged* indefinitely elsewhere through the usual +mechanisms within Nextcloud Server and at the discretion of the admin). + +Excluding (whitelisting) select IP addresses from brute force protection to prevent false +positives is supported, but usually false positives are best handled by fixing the underlying causes +(e.g. a misconfigured reverse proxy or misbehaving client). + +.. tip:: If you do notice a problem with the authentication behavior of any the official Nextcloud clients, + please report it to the appropriate repository so that it can be looked into. + +Keeping brute force protection active and operating properly helps protects your Nextcloud Server from +malicious actors while minimizing potential impact on legitimate usage. + +Example: The login page +~~~~~~~~~~~~~~~~~~~~~~~ + The brute force protection is easiest to see in action on the login page. If you try to log in the first time with an invalid username and/or password you will not notice anything. But if you do this a few times you start to notice that the verification of the login is taking longer each time. This is the brute force protection kicking in. -The maximum delay is 25 seconds. +The maximum delay is 25 seconds, unless maximum number of attempts (currently 10) was reached within +the last 30 minutes (in which case a ``429 Too Many Requests`` will be returned until the maximum attempts +within the recent time has dropped below the threshold). -After a successful login the attempts will be cleared. And once a user is -properly authenticated they will no longer be hit by the delay. +After a successful login (from the same source IP address), any prior invalid login attempts will be cleared +and you will no longer be hit by the delay. -Brute force protection and load balancer/reverse proxy ------------------------------------------------------- +.. note:: Not all actions are necessarily viewed the same. It is possible for some activities to be more (or less) strict + than others. + +Usage +----- + +Activating +~~~~~~~~~~ + +Brute force protection is enabled by default on Nextcloud. Its behavior can be adjusted through the +``bruteforcesettings`` app (shipped with Server and enabled by default), several ``occ`` commands, and several +``config.php`` parameters. Its effectiveness is highly dependent on having a properly configured environment, +particularly when integrating a reverse proxy with Nextcloud (and associated parameters such as ``trusted_proxies``). + +The brute force settings app +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This app, which shipped and enabled by default, makes it possible (via the Web UI) to view the status of a +connection and modify certain parameters of the brute force protection built into Nextcloud Server. + +The user interface added by this app is found under *Administration settings -> Security* under the *Brute-force +IP whitelist* heading. + +Currently an admin can view the status of the IP address they are connecting from as well as specify IPv4 or IPv6 +addresses and ranges to exempt from brute force protection. + +Additional enhancements may be made in the future, within this app and/or in combination with Nextcloud Server for +additional monitoring or behavior adjustments related to brute force protection. + +.. warning:: Disabling the ``bruteforcesettings`` app does **not** disable brute force protection + - it merely removes your ability to adjust brute force related settings from the Web interface. + +.. danger:: + + You would need to adjust the parameter ``auth-bruteforce-protection-enabled`` in your Nextcloud ``config.php`` to + disable brute force protection, which is **heavily discouraged for production servers**, particularly if your + server is reachable via a public IP address. It allows an attacker to iterate over all users and their passwords + as well as two-factor verifications afterwards ultimately leading to admin access. + +``occ`` commands +~~~~~~~~~~~~~~~~ + +There are several brute force related ``occ`` commands under ``occ security``. + +Brute force protection and load balancers/reverse proxies +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you are behind a reverse proxy or load balancer it is important you make sure it is setup properly. Especially the **trusted_proxies** and **forwarded_for_headers** @@ -31,26 +115,43 @@ setup properly. Especially the **trusted_proxies** and **forwarded_for_headers** that Nextcloud actually starts throttling all traffic coming from the reverse proxy or load balancer. For more information see :doc:`reverse_proxy_configuration`. - -Exclude IP addresses from brute force protection ------------------------------------------------- - -It's possible to exlude IP addresses from the brute force protection. - -- Enable the bruteforcesettings app -- Login as admin and go to Administration settings -> Security - -.. warning:: - - Note that any excluded IP address can perform authentication attempts without any throttling. - Its best to exclude as few IP addresses as you can, or even none at all. - Troubleshooting --------------- +Overview +~~~~~~~~ + On most setups Nextcloud will work out of the box without any issues. If you -run into a situation where login is often very slow for all users the first -step is to inspect the `bruteforce_attempts` table. There you can see -which IP addresses are actually throttled. +run into a situation where logging in or connecting is often very slow for multiple users, the first +step is to check your Nextcloud Server logs to see what IP addresses are being detected (you may need +adjust your logging to INFO level temporarily to do so). +If all clients appear to be coming from the same IP address and that IP address happens to be your +proxy, you need to review your ``trusted_proxies`` configuration. If it is a common connection point, +such as a multi-user office location, it is possible whitelisting is appropriate. +For testing purposes you want want to whitelist your own IP address to see if the problem disappears. +If it does - and assuming your proxy configuration is correct - you may have a client/device in your +network that is misbehaving and generating invalid login attempts from your IP address. + +For detailed troubleshooting, you may wish to inspect the `bruteforce_attempts` database table. There +you can see which IP addresses are throttled and any other metadata stored about their attempts to +connect. + +Excluding IP addresses from brute force protection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. note:: Most nuisance triggering of brute force protection can be resolved through proper configuration of reverse + proxies. In other cases, select IP addresses that need to be whitelisted can be configured within this app (while + leaving brute force protection enabled). This can be useful for testing purposes or when there are a lot of people + (or devices) connecting from a known, single IP address. + +It's possible to exclude IP addresses from the brute force protection. + +- Make sure the ``bruteforcesettings`` app is enabled (it is by default) +- Login as admin and go to **Administration settings -> Security** + +.. danger:: + + Any excluded IP address can perform authentication attempts without any throttling. + It's best to exclude as few IP addresses as you can, or even none at all.