Installare le chiavi universali sulle pagine web

Una chiave Fraud Defense Universal aiuta a proteggere le applicazioni web e gli endpoint API da attacchi bot automatizzati, abuso di credenziali e attività fraudolente. Utilizzando una chiave universale, puoi implementare protezioni sul tuo sito web con l'intercettazione automatica delle richieste di rete (AutoExecute), l'esecuzione manuale di JavaScript o una combinazione di entrambi i metodi.

Prima di iniziare

  1. Prepara il tuo ambiente per Google Cloud Fraud Defense.

  2. Crea una chiave universale.

  3. Configura i domini per la tua chiave universale.

  4. Per visualizzare la colonna Stato per gli endpoint protetti nella consoleGoogle Cloud , assicurati di disporre dell'autorizzazione Cloud Monitoringmonitoring.timeSeries.list. Questa autorizzazione è inclusa nei ruoli Fraud Defense predefiniti: Amministratore reCAPTCHA Enterprise, Editor reCAPTCHA Enterprise e Visualizzatore reCAPTCHA Enterprise.

Installa le chiavi universali sul tuo sito web

Per installare la chiave universale e proteggere le tue pagine web, puoi utilizzare la configurazione AutoExecute, l'installazione manuale di JavaScript o entrambi i metodi insieme su endpoint diversi utilizzando la stessa chiave universale:

  • Configurazione di AutoExecute (consigliata): intercetta automaticamente le richieste di rete asincrone ai percorsi URL configurati e allega il token reCAPTCHA all'intestazione della richiesta.
  • Installazione manuale: utilizza chiamate grecaptcha.enterprise.execute() manuali o attributi dei pulsanti HTML. Puoi utilizzare questo metodo da solo o insieme ad AutoExecute per le richieste di rete non supportate da AutoExecute, per le richieste che richiedono il posizionamento di token personalizzati nel payload o durante le migrazioni incrementali ad AutoExecute.

Configura AutoExecute

AutoExecute può aiutarti a semplificare l'integrazione di JavaScript nel frontend intercettando le richieste di rete sulle tue pagine web ed eliminando le chiamate grecaptcha.enterprise.execute() manuali per ogni azione del frontend.

Come funziona AutoExecute

Lo script Fraud Defense si integra automaticamente con le azioni di rete definite nella configurazione della policy della chiave universale. Quando lo script rileva una richiesta di rete asincrona a un percorso configurato, intercetta la richiesta, attiva una valutazione del rischio e, potenzialmente, mostra un test CAPTCHA all'utente prima che la richiesta originale continui. Il token di risposta generato viene allegato automaticamente all'intestazione X-Recaptcha-Token nella richiesta.

API di rete supportate

AutoExecute intercetta solo le richieste di rete asincrone avviate dalle seguenti API (inclusi framework come AJAX che si basano su di esse):

Nome API Configurazione del timeout Esempio di implementazione
API Fetch Imposta i timeout utilizzando il controller AbortSignal. AbortSignal.timeout(n)
XMLHttpRequest Imposta i timeout utilizzando la proprietà nativa .timeout. xhr.timeout = n

Best practice per l'integrazione

  • Solo azioni attivate dall'utente: AutoExecute non supporta le risorse che vengono caricate automaticamente durante il caricamento pagina. Per evitare errori di integrazione, applica AutoExecute solo alle richieste attivate da interazioni esplicite dell'utente (ad esempio, il clic su un pulsante di accesso o di invio).
  • Previeni i timeout di latenza: i flussi di verifica di Fraud Defense possono occasionalmente causare ritardi di rete. Per evitare timeout lato client, configura sempre timeout espliciti delle richieste direttamente utilizzando i meccanismi elencati nella tabella.
  • Proteggi solo i percorsi sensibili: specifica protectedEndpoints solo per i percorsi sensibili e utilizza un nome significativo per l'interazione dell'utente nel parametro action. Evita di proteggere ogni endpoint, perché l'attivazione di Fraud Defense su ogni richiesta di backend può influire negativamente sulle prestazioni. Per ulteriori indicazioni, consulta Azioni.

Aggiungi il tag di script alle tue pagine web

Per caricare Fraud Defense sulla tua pagina web, aggiungi l'API JavaScript con la tua chiave universale all'interno dell'elemento <head></head> della tua pagina web:

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

Per impostazione predefinita, Fraud Defense utilizza la lingua del browser. Se vuoi specificare una lingua diversa, utilizza l'attributo hl=LANG nello script. Ad esempio, per utilizzare il francese, specifica quanto segue:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

Per scoprire le lingue supportate, consulta i codici lingua per Fraud Defense.

Configura gli endpoint protetti

