Brute Force Protection

ProAuth provides comprehensive brute force protection for UserStore authentication. Three independent mechanisms can be configured to protect user accounts from unauthorized access attempts: permanent account locking, temporary account locking, and progressive login throttling. Each mechanism is configured per UserStore IDP instance and can be enabled independently or combined for a layered defense.

Permanent Account Locking

When enabled, a user account is permanently locked after a configured number of consecutive failed login attempts. A locked account must be unlocked manually by an administrator through the Admin UI, the Management API, or the UserStore API.

A successful login resets the failed attempt counter to zero.

Configuration

Option	Description	Default
AttemptsBeforeUserLocked	Maximum number of consecutive failed login attempts before the account is permanently locked. Set to 0 or leave empty to disable permanent locking.	disabled

TIP

Permanent locking is well suited for high-security environments. Combine it with the user lock notification (see User lock notifications) to alert administrators when an account is locked so they can take immediate action.

WARNING

If permanent locking is the only mechanism enabled, an attacker can deliberately lock out legitimate users by repeatedly submitting wrong passwords. Consider enabling temporary locking or throttling in addition.

Temporary Account Locking

Temporary locking automatically locks a user account for a configurable duration after a number of consecutive failed login attempts. Once the lock duration expires, the user can attempt to log in again. This protects accounts without requiring administrator intervention.

While a temporary lock is active, all login attempts are rejected — even if the correct password is provided. The failed attempt counter is not incremented during the lock period.

Configuration

Option	Description	Default
TemporaryLockEnabled	Enable or disable temporary account locking.	false
TemporaryLockThreshold	Number of consecutive failed login attempts before a temporary lock is applied.	5
TemporaryLockDurationSeconds	Duration of the temporary lock in seconds. After this period, the account is automatically unlocked.	3600 (1 hour)

INFO

Temporary locking and permanent locking use the same failed attempt counter but operate independently. If both are enabled, make sure the permanent lock threshold is higher than the temporary lock threshold. Otherwise the account will be permanently locked before a temporary lock can take effect.

Example

With TemporaryLockThreshold = 3 and TemporaryLockDurationSeconds = 600:

1. The user fails 3 consecutive login attempts.
2. The account is temporarily locked for 10 minutes.
3. After 10 minutes, the user can attempt to log in again.
4. If the user then enters the correct password, the counter resets and the lock is cleared.

Progressive Login Throttling

Throttling introduces an artificial, progressively increasing delay before each login response. The delay grows exponentially with the number of consecutive failed attempts, making automated brute force attacks impractical while keeping the impact on legitimate users minimal.

Configuration

Option	Description	Default
ThrottlingEnabled	Enable or disable progressive login throttling.	false
ThrottlingBaseDelayMs	Base delay in milliseconds applied after the first failed login attempt.	1000
ThrottlingMaxDelayMs	Maximum delay cap in milliseconds. The delay will never exceed this value.	30000

Delay Formula

The delay for each failed attempt is calculated using exponential backoff:

$$\text{delay} = \min!\bigl(\text{BaseDelayMs} \times 2^{(\text{failedAttempts} - 1)},; \text{MaxDelayMs}\bigr)$$

A successful login resets the failed attempt counter and the delay returns to zero.

Example Delay Progression

With ThrottlingBaseDelayMs = 1000 and ThrottlingMaxDelayMs = 30000:

Failed Attempts	Delay
1	1,000 ms (1 s)
2	2,000 ms (2 s)
3	4,000 ms (4 s)
4	8,000 ms (8 s)
5	16,000 ms (16 s)
6+	30,000 ms (30 s, capped)

TIP

Throttling is the least disruptive protection mechanism. It does not prevent correct passwords from succeeding, it only adds a delay. This makes it a good default choice that can be combined with the other mechanisms.

Combining Mechanisms

All three protection mechanisms can be enabled at the same time for defense in depth. They are evaluated in the following order:

