Learn Authelia - Brute Force Protection (Regulation)

#Introduction

In episode 20 you managed consent — the entry point for legitimate applications. Episode 21 turns 180 degrees: facing attackers trying to guess passwords blindly. That attack is called brute force, and Authelia answers it via regulation.

Imagine an ATM that rejects your card after three wrong PINs. That's the principle of regulation: not just preventing one failed attempt, but making repeated short-term attempts difficult. An attacker needs thousands of attempts to guess a password; regulation makes those thousands of attempts impossible in a short time.

#Why Repeated Attempts Are Dangerous

Even a strong password remains fragile if an attacker can try without limit. Brute force attacks and credential stuffing — using password combinations leaked from other sites — work by volume: try millions of combinations until one matches. Without a limiter, the Authelia login endpoint is a slot machine that never rejects a player.

Regulation changes the game: every failure is recorded, and if failures exceed a threshold within a certain time window, Authelia stops further attempts temporarily.

#Regulation Configuration

Regulation is set in the regulation section:

regulation:
  modes:
    - 'ip'
  max_retries: 3
  find_time: 2m
  ban_time: 15m

With the configuration above, three failures within two minutes will block the IP for fifteen minutes.

#Ban Modes: User or IP

Authelia supports two ban subjects:

• user — the account is the ban subject. Failed attempts on the same account are counted, from any IP.
• ip — the network address is the ban subject. Attempts from the same IP are counted, for any account.

Both can be combined: modes: ['user', 'ip']. Authelia's default is user, but the documentation recommends ip. The main reason: account-based bans can be abused by attackers to deliberately lock out a victim's account (denial of service), while IP-based bans are harder to provoke from outside. Of course, IPs can be changed — so in public environments, consider combining both.

#How Authelia Tracks Failed Attempts

Regulation works on first-factor failures, i.e. the username and password combination. Every failure is recorded in the storage backend along with time information, and the find_time window determines the counting: failures older than find_time are no longer counted.

#Behavior When Banned

When a ban is active, Authelia rejects the authentication request with a 403 status and a message explaining that the account or address is banned. A legitimate user caught by a ban can't log in until ban_time passes or the ban is removed manually — a painful effect, but intentional.

#Analyzing Logs

To monitor failed attempts and ban events, check the Authelia logs:

authelia storage bans list
docker logs authelia 2>&1 | grep -iE "authentication attempt|banned"

authelia storage bans list shows the ban entries stored in the database. Log lines list the user, source IP, and failure reason. Suspicious patterns — many failures from one IP or one account — are early signs of an attack.

#Example Ban Scenario

Imagine the configuration max_retries: 3, find_time: 2m, and ban_time: 15m. An attacker tries to guess the root account password three times within one minute. Authelia records three failures within the two-minute window, then blocks the attacker's IP for fifteen minutes. The log snippet would look roughly like this:

level=info msg="Authentication attempt for user 'root' failed"
level=info msg="Authentication attempt for user 'root' failed"
level=warning msg="Authentication ban applied to IP 203.0.113.5"

Note the levels: ordinary failures are logged at the info level, while a ban is raised to the warning level. Filtering logs at the warning level in an alerting system becomes a simple alarm telling you an attacker is trying to get in.

#Tuning Regulation Without Trapping Users

Regulation is a balance between security and convenience. A few guidelines:

• Watch where your users come from. If legitimate users come from one large NAT IP, for example an office, an IP-based ban could trap many people at once.
• Bots and scanners keep trying logins and burn through the IP ban quota. Consider a slightly higher max_retries or a shorter find_time to reduce false bans.
• Use user-based bans for the highest-risk admin accounts, and IP-based bans for the general layer.
• Don't disable regulation; if it needs loosening, raise max_retries and ban_time, not drop them to zero.

#Handling Bans Manually

Sometimes a ban needs to be removed or applied manually — for example when an attacker is clearly targeting an account. The authelia storage bans CLI enables this:

authelia storage bans list
authelia storage bans delete --id 1

With the commands above you can see who's currently blocked, lift an incorrectly targeted ban, and record bans applied automatically by regulation.

#Closing

In this episode you understood:

• Regulation records failed login attempts and blocks when a threshold is exceeded.
• max_retries, find_time, and ban_time control when and how long a ban occurs.
• The user and ip modes determine the ban subject; both can be combined.
• Logs and the authelia storage bans CLI become monitoring and management tools.
• Tuning regulation is a balance between security and the convenience of legitimate users.

Regulation protects at the application level, but the next layer protects the whole connection. In episode 22, we discuss Security Headers & HTTPS — HSTS, CSP, and TLS policies that keep browsers and users safe. See you there!