Per configurare gli endpoint protetti per la chiave universale, seleziona una scheda:

Console

  1. Nella console Google Cloud , vai alla pagina Fraud Defense.

    Vai a Fraud Defense

  2. Nella barra degli strumenti della console, verifica che il progetto venga visualizzato nel selettore di risorse. In caso contrario, fai clic sul selettore di risorse e seleziona il progetto.

  3. Seleziona la scheda Chiavi.

    La scheda Chiavi ha due visualizzazioni: Schede e Tabella. Se il progetto contiene molte chiavi, è disponibile solo la visualizzazione Tabella.

  4. Nella sezione Chiavi reCAPTCHA, individua la chiave universale che vuoi configurare:

    • Nella visualizzazione Schede, fai clic su Dettagli chiave nella scheda della chiave.
    • Nella visualizzazione Tabella, fai clic sul nome della chiave.

  5. Nella pagina Dettagli chiave, fai clic sulla scheda Integrazione.

  6. Nel passaggio Aggiungi reCAPTCHA al tuo sito web, seleziona la scheda AutoExecute (consigliato).

    (Facoltativo) Per proteggere manualmente endpoint specifici, fai clic sulla scheda Manuale per visualizzare lo snippet di codice grecaptcha.enterprise.execute().

  7. Nella sezione Endpoint protetti, fai clic su Aggiungi endpoint per configurare ogni endpoint che vuoi proteggere:

    1. Nel campo Azione, inserisci un nome per l'interazione dell'utente. Ad esempio, login, register o add_to_cart. Per ulteriori indicazioni, consulta Azioni.
    2. Nel campo Percorso, inserisci il percorso dell'URL univoco o il pattern glob da intercettare. Ad esempio, /login_api, /register_api o /cart_api/add/*.
    3. (Facoltativo) Per aggiungere un altro endpoint, fai clic su Aggiungi endpoint.

  8. Fai clic su Salva per salvare gli endpoint protetti.

Dopo aver salvato la configurazione, la colonna Stato nella tabella Endpoint protetti indica se Fraud Defense ha ricevuto traffico per ogni azione nelle ultime 24 ore. L'aggiornamento dello stato del traffico può richiedere 10 minuti dopo che un endpoint riceve il traffico per la prima volta.

gcloud

Per esaminare la configurazione della policy attuale per la chiave universale, utilizza il comando gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

Per aggiornare la configurazione della policy con gli endpoint protetti, crea un file YAML (ad esempio POLICY.yaml) che definisca i percorsi e le azioni protetti:

clientSettings:
  allowedDomains:
    - example.com
  protectedEndpointGroup:
    protectedEndpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

Aggiorna la configurazione della chiave con il file YAML utilizzando il comando gcloud alpha recaptcha policies update:

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

API REST

Per aggiornare la configurazione della policy in modo da definire gli endpoint protetti utilizzando l'API REST, utilizza il metodo projects.keys.updatePolicy.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

  • PROJECT_ID: il tuo ID progetto Google Cloud
  • KEY_ID: l'ID della chiave universale

Metodo HTTP e URL: 

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings

Corpo JSON della richiesta: 