1. Temporary lock — if active, the request is rejected immediately without checking credentials.
2. Throttling — an artificial delay is applied before the credential check.
3. Credential check — password validation is performed.
4. Counter update — on failure, the failed attempt counter increments.
5. Lock evaluation — permanent and temporary lock thresholds are evaluated against the updated counter.

Recommended Configuration for Combined Use

When using all three mechanisms together, configure the thresholds so they take effect in the desired order:

Mechanism	Recommended Threshold
Throttling	enabled (base: 1000 ms, max: 30000 ms)
Temporary Lock	threshold: 5 attempts, duration: 300 seconds
Permanent Lock	threshold: 10 attempts

This ensures:

• Attempts 1–4: progressively increasing delays slow down attackers
• Attempt 5: temporary lock engages, blocking all attempts for 5 minutes
• After unlock: if the user continues to fail, delays resume
• Attempt 10: permanent lock engages, requiring admin intervention

INFO

The failed attempt counter is shared across all three mechanisms. A successful login at any point resets the counter and clears any active temporary lock.

Lock Message Behavior

By default, when a user submits the correct password while the account is locked, ProAuth shows a specific error message indicating the lock state ("This account is locked out." for permanent locks, "This account is temporarily locked. Please try again later." for temporary locks). When the password is wrong, a generic "Invalid username or password." message is always returned regardless of the lock state.

In penetration-tested or high-security environments, showing a specific lock message after a correct password can be considered a side-channel — it reveals that the attacker guessed the correct password. To mitigate this, the InformAboutLockAfterSuccessfulLogin option can be set to false. When disabled, ProAuth returns the generic error message for both correct and incorrect passwords while the account is locked.

Option	Description	Default
InformAboutLockAfterSuccessfulLogin	When true, shows specific lock messages after a successful credential check on a locked account. When false, returns the generic "Invalid username or password" message in all cases.	true

TIP

For internal or enterprise deployments where users need to understand why they cannot log in, keep the default (true). For public-facing or pentest-hardened deployments, set this option to false.

Configuration via Management API

Brute force protection options are configured as UserStore IDP instance options through the Management API. Options are set per IDP instance using the standard option endpoint:

PUT /api/v1/options
Content-Type: application/json

{
  "name": "ThrottlingEnabled",
  "value": "true",
  "applyToIdpInstanceId": "<idp-instance-id>"
}

All brute force protection options follow the same pattern. Replace name and value accordingly:

Option Name	Type	Example Value
AttemptsBeforeUserLocked	integer	10
TemporaryLockEnabled	boolean	true
TemporaryLockThreshold	integer	5
TemporaryLockDurationSeconds	integer	3600
ThrottlingEnabled	boolean	true
ThrottlingBaseDelayMs	integer	1000
ThrottlingMaxDelayMs	integer	30000
InformAboutLockAfterSuccessfulLogin	boolean	true

Infrastructure Rate Limiting

ProAuth's brute force protection operates at the application level and tracks failed attempts per user account. This is the primary security mechanism and should always be enabled.

Infrastructure-level rate limiting at your reverse proxy or load balancer provides an additional layer for protecting system resources:

Why Per-User Protection is Primary

ProAuth tracks failed attempts per username, not per IP or session:

• Protection applies regardless of the client's network origin
• Effective for users behind shared IPs (corporate NAT, VPNs, mobile carriers)
• Consistent enforcement across load-balanced deployments

Infrastructure rate limiting complements this by protecting system resources (CPU, connections, bandwidth) from high-volume attacks.

Recommended Infrastructure Measures

Layer	Mechanism	Purpose
CDN / WAF	IP reputation and anomaly detection	Block known malicious sources
Reverse Proxy	Connection rate limiting	Prevent resource exhaustion
Load Balancer	Connection limits	Protect backend capacity

Example: NGINX Rate Limiting

http {
    limit_req_zone $binary_remote_addr zone=login:10m rate=10r/s;

    server {
        location /signin {
            limit_req zone=login burst=20 nodelay;
            proxy_pass http://proauth;
        }
    }
}

