From 08b9d4a09b8c82ae81986ffa4a956c7155d8dab3 Mon Sep 17 00:00:00 2001 From: Josh Date: Tue, 13 Feb 2024 11:50:09 -0500 Subject: [PATCH 1/2] docs(admin): revise the brute force protection configuration chapter Co-authored-by: Joas Schilling <213943+nickvergessen@users.noreply.github.com> Signed-off-by: Josh --- .../bruteforce_configuration.rst | 190 +++++++++++++++--- 1 file changed, 165 insertions(+), 25 deletions(-) diff --git a/admin_manual/configuration_server/bruteforce_configuration.rst b/admin_manual/configuration_server/bruteforce_configuration.rst index 212a40751..a5984489c 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,82 @@ 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. + +Additional Details +------------------ + +Feature History +~~~~~~~~~~~~~~~ + +(Notable) + +* Server 10.0: + - Added: Initial implementation +* Server 12.0: + - Fixed: Disregard existing recent attempts immediately if BPF is disabled manually + - Added: Admin security settings section for managing some parameters (via the ``bruteforcesettings`` shipped app) + - Added: Enable the admin to exclude IP addresses from throttling (via the ``bruteforcesettings`` shipped app) +* Server 13.0 + - Changed: Reset bruteforce attempts upon successful login (only the entries associated with that user from that IP) +* Server 14.0 + - Fixed: Avoid unintentional client authentication timeouts (for well behaving clients) +* Server 15.0 + - Changed: Reset bruteforce attempts upon successful token refresh when using OAuth +* Server 18.0 + - Fixed: Handle scoped IPv6 addresses +* Server 20.0 + - Changed: When maximum delay is reached and maximum attempts permitted have been exceeded within the past 30 minutes, return "429 Too Many Requests" until no longer the true + - Added: ``occ`` command to reset bruteforce attempts for an IP (``occ security:bruteforce:reset``) +* Server 21.0 + - Added: Once a day cronjob added to cleanup stale attempt entries + - Changed: Delete all entries >48 hours old +* Server 24.0 + - Added: Logging of throttling or blocking (info level) +* Server 28.0 + - Fixed: Reset bruteforce attempts upon successful sudo attempt + - Added: Memcache based backend + - Added: Show admins when they are throttled (via standard setup checks) + - Added: Show current user throttling status (via the ``bruteforcesettings`` app) +* Server 29.0 + - Fixed: Don't throw a "500 Internal Server Error" when MaxDelayReached; instead return a "429 Too Many Requests" + - Fixed: Prevent setting empty IP masks when adding an exclusion (in the ``bruteforcesetting`` app) From 7e503a2c1298b977afbd361d0becdf2f86040352 Mon Sep 17 00:00:00 2001 From: Josh Date: Sat, 17 Feb 2024 12:33:14 -0500 Subject: [PATCH 2/2] Update bruteforce_configuration.rst: Drop feature history Signed-off-by: Josh --- .../bruteforce_configuration.rst | 39 ------------------- 1 file changed, 39 deletions(-) diff --git a/admin_manual/configuration_server/bruteforce_configuration.rst b/admin_manual/configuration_server/bruteforce_configuration.rst index a5984489c..5b2c8fb7d 100644 --- a/admin_manual/configuration_server/bruteforce_configuration.rst +++ b/admin_manual/configuration_server/bruteforce_configuration.rst @@ -155,42 +155,3 @@ It's possible to exclude IP addresses from the brute force protection. 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. - -Additional Details ------------------- - -Feature History -~~~~~~~~~~~~~~~ - -(Notable) - -* Server 10.0: - - Added: Initial implementation -* Server 12.0: - - Fixed: Disregard existing recent attempts immediately if BPF is disabled manually - - Added: Admin security settings section for managing some parameters (via the ``bruteforcesettings`` shipped app) - - Added: Enable the admin to exclude IP addresses from throttling (via the ``bruteforcesettings`` shipped app) -* Server 13.0 - - Changed: Reset bruteforce attempts upon successful login (only the entries associated with that user from that IP) -* Server 14.0 - - Fixed: Avoid unintentional client authentication timeouts (for well behaving clients) -* Server 15.0 - - Changed: Reset bruteforce attempts upon successful token refresh when using OAuth -* Server 18.0 - - Fixed: Handle scoped IPv6 addresses -* Server 20.0 - - Changed: When maximum delay is reached and maximum attempts permitted have been exceeded within the past 30 minutes, return "429 Too Many Requests" until no longer the true - - Added: ``occ`` command to reset bruteforce attempts for an IP (``occ security:bruteforce:reset``) -* Server 21.0 - - Added: Once a day cronjob added to cleanup stale attempt entries - - Changed: Delete all entries >48 hours old -* Server 24.0 - - Added: Logging of throttling or blocking (info level) -* Server 28.0 - - Fixed: Reset bruteforce attempts upon successful sudo attempt - - Added: Memcache based backend - - Added: Show admins when they are throttled (via standard setup checks) - - Added: Show current user throttling status (via the ``bruteforcesettings`` app) -* Server 29.0 - - Fixed: Don't throw a "500 Internal Server Error" when MaxDelayReached; instead return a "429 Too Many Requests" - - Fixed: Prevent setting empty IP masks when adding an exclusion (in the ``bruteforcesetting`` app)