{
"clientSettings": {
  "allowedDomains": [
    "example.com"
  ],
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

Per inviare la richiesta, espandi una di queste opzioni:

Se l'operazione ha esito positivo, la richiesta restituisce la configurazione della policy aggiornata.

Sintassi e limiti degli endpoint protetti

Puoi configurare fino a 25 endpoint protetti per chiave universale. Ogni endpoint deve soddisfare i seguenti requisiti:

  • action: il nome dell'azione deve contenere da 1 a 100 caratteri e utilizzare solo lettere, numeri, barre (/) e trattini bassi (_).
  • path (sensibile alle maiuscole): il percorso deve soddisfare i seguenti criteri:
    • Essere univoco, iniziare con / e contenere da 1 a 200 caratteri senza barre consecutive (//).
    • Includi almeno un segmento che non sia un carattere jolly. Ad esempio, non può essere /, /*, /** o /*/.
    • I caratteri jolly devono occupare segmenti completi: * corrisponde a un singolo segmento. Ad esempio, /api/*/login o /api/* sono validi; /api/login* non è valido e ** corrisponde a più segmenti solo come segmento finale. Ad esempio, /api/** è valido, mentre /api/**/login non lo è.

Comportamento di corrispondenza del percorso

AutoExecute valuta gli endpoint protetti in sequenza dall'alto verso il basso solo in base al percorso dell'URL. Ignora il dominio, lo schema e parametri di ricerca di destinazione. Questo comportamento ha le seguenti implicazioni pratiche:

  • Ordine di corrispondenza dei percorsi: AutoExecute applica il primo endpoint corrispondente. Se nessun endpoint corrisponde, AutoExecute non intercetta la richiesta. Posiziona i percorsi specifici prima dei pattern con caratteri jolly per evitare di oscurare route più specifiche. Ad esempio, elenca /mysite/login prima di /*/login.
  • Richieste di terze parti: se gli strumenti di terze parti in esecuzione sulla tua pagina (come script di analisi o di partner) inviano richieste a percorsi che corrispondono ai tuoi endpoint protetti (ad esempio, https://analytics.example.net/login corrispondente a /login), AutoExecute intercetta anche queste richieste. Ciò può causare una latenza di rete aggiuntiva, metriche distorte o verifiche CAPTCHA impreviste. Per evitare conflitti, assicurati che i percorsi protetti siano distintivi (ad esempio, /auth/v1/login) o utilizza l'installazione manuale se si verificano collisioni di percorsi.
  • API cross-domain: se l'API di backend è ospitata su un dominio diverso da quello del tuo sito web (ad esempio, cdn.example.com rispetto a www.example.com), AutoExecute funziona automaticamente senza configurazione aggiuntiva del dominio.

Se la corrispondenza con domini di destinazione specifici è importante per la tua integrazione, invia una richiesta di funzionalità.

Verifica i token nel tuo backend

Nel backend, recupera il token di risposta dall'intestazione della richiesta X-Recaptcha-Token e crea un test entro due minuti.

Installazione manuale

Ti consigliamo di aggiungere la verifica di Fraud Defense a un'interazione utente che deve essere verificata. Ad esempio, se vuoi verificare l'azione di invio di un modulo, devi aggiungere la verifica di Fraud Defense all'azione di invio.

A seconda di dove vuoi aggiungere la verifica di Fraud Defense, scegli l'opzione appropriata:

Aggiungi la verifica a un'interazione dell'utente

  1. Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la tua chiave universale all'interno dell'elemento <head></head> della pagina web:

    <head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

    Per impostazione predefinita, Fraud Defense utilizza la lingua del browser. Se vuoi specificare una lingua diversa, utilizza l'attributo hl=LANG nello script. Ad esempio, per utilizzare il francese, specifica quanto segue:

    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

    Per scoprire le lingue supportate, consulta i codici lingua per Fraud Defense.

    Se vuoi specificare una posizione per il badge, utilizza badge=LOCATION come parametro di query nel tag di script. Ad esempio, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. Per impostazione predefinita, la località è impostata su bottomright. Altri valori possibili sono inline e bottomleft.

  2. Per aggiungere la verifica di Fraud Defense a un'interazione utente, segui questi passaggi:

    1. Per assicurarti che grecaptcha.enterprise.execute() venga eseguito dopo il caricamento della libreria Fraud Defense, utilizza grecaptcha.enterprise.ready().

    2. Richiama grecaptcha.enterprise.execute() per ogni interazione che vuoi proteggere con la chiave universale. Specifica un nome significativo per un'interazione utente nel parametro action. Per ulteriori indicazioni, consulta Azioni.

      L'esempio seguente mostra come chiamare grecaptcha.enterprise.execute() su un'azione di accesso:

      <script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>

  3. Dopo che è stato generato, invia il token reCAPTCHA al tuo backend e crea un test entro due minuti.

Aggiungi Fraud Defense a un pulsante HTML

  1. Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la tua chiave universale all'interno dell'elemento <head></head> della pagina web:

    <head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

    Per impostazione predefinita, Fraud Defense utilizza la lingua del browser. Se vuoi specificare una lingua diversa, utilizza l'attributo hl=LANG nello script. Ad esempio, per utilizzare il francese, specifica quanto segue:

    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

    Per scoprire le lingue supportate, consulta i codici lingua per Fraud Defense.

  2. Per aggiungere Fraud Defense a un pulsante HTML, segui questi passaggi:

    1. Definisci una funzione di callback per gestire il token.

      <script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>

      Per saperne di più, consulta il metodo requestSubmit().

    2. Aggiungi attributi al pulsante HTML.

      <button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>

      Se vuoi specificare una posizione per il badge, utilizza l'attributo data-badge="LOCATION" nell'elemento che ha class="g-recaptcha". Per impostazione predefinita, la località è impostata su bottomright. Altri valori possibili sono inline e bottomleft.

    3. Quando questo pulsante viene utilizzato per inviare un modulo sul tuo sito, il parametro POST g-recaptcha-response contiene il token di risposta.

  3. Dopo che è stato generato, invia il token reCAPTCHA al tuo backend e crea una valutazione entro due minuti.

Passaggi successivi