TIP

Infrastructure rate limiting protects system resources. ProAuth's per-user mechanisms protect individual accounts. Enable both for defense in depth.

Best Practices

Defense in Depth

Brute force protection is one layer of a comprehensive authentication security strategy. For robust protection, combine it with:

Measure	Purpose
Strong password policies	Reduce effectiveness of dictionary attacks
Multi-factor authentication	Require additional verification beyond passwords
Password breach detection	Prevent use of compromised credentials
Security monitoring (SIEM)	Detect and respond to attack patterns

Recommended Configuration

For most deployments, enable all three mechanisms with the following configuration:

Option	Recommended Value	Rationale
ThrottlingEnabled	true	Low-impact baseline protection
ThrottlingBaseDelayMs	1000	Noticeable delay without impacting legitimate users
ThrottlingMaxDelayMs	30000	Caps delay at 30 seconds
TemporaryLockEnabled	true	Auto-recovers without admin intervention
TemporaryLockThreshold	5 to 10	Balance between security and usability
TemporaryLockDurationSeconds	300 to 900	5–15 minutes deters automated attacks
AttemptsBeforeUserLocked	15 to 20 (or disabled)	Only for high-security environments
InformAboutLockAfterSuccessfulLogin	false	Recommended for public-facing deployments

High-Security Environments

For deployments requiring stricter controls:

• Enable permanent locking with administrator notification
• Set InformAboutLockAfterSuccessfulLogin to false
• Require multi-factor authentication for all users
• Integrate with a SIEM for real-time alerting
• Enable CAPTCHA protection for public-facing login pages

Distributed Deployments

ProAuth stores protection state in the database, ensuring consistent enforcement across all instances in a load-balanced deployment. No additional configuration is required for clustered environments.

Monitoring and Alerting

ProAuth exposes OpenTelemetry metrics for security events:

Metric	Description
userstore_temporary_lock_total	Temporary locks applied
userstore_permanent_lock_total	Permanent locks applied

Configure alerts for elevated lock rates, which may indicate an attack in progress or misconfigured thresholds affecting legitimate users.

Configure your monitoring system (Prometheus, Azure Monitor, Datadog, etc.) to alert on:

• Sudden spikes in lock events (possible attack in progress)
• Sustained elevated lock rates (credential stuffing campaign)
• Locks on privileged accounts (admin, service accounts)

CAPTCHA Protection

In addition to throttling and locking, ProAuth supports CAPTCHA challenges to distinguish human users from automated bots. CAPTCHA provides an additional layer of protection against credential stuffing and brute force attacks, particularly effective for public-facing login pages.

Supported Providers

ProAuth integrates with three privacy-focused CAPTCHA providers. All providers are GDPR-compliant and do not use invasive tracking.

Provider	Description	Documentation
Cloudflare Turnstile	Free, privacy-focused, invisible challenges. Default provider.	developers.cloudflare.com/turnstile
hCaptcha	Privacy-focused alternative to reCAPTCHA, supports accessibility.	docs.hcaptcha.com
Friendly Captcha	EU-based, proof-of-work based, no cookies required.	docs.friendlycaptcha.com

Recommended Provider

Cloudflare Turnstile is the recommended CAPTCHA provider. It is free, fully compatible with ProAuth's default security headers, and requires no additional configuration beyond the site key and secret key.

Cross-Origin-Embedder-Policy Override Required

hCaptcha and Friendly Captcha require cross-origin resources that are blocked by ProAuth's default Cross-Origin-Embedder-Policy: require-corp header. To use these providers, set the CrossOriginEmbedderPolicy base service setting to UnsafeNone:

"BaseServiceSettings": {
  "CrossOriginEmbedderPolicy": "UnsafeNone"
}

Or via Helm values:

appsettings:
  baseservicesettings:
    crossoriginembedderpolicy: "UnsafeNone"

