# Protecting user registration

> **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).

Sign-up forms are abused to create accounts in bulk: for spam, promotion and trial abuse, resale, or as a base for later attacks. This page sets up a stricter widget policy for the sign-up form, classifies the email address and profile fields when the widget verifies, and shows backend code that turns the signed result into an account decision.

Prerequisites: a running Sentinel with an active license, widget 3.7.0 or later on the sign-up page (3.6.0 for the **Strict** preset, 3.7.0 to send `type="email"` inputs), and an admin user who can edit security groups and API keys. See [Get started](/docs/sentinel/v2/get-started/).

## What you're defending against

| Threat | What stops it |
| --- | --- |
| Scripted sign-ups at volume | Proof-of-work, tight rate limits per device and IP, and [Human Interaction Signature](/docs/sentinel/v2/features/human-interaction-signature/) (HIS), which blocks clients that don't behave like a person. |
| Sign-ups from data centers, proxies and Tor | A code challenge and a harder proof-of-work for `hosting` networks and risky IPs, from the first request. |
| Disposable and fake email addresses | The email rules `DISPOSABLE`, `MX` and `PRIVACY_RELAY`, signed into `verificationData`. |
| Many accounts from one device | The [EDK](/docs/sentinel/v2/reference/glossary/) (`device.edk`), a daily device key your backend can count sign-ups by. |
| Spam and injection in profile fields | The text and injection rules on the fields the widget sends. |
| Clients that keep failing | The client's penalty rises with each failure; from `8`, the **Strict** preset denies it until the penalty expires. |

The email address and profile fields reach Sentinel only with `POST /v2/verify`, after the challenge was issued. Security-group rules decide who gets which challenge; decisions about the email address happen in your backend, from `verificationData`.

## Recommended configuration

### Security group for the sign-up form

Create a `public` security group for the sign-up form, separate from your other forms, and apply these presets from **Templates**:

