Protecting user registration
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.
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 (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 (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 | 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) | 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 | 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:
{
"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:
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:mobileAPI 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) preset | Your backend: POST /v2/verify/signature, POST /v2/threat/_report |
The country and network conditions of Strict need an IP resolver. 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, and point it at Sentinel with the sign-up group's public key:
<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_…¶ms.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.
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:
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);DISPOSABLEandMX. A disposable domain or one without an MX record rarely belongs to a real customer.MXalso triggers when Sentinel's DNS resolver fails, so check the host's resolver if it fires on known-good domains. See Classifier.NEUTRALisn'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 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:
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"}'{ "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.
Monitoring & tuning
- Apply Strict in monitor mode first. Its
gateandelevatedrules 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. - Watch failed verifications. In Logs, filter the sign-up key by Result. Many
HIS_BLOCKED,INCORRECT_CODEorTOO_FASTerrors from real users mean the escalation is too aggressive for your audience: switch to Recommended, or lower Strict's HIS tomonitorwith the HIS add-on. See Request logs & analytics. - Track the code-challenge share. The
protectionLevelbreakdown ofPOST /v2/request-logs/_statsshows how many sign-ups had to type a code. - Tune the email rules. If many genuine users trip a rule, add it to
classifier.disableRulesin a rule after the presets, and repeatFREE_PROVIDER PRIVACY_RELAYthere: a laterclassifier.disableRulesreplaces the add-on's list. - Alert on attacks. The
verification_failuresalert fires when failed verifications rise well above the account's baseline. During an ongoing sign-up attack, switch the base preset to Lockdown and back afterward.