This relaxation is safe because ProAuth applies other security headers (Content-Security-Policy, X-Frame-Options, Cross-Origin-Opener-Policy, Cross-Origin-Resource-Policy) that prevent framing and cross-origin attacks. The strict require-corp default is retained because it provides defense-in-depth for deployments that use Turnstile or do not use CAPTCHA.

INFO

Google reCAPTCHA is intentionally not supported due to privacy concerns. The supported providers offer comparable bot detection while respecting user privacy.

Activation Modes

CAPTCHA can be configured with three activation modes to balance security and user experience:

Mode	Description
Disabled	CAPTCHA is never shown. This is the default.
Always	CAPTCHA is required on every login attempt.
AfterFailures	CAPTCHA is required only after a configured number of consecutive failed login attempts.

The AfterFailures mode provides a good balance — legitimate users entering correct credentials are not challenged, while repeated failures trigger CAPTCHA to stop automated attacks.

Configuration

CAPTCHA is configured per UserStore IDP instance. You must first register with your chosen CAPTCHA provider to obtain a site key and secret key.

Option	Description	Default
CaptchaActivationMode	When CAPTCHA is required: Disabled, Always, or AfterFailures.	Disabled
CaptchaFailureThreshold	Number of consecutive failed login attempts before CAPTCHA is required (only applies when mode is AfterFailures).	3
CaptchaProvider	CAPTCHA provider to use: Turnstile, HCaptcha, or FriendlyCaptcha.	Turnstile
CaptchaSiteKey	Public site key from your CAPTCHA provider. Displayed in the browser.	—
CaptchaSecretKey	Secret key for server-side verification. Keep this confidential.	—

Configuration via Management API

CAPTCHA options are configured as UserStore IDP instance options through the Management API:

PUT /api/v1/options
Content-Type: application/json

{
  "name": "CaptchaActivationMode",
  "value": "AfterFailures",
  "applyToIdpInstanceId": "<idp-instance-id>"
}

Configure all required options:

Option Name	Type	Example Value
CaptchaActivationMode	string	AfterFailures
CaptchaFailureThreshold	integer	3
CaptchaProvider	string	Turnstile
CaptchaSiteKey	string	0x4AAA...
CaptchaSecretKey	string	0x4AAA...

WARNING

The CaptchaSecretKey is sensitive and must be kept confidential. Store it securely and avoid logging or exposing it in client-side code.

Provider Setup

Cloudflare Turnstile

1. Sign up at dash.cloudflare.com and navigate to Turnstile
2. Add a new site and configure your domain
3. Choose widget mode: Managed (recommended), Non-interactive, or Invisible
4. Copy the Site Key and Secret Key to ProAuth configuration

hCaptcha

1. Sign up at dashboard.hcaptcha.com
2. Add a new site and configure your domain
3. Copy the Site Key and Secret Key to ProAuth configuration
4. Optionally enable Enterprise features for passive detection

Friendly Captcha

1. Sign up at friendlycaptcha.com
2. Create an application and configure your domain
3. Copy the Site Key and API Key to ProAuth configuration

Integration with Other Protections

CAPTCHA operates alongside the other brute force protection mechanisms. The evaluation order is:

1. Temporary lock — if active, reject immediately
2. CAPTCHA — if required based on activation mode, verify challenge
3. Throttling — apply progressive delay
4. Credential check — validate password
5. Counter update and lock evaluation — update failed attempts, check lock thresholds

TIP

For maximum protection, enable CAPTCHA in AfterFailures mode (threshold 2–3) combined with throttling and temporary locking. This provides layered defense: CAPTCHA stops bots, throttling slows attackers, and locking halts persistent attacks.

Recommended Configuration

Scenario	CaptchaActivationMode	CaptchaFailureThreshold
Internal enterprise application	Disabled	—
Public-facing application	AfterFailures	3
High-security or under attack	Always	—

INFO

The AfterFailures mode tracks failed attempts per user account. An attacker targeting multiple accounts will trigger CAPTCHA on each account individually after the threshold is reached.