# Protecting login & authentication

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

Login forms are attacked with lists of leaked credentials, and a successful guess pays off directly, so they deserve stricter protection than a contact form. This page combines a strict widget policy with three backend checks: a signed widget verification, a per-account attempt limit, and a distance check against the account's last login location.

Prerequisites: a running Sentinel with an active license, widget 3.6.0 or later on the login page, and an admin user who can edit security groups and API keys. The location check also needs an [IP resolver](/docs/sentinel/v2/configure/ip-resolvers/) that returns coordinates.

## What you're defending against

| Threat | What stops it |
| --- | --- |
| Credential stuffing from scripts and headless browsers | Proof-of-work on every attempt, rate limits per device and IP, and [Human Interaction Signature](/docs/sentinel/v2/features/human-interaction-signature/) (HIS). |
| Attempts from data centers, proxies and Tor | A code challenge and a harder proof-of-work from the first request (`network = hosting`, `risk`, signals). |
| One client failing again and again | Each failed verification raises the client's penalty; from `8`, the **Strict** preset denies it. Your backend's reports of failed passwords add automatic threat entries. |
| Password spraying against one account from many IPs | A per-account attempt limit, which you check from your backend with the classifier's `rateLimit`. |
| A stolen password used from another region | `LOCATION_DISTANCE`: the distance from the account's last login location, so your backend can ask for a second factor. |

## Recommended configuration

### Security group for the login form

