# Brute force attack preventions

Type of document: Reference
Product: F5 WAF for NGINX

---


This topic describes how to configure brute force attack prevention in F5 WAF for NGINX.

Brute force attacks try many combinations of usernames and passwords to access a protected application. To detect these attacks, F5 WAF for NGINX tracks failed login attempts for configured login pages.

When a threshold is reached, the policy can log the attack, challenge the client with client-side integrity, or challenge the client with CAPTCHA.

## User-defined URLs

To protect a login endpoint, define it as a user-defined URL.

```json
"urls": [
  {
    "method": "*",
    "name": "/html_login",
    "protocol": "http",
    "type": "explicit"
  }
],
```

## Login pages

A login page identifies the endpoint that users submit credentials to. It also defines how F5 WAF for NGINX determines whether a login attempt succeeded or failed.

The `accessValidation` object is required for brute force protection. You can use fields such as `responseContains`, `responseOmits`, or HTTP status checks to classify the login result.

```json
"login-pages": [
  {
    "accessValidation": {
      "responseContains": "Success"
    },
    "authenticationType": "form",
    "url": {
      "method": "*",
      "name": "/html_login",
      "protocol": "http",
      "type": "explicit"
    },
    "usernameParameterName": "username",
    "passwordParameterName": "password"
  }
]
```

**Note:** 

For more information, see the [login-pages section](/waf/policies/parameter-reference.md#policy/login-pages) of the parameter reference.

## Mitigation actions

Use the following action values for `loginAttemptsFromTheSameUser`, `loginAttemptsFromTheSameIp`, and `loginAttemptsFromTheSameDeviceId`:

- `alarm` logs the brute force event and allows the request.
- `alarm-and-client-side-integrity` serves a JavaScript challenge to verify that the client behaves like a browser.
- `alarm-and-captcha` serves a CAPTCHA challenge to verify that the client is operated by a human user. This action requires a generated challenge pool.

## Configure brute force challenges

1. Define the login endpoint in `urls`.
2. Add the same endpoint to `login-pages`.
3. Configure `accessValidation` so F5 WAF for NGINX can classify successful and failed logins.
4. With `bruteForceProtectionForAllLoginPages`, decide whether the brute force settings apply to all login pages or only one page.
5. Set thresholds for `loginAttemptsFromTheSameUser`, `loginAttemptsFromTheSameIp`, or `loginAttemptsFromTheSameDeviceId`, depending on how you want to track failed login activity.
6. Choose a mitigation action: `alarm`, `alarm-and-client-side-integrity`, or `alarm-and-captcha`.
7. Tune the timing fields for detection, mitigation, and re-enable behavior.
8. If needed, configure bypass behavior for the selected challenge type.

## Client-side integrity example

The following example applies client-side integrity to all configured login pages.

```json
{
  "policy": {
    "brute-force-attack-preventions": [
      {
        "bruteForceProtectionForAllLoginPages": true,
        "loginAttemptsFromTheSameIp": {
          "action": "alarm-and-client-side-integrity",
          "enabled": true,
          "threshold": 3
        },
        "loginAttemptsFromTheSameUser": {
          "action": "alarm-and-client-side-integrity",
          "enabled": true,
          "threshold": 3
        },
        "clientSideIntegrityBypassCriteria": {
          "action": "alarm-and-captcha",
          "enabled": false,
          "threshold": 1
        },
        "measurementPeriod": 60,
        "preventionDuration": 60,
        "reEnableLoginAfter": 60,
        "sourceBasedProtectionDetectionPeriod": 60
      }
    ]
  }
}
```

In this example:

- `loginAttemptsFromTheSameUser` challenges repeated failures for the same username.
- `loginAttemptsFromTheSameIp` challenges repeated failures from the same source IP address.

## CAPTCHA example

The following example protects a specific login page with CAPTCHA.

```json
{
  "policy": {
    "brute-force-attack-preventions": [
      {
        "bruteForceProtectionForAllLoginPages": false,
        "url": {
          "method": "*",
          "name": "/html_login",
          "protocol": "http"
        },
        "loginAttemptsFromTheSameIp": {
          "action": "alarm-and-captcha",
          "enabled": true,
          "threshold": 3
        },
        "loginAttemptsFromTheSameUser": {
          "action": "alarm-and-captcha",
          "enabled": true,
          "threshold": 3
        },
        "captchaBypassCriteria": {
          "action": "alarm-and-drop",
          "enabled": false,
          "threshold": 5
        },
        "measurementPeriod": 60,
        "preventionDuration": 60,
        "reEnableLoginAfter": 60,
        "sourceBasedProtectionDetectionPeriod": 60
      }
    ]
  }
}
```

To protect browser login pages with human verification, use the CAPTCHA example in [section name]. This option replaces a client-side integrity challenge.

**Note:** 

CAPTCHA actions have two requirements:

- Make a challenge pool available when you compile your policy. Otherwise, the bundle contains no challenges.
- If your virtual server serves plain HTTP, set `secureAttribute` to `never`. If you don't, the browser discards the enforcer state cookie, and the client can't pass the challenge.

For more information, see [Cookie enforcement](/waf/policies/cookie-enforcement.md).

## Device ID examples

Use the following examples to track failed logins by device identifier instead of username or source IP address:

### Client-side integrity

```json
{
  "policy": {
    "brute-force-attack-preventions": [
      {
        "bruteForceProtectionForAllLoginPages": false,
        "url": {
          "method": "*",
          "name": "/html_login",
          "protocol": "http"
        },
        "loginAttemptsFromTheSameDeviceId": {
          "action": "alarm-and-client-side-integrity",
          "enabled": true,
          "threshold": 3
        },
        "measurementPeriod": 60,
        "preventionDuration": 60,
        "reEnableLoginAfter": 60,
        "sourceBasedProtectionDetectionPeriod": 60
      }
    ]
  }
}
```

### CAPTCHA

```json
{
  "policy": {
    "brute-force-attack-preventions": [
      {
        "bruteForceProtectionForAllLoginPages": false,
        "url": {
          "method": "*",
          "name": "/html_login",
          "protocol": "http"
        },
        "loginAttemptsFromTheSameDeviceId": {
          "action": "alarm-and-captcha",
          "enabled": true,
          "threshold": 3
        },
        "measurementPeriod": 60,
        "preventionDuration": 60,
        "reEnableLoginAfter": 60,
        "sourceBasedProtectionDetectionPeriod": 60
      }
    ]
  }
}
```

When the brute-force configuration applies to one login page, set `url`. If `bruteForceProtectionForAllLoginPages` is set to `true`, omit `url`.

## More information

**Note:** 

For more information, see the [brute-force-attack-preventions section](/waf/policies/parameter-reference.md#policy/brute-force-attack-preventions) of the parameter reference.