| Preset | Kind | Why |
| --- | --- | --- |
| [Strict](/docs/sentinel/v2/policies/presets/#strict) | Base | Rate limits of `30/10m` per device and `300/1h` per IP, HIS in `relaxed` mode (`strict` for high risk), challenges that expire after `5m`, a code challenge for `hosting` networks and risky clients, and a deny gate at penalty `8`. |
| [Form fields (consumer sign-ups)](/docs/sentinel/v2/policies/presets/#form-fields) | Add-on | Sends the form's fields to `/v2/verify`, and stops scoring free and privacy-relay email providers, which most consumers use. For a B2B product where a free address is itself a signal, apply **Form fields** instead. |
| [Shared IPs](/docs/sentinel/v2/policies/presets/#shared-ips) | Add-on, optional | Raises the header-entropy limit on mobile networks, where many users share one IP. |

Optionally, add a gate of your own that refuses sign-ups over Tor. Like the preset's `threats` rule, it lets a visitor who already holds a challenge submit it:

```json
{
"name": "signup-no-tor",
"action": "deny",
"message": "Sign-up isn't available over Tor.",
"conditions": [
{ "field": "network", "operator": "=", "value": ["tor"] },
{ "field": "path", "operator": "!=", "value": ["/v2/verify"] }
]
}
```

Put it before the base preset, so a denied request doesn't reach its `set` rules. The group then runs:

```text
signup-no-tor
preset:forms-consumer:classifier
preset:strict:gate
preset:strict:threats
preset:strict:base
preset:strict:elevated
preset:strict:high
preset:shared-ip:mobile
```

<Callout type="warning" title="Strict needs widget 3.6.0">

HIS in `relaxed` and `strict` mode blocks widgets that don't send interaction data, and `his.codeChallenge` needs widget 3.6.0 or later. Upgrade every page that uses the key before you apply **Strict**. See [Presets: Strict](/docs/sentinel/v2/policies/presets/#strict).

### API keys

| Key | Group | Used by |
| --- | --- | --- |
| `public` | The sign-up group above, with **Request logging** set to **Verification** | The widget on the sign-up page |
| `restricted` | A backend group with the [Backend API (allowed IPs)](/docs/sentinel/v2/policies/presets/#backend-api-allowed-ips) preset | Your backend: `POST /v2/verify/signature`, `POST /v2/threat/_report` |

The country and network conditions of **Strict** need an [IP resolver](/docs/sentinel/v2/configure/ip-resolvers/). Without one, `network = hosting` never matches and `risk` sees only the device and threat-list signals.

## Integration steps

### Step 1 — Add the widget to the sign-up form

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

```html
<form action="/signup" method="post">
<input type="text" name="name" autocomplete="name" required />
<input type="email" name="email" autocomplete="email" required />
<input type="password" name="password" autocomplete="new-password" required />
<altcha-widget
challenge="https://sentinel.example.com/v2/challenge?apiKey=key_…&params.formId=signup"
></altcha-widget>
<button type="submit">Create account</button>
</form>
```

The widget sends the values of text inputs, email inputs and textareas to `/v2/verify`, but never password fields. Widgets before 3.7.0 don't send `type="email"` inputs; with those, make the email input `type="text" inputmode="email"` so that Sentinel receives the address. Mark fields that aren't prose, such as a phone number, with `data-no-spamfilter`. See [Which fields the widget sends](/docs/sentinel/v2/integrate/widget/#which-fields-the-widget-sends).

### Step 2 — Verify the payload and decide

Verify the payload before you create the account, then map the classification to an account decision. This Express handler uses `altcha-lib` 2.9.0 or later and a Redis client to count sign-ups per device:

```ts
import { verifyFieldsHash, verifyServer } from 'altcha-lib';
import express from 'express';
import { createClient } from 'redis';

const redis = await createClient({ url: process.env.REDIS_URL }).connect();
const app = express();
app.use(express.urlencoded({ extended: false }));

app.post('/signup', async (req, res) => {
const result = await verifyServer({
payload: req.body.altcha,
url: 'https://sentinel.example.com/v2/verify/signature',
apiKey: { id: 'key_…', secret: process.env.SENTINEL_API_KEY_SECRET! }, // restricted key
});
const data = result.verified ? result.verificationData : null;
if (
!data ||
data['params.formId'] !== 'signup' ||
!data.fields ||
!(await verifyFieldsHash({ formData: req.body, fields: data.fields, fieldsHash: String(data.fieldsHash) }))
) {
res.status(400).send('Verification failed. Please try again.');
return;
}

const reasons = data.reasons ?? [];
if (data.classification === 'BAD') {
res.status(422).send('We could not create your account.');
return;
}
if (reasons.includes('DISPOSABLE') || reasons.includes('MX')) {
res.status(422).send('Please use a permanent email address.');
return;
}

// Sign-ups per device today. The EDK rotates daily and is shared by people with the same
// IP, browser and language, so use a generous limit.
const edkKey = `signups:${data['device.edk']}`;
const signupsFromDevice = await redis.incr(edkKey);
await redis.expire(edkKey, 86400);

const user = await createUser(req.body, {
signupIp: data.ipAddress,                                   // for abuse reports later
needsReview: data.classification === 'NEUTRAL' || signupsFromDevice > 3,
}); // your code
await sendConfirmationEmail(user); // your code
res.redirect('/welcome');
});

app.listen(8080);
```

- **`DISPOSABLE` and `MX`.** A disposable domain or one without an MX record rarely belongs to a real customer. `MX` also triggers when Sentinel's DNS resolver fails, so check the host's resolver if it fires on known-good domains. See [Classifier](/docs/sentinel/v2/features/classifier/#limitations).
- **`NEUTRAL` isn't a rejection.** Create the account, but hold back what abusers want from it, such as trial credits, outgoing messages or invitations, until the email is confirmed or someone reviews it.
- **Don't explain rejections in detail.** A generic message gives a bot operator less to tune against.

See [Verifying submissions](/docs/sentinel/v2/integrate/verification/) for the full list of `verificationData` fields.

### Step 3 — Report abusive accounts

When you later ban an account for abuse, report the IP it signed up from. The report that reaches your `limit` gives the IP an automatic threat entry with the action `block`. Threat entries apply to every account, so the `threats` rule of **Strict**, and of every other widget base preset, then denies the IP in each group that has it:

```bash
curl -X POST https://sentinel.example.com/v2/threat/_report \
-u 'key_…:sec_…' \
-H 'Content-Type: application/json' \
-d '{"ip": "89.160.20.128", "limit": "3/24h", "kind": "bot", "reason": "Fake account banned"}'
```

```json
{ "data": { "action": null, "limitExceeded": false, "entryExists": false } }
```

The entry expires after `48h` by default (`expire` in the report changes it). Report only IPs your own systems confirmed as abusive: a shared mobile or office IP carries the reputation of everyone behind it. See [Report abuse](/docs/sentinel/v2/features/threat-intelligence/#report-abuse).

## Monitoring & tuning

- **Apply Strict in monitor mode first.** Its `gate` and `elevated` rules can deny or challenge legitimate users behind shared IPs. Check **Apply in monitor mode**, watch the group's **Activity** tab, then go live. See [Monitor mode](/docs/sentinel/v2/policies/presets/#monitor-mode).
- **Watch failed verifications.** In **Logs**, filter the sign-up key by **Result**. Many `HIS_BLOCKED`, `INCORRECT_CODE` or `TOO_FAST` errors from real users mean the escalation is too aggressive for your audience: switch to **Recommended**, or lower **Strict**'s HIS to `monitor` with the [HIS](/docs/sentinel/v2/policies/presets/#his) add-on. See [Request logs & analytics](/docs/sentinel/v2/operations/request-logs/).
- **Track the code-challenge share.** The `protectionLevel` breakdown of `POST /v2/request-logs/_stats` shows how many sign-ups had to type a code.
- **Tune the email rules.** If many genuine users trip a rule, add it to `classifier.disableRules` in a rule after the presets, and repeat `FREE_PROVIDER PRIVACY_RELAY` there: a later `classifier.disableRules` replaces the add-on's list.
- **Alert on attacks.** The `verification_failures` alert fires when failed verifications rise well above the account's baseline. During an ongoing sign-up attack, switch the base preset to [Lockdown](/docs/sentinel/v2/policies/presets/#lockdown) and back afterward.

## Related

- [Protecting login & authentication](/docs/sentinel/v2/use-cases/login/)
- [Protecting contact & lead forms](/docs/sentinel/v2/use-cases/forms/)
- [Security presets](/docs/sentinel/v2/policies/presets/)
- [Human Interaction Signature](/docs/sentinel/v2/features/human-interaction-signature/)
- [Scores, risk & penalty](/docs/sentinel/v2/concepts/scoring/)
- [Threat intelligence](/docs/sentinel/v2/features/threat-intelligence/)