Create a `public` security group for login forms and apply the [Strict](/docs/sentinel/v2/policies/presets/#strict) base preset from **Templates**. Leave out the **Form fields** add-on: the widget would only send the username, which tells the text rules nothing.

**Strict** writes these rules:

| Rule | Effect |
| --- | --- |
| `preset:strict:gate` | Denies clients with a penalty of `8` or more. |
| `preset:strict:threats` | Denies IPs with the threat verdict `block`, except on `/v2/verify`. |
| `preset:strict:base` | `30/10m` per device and `300/1h` per IP, HIS `relaxed`, challenges expire after `5m`. |
| `preset:strict:elevated` | A code challenge and a harder proof-of-work for `risk` ≥ 3, a penalty of `2` or more, `hosting` networks, or the `BOT`, `CLI`, `LIBRARY`, `MALICIOUS`, `PROXY` and `TOR` signals. |
| `preset:strict:high` | HIS `strict`, a longer code and the hardest proof-of-work for `risk` ≥ 6 or a penalty of `5` or more. |

Add [Trusted networks](/docs/sentinel/v2/policies/presets/#trusted-networks) in front if your support staff log in from a known office network and shouldn't be escalated. See [Presets: Strict](/docs/sentinel/v2/policies/presets/#strict) for the exact rules.

<Callout type="warning" title="Shared IPs and the penalty gate">

The penalty is kept per account and client IP. Behind a corporate NAT or a mobile carrier, one attacker's failures also escalate and, from penalty `8`, deny their neighbors until the penalty expires (`[penalty] ttl`, default `30m`). If your users often share IPs, raise the `gate` threshold or remove that rule, and test the preset in monitor mode first.

### Backend group

Your backend calls `POST /v2/verify/signature`, `POST /v2/classifier` and `POST /v2/threat/_report` with a `restricted` key. Put that key in a group with the [Backend API (allowed IPs)](/docs/sentinel/v2/policies/presets/#backend-api-allowed-ips) preset. Each login then makes two or three calls from your backend's IP, so raise the global per-IP limit above your peak login rate:

```toml
[rate_limit]
global = "3000/1m"   # per client IP; your backend's IP counts every login attempt 2–3 times
```

See [Backend & API protection](/docs/sentinel/v2/use-cases/api-protection/) and [`[rate_limit]`](/docs/sentinel/v2/reference/configuration/#rate_limit).

## Integration steps

### Step 1 — Add the widget to the login form

Install the widget in your page as described in [Widget integration](/docs/integration/widget/), and point it at Sentinel with the login group's `public` key:

```html
<form action="/login" method="post">
<input type="text" name="username" autocomplete="username" required />
<input type="password" name="password" autocomplete="current-password" required />
<altcha-widget
challenge="https://sentinel.example.com/v2/challenge?apiKey=key_…&params.formId=login"
></altcha-widget>
<button type="submit">Sign in</button>
</form>
```

### Step 2 — Check the attempt before the password

Run Sentinel's checks before you hash the password, so a refused attempt costs you nothing:

1. Verify the widget payload with `POST /v2/verify/signature`.
2. Call `POST /v2/classifier` with the visitor's IP and headers, a `rateLimit` keyed by the account, and the account's `lastKnownLocation`. One hit counts against the limit per call. Sentinel keeps the counter per API key, or per account with `rateLimit.scope` `account` (as in the Backend API preset), so every replica of your app shares it.

```ts
import { createHash } from 'node:crypto';
import { verifyServer } from 'altcha-lib';
import express from 'express';

const SENTINEL = 'https://sentinel.example.com';
const KEY_ID = 'key_…'; // restricted key
const KEY_SECRET = process.env.SENTINEL_API_KEY_SECRET!;
const BASIC = 'Basic ' + Buffer.from(`${KEY_ID}:${KEY_SECRET}`).toString('base64');

async function sentinel(path: string, body: unknown) {
const res = await fetch(SENTINEL + path, {
method: 'POST',
headers: { Authorization: BASIC, 'Content-Type': 'application/json' },
body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`Sentinel ${path}: ${res.status}`);
return (await res.json()).data;
}

const app = express();
app.set('trust proxy', 1); // req.ip is the visitor's IP behind your load balancer
app.use(express.urlencoded({ extended: false }));

app.post('/login', async (req, res) => {
const verification = await verifyServer({
payload: req.body.altcha,
url: `${SENTINEL}/v2/verify/signature`,
apiKey: { id: KEY_ID, secret: KEY_SECRET },
});
const v = verification.verified ? verification.verificationData : null;
if (!v || v['params.formId'] !== 'login' || v.classification === 'BAD') {
res.status(400).send('Verification failed. Please try again.');
return;
}

const username = String(req.body.username).trim().toLowerCase();
const user = await findUser(username); // your code; may be null
const check = await sentinel('/v2/classifier', {
ip: req.ip,
headers: {
  'user-agent': req.get('user-agent') ?? '',
  accept: req.get('accept') ?? '',
  'accept-language': req.get('accept-language') ?? '',
},
rateLimit: {
  limit: '5/15m,20/1d',
  // A hash keeps usernames out of Sentinel's KV store.
  customKey: 'login:' + createHash('sha256').update(username).digest('hex'),
},
lastKnownLocation: user?.lastLoginLocation ?? undefined, // { lat, lon }
});
if (check.rateLimit?.triggeredRules.includes('RATE_LIMIT')) {
res.status(429).send('Too many attempts for this account. Try again later.');
return;
}

if (!user || !(await checkPassword(user, req.body.password))) { // your code
await sentinel('/v2/threat/_report', {
  ip: req.ip,
  limit: '20/10m',
  kind: 'malicious',
  reason: 'Failed login',
});
res.status(401).send('Wrong username or password.');
return;
}

const distanceKm = check.location?.rules.LOCATION_DISTANCE.distanceKm ?? 0;
if (check.ip?.lat != null && check.ip?.lon != null) {
await saveLastLoginLocation(user, { lat: check.ip.lat, lon: check.ip.lon }); // your code
}
if (distanceKm >= 1000) {
await startSecondFactor(req, res, user); // your code: OTP, passkey or email link
return;
}
await startSession(req, res, user); // your code
});

app.listen(8080);
```

- **Per-account limit.** `5/15m,20/1d` allows 5 attempts per account in 15 minutes and 20 a day, successful ones included. The first exceeded limit makes the `RATE_LIMIT` rule score `10`, and `check.rateLimit` also returns `remainingPoints` and `resetInSec`. Limits use the `points/duration` syntax of [Rate limiting](/docs/sentinel/v2/features/rate-limiting/#limit-syntax).
- **Failed-password reports.** The 20th report for an IP within 10 minutes gives it an automatic `block` entry for `48h`. The **Strict** preset's `threats` rule then denies the IP on the login widget, and on every other widget group with that rule. See [Report abuse](/docs/sentinel/v2/features/threat-intelligence/#report-abuse).
- **Distance.** `LOCATION_DISTANCE.distanceKm` is the distance between the IP's coordinates and `lastKnownLocation`, or `null` when either is missing. Its rule score grows with the logarithm of the distance; the threshold of `1000` km above is yours to pick. Travel and VPNs cause real distances, so ask for a second factor rather than refusing the login.
- **Fail closed or open.** The `sentinel()` helper throws on an error response. Decide whether your login refuses attempts or skips these checks while Sentinel is unreachable, and catch accordingly.

See the [`POST /v2/classifier` API reference](/sentinel-api-docs-v2.html#tag/classifier/POST/v2/classifier) for the full response.

## Monitoring & tuning

- **Test Strict in monitor mode.** Apply it with **Apply in monitor mode** checked, and watch the group's **Activity** tab for how many attempts its `gate`, `elevated` and `high` rules would have denied or escalated. See [Monitor mode](/docs/sentinel/v2/policies/presets/#monitor-mode).
- **Watch verification errors.** With request logging on the login key, the `error` breakdown of `POST /v2/request-logs/_stats` counts `HIS_BLOCKED`, `INCORRECT_CODE`, `TOO_FAST` and `ACCESS_DENIED`. A rise during normal traffic means real users are caught; during an attack, it means the policy works.
- **Watch the per-account limit.** With request logging set to **All** on the backend key, each `POST /v2/classifier` call is logged with its `triggeredRules`. Filter on `RATE_LIMIT` to see which periods hit the limit.
- **Alert on attacks.** The `verification_failures` alert fires when failed verifications rise well above the account's baseline. During a sustained attack, switch the base preset to [Lockdown](/docs/sentinel/v2/policies/presets/#lockdown), and back when it ends. See [Alerts](/docs/sentinel/v2/operations/alerts/#rules).
- **Unblock a false positive.** A root user can set an automatic entry's action to `allow`, or delete it, under **Threat Intelligence → Entries**. See [Threat intelligence](/docs/sentinel/v2/features/threat-intelligence/#automatic-entries).

The `brute_force` and `user_brute_force` alerts watch sign-ins to Sentinel's own admin UI, not your application's logins.

## Related

- [Protecting user registration](/docs/sentinel/v2/use-cases/registration/)
- [Threat detection](/docs/sentinel/v2/use-cases/threat-detection/)
- [Security presets](/docs/sentinel/v2/policies/presets/)
- [Rate limiting & penalty](/docs/sentinel/v2/features/rate-limiting/)
- [Classifier](/docs/sentinel/v2/features/classifier/)
- [Verifying submissions](/docs/sentinel/v2/integrate/verification/)
