Auth0

Auth0 esegue una Action prima di creare un utente che si registra con una password o con un codice passwordless (una connessione Database o Passwordless), e quella Action può chiamare Bot Protection e rifiutare la registrazione. La pagina di registrazione è di Auth0, sul dominio di Auth0, quindi la Action non ha il cookie _kz: la decisione si basa sull'IP e sullo User-Agent.

Il tag

Metti il tag sulle tue pagine, quelle dove le persone arrivano prima di registrarsi e dove fanno login e pagano, così quelle decisioni hanno il token:

<script src="https://korzen.dev/v1/tag.js" data-site-key="YOUR_SITE_KEY" async></script>

La chiamata

La Action. Auth0 le concede 20 secondi in tutto; la chiamata rispetta il tuo timeout, e qualsiasi altro esito lascia passare la registrazione:

// Auth0 Dashboard: Actions, Triggers, pre-user-registration; a new Action.
// Add the secret KORZEN_API_KEY to the Action.
exports.onExecutePreUserRegistration = async (event, api) => {
  let d = null;
  try {
    const res = await fetch("https://korzen.dev/v1/decide", {
      method: "POST",
      headers: { Authorization: `Bearer ${event.secrets.KORZEN_API_KEY}`, "Content-Type": "application/json" },
      body: JSON.stringify({
        ip: event.request.ip,
        user_agent: event.request.user_agent,
        ja4: event.security_context?.ja4 || undefined, // behind Cloudflare only: left out without it
        headers: { "accept-language": event.request.language },
        path: "/signup",
        method: "POST",
      }),
      signal: AbortSignal.timeout(200),
    });
    if (res.ok) d = await res.json();
  } catch {} // fail open
  if (d?.action === "block") {
    api.access.deny("korzen_block", "We could not create your account.");
    return;
  }
  // "challenge": Auth0's own CAPTCHA or MFA, if your plan has them
  if (d?.request_id) api.user.setAppMetadata("korzen_request_id", d.request_id);
};

Auth0 dà all'Action la lingua e lo User-Agent del browser, ma nessuno degli altri header della richiesta, quindi la chiamata inoltra solo accept-language: qui mancano gli header che una build di browser invia uguali, che Bot Protection legge nelle chiamate del tuo server.

Su un tenant il cui traffico passa da Cloudflare (i piani Enterprise di Auth0), l'evento ha anche security_context.ja4: il JA4 dell'handshake TLS del visitatore con l'edge di Auth0, nella stessa forma che Bot Protection legge da Cloudflare davanti al tuo server. La chiamata lo invia come ja4 quando c'è; senza, il campo resta fuori.

L'IP del visitatore

event.request.ip è l'indirizzo che ha raggiunto Auth0, già quello del visitatore: non c'è niente da configurare. Su un dominio personalizzato dietro un tuo proxy, consulta le impostazioni del dominio personalizzato di Auth0 per l'IP del visitatore.

Le decisioni di Auth0 arrivano senza il token del tag. Quando Bot Protection ha già visto il tuo tag su altre pagine, un token mancante aggiunge un po' allo score (no_token), mai abbastanza per bot da solo.

Applica l'azione

Leggi solo action. Su block, rispondi con lo stesso errore che l'azione mostra quando fallisce per qualsiasi altro motivo, così il bot non impara niente. Su challenge, usa la verifica che hai già (un CAPTCHA, un codice via email o telefono); se non ne hai, prosegui. L'account parte in monitor mode, dove action è sempre allow: per i visitatori non cambia niente finché non attivi il block mode.

Conserva il request_id

Ogni risposta ha un request_id. Conservalo insieme a ciò che l'azione ha creato, in una colonna dell'account o dell'ordine, o in una riga di log con il loro id. Identifica quella decisione quando ci chiedi informazioni, e ti permette di scoprire in seguito quale risposta ha fatto entrare un account falso.

Provalo sulla tua macchina

Usa il tuo tenant di sviluppo. Nell'editor della Action, Test la esegue con un evento di esempio; poi registrati dalla tua pagina di login, e la decisione compare nella pagina Decisioni della dashboard sotto /signup. Verifica il fail-open con un secret KORZEN_API_KEY sbagliato: la registrazione va a buon fine.

Errori comuni

• Le registrazioni social. Google, GitHub e simili non eseguono il trigger pre-user-registration; una Action post-login può chiedere a Bot Protection di loro al primo login.
• Chiamare /v1/decide dal browser. L'API key arriverebbe a ogni visitatore; la chiamata va fatta dal tuo server.
• Nessun timeout, o un errore che blocca la registrazione. Qualsiasi risposta diversa da 200, o nessuna risposta in tempo, significa: lascia passare il visitatore.