Installare le chiavi universali sulle pagine web

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questo documento descrive come installare e integrare una chiave universale nelle tue pagine web.

Prima di iniziare

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

2. Crea una chiave universale e configura i domini.

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

Attenzione: non configurare chiamate AutoExecute e manuali grecaptcha.enterprise.execute() sullo stesso endpoint. In questo modo, vengono attivate richieste duplicate, aumenta la latenza, vengono mostrate verifiche CAPTCHA duplicate e potrebbero essere addebitati costi di valutazione duplicati.

A seconda del tuo approccio di integrazione, scegli l'opzione appropriata:

Configurazione di AutoExecute

AutoExecute può 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.

Importante: quando utilizzi AutoExecute, tieni presente quanto segue:

• AutoExecute intercetta solo le richieste di rete asincrone avviate con l'API Fetch o XMLHttpRequest, incluse le richieste di framework come AJAX che utilizzano queste API.
• AutoExecute non è supportato per le risorse che vengono caricate automaticamente al momento del caricamento della pagina. Applica invece AutoExecute alle richieste di rete attivate da azioni dell'utente sulla pagina, ad esempio un pulsante di accesso.
• Per evitare che i test di Fraud Defense causino timeout di rete, applica i timeout direttamente alle richieste. Utilizza AbortSignal.timeout(n) per l'API Fetch e la proprietà XMLHttpRequest.timeout per XMLHttpRequest.

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

Lo script Fraud Defense si integra automaticamente con le azioni di rete definite nella configurazione della policy della chiave universale. Questa sezione definisce una mappatura dei percorsi dell'URL (path) ai nomi delle azioni (action).

Suggerimento: specifica protected_endpoints solo per i percorsi sensibili. Per ogni percorso, specifica 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.

Se lo script di Fraud Defense rileva una richiesta di rete asincrona a un percorso mappato, intercetta la richiesta, attiva una valutazione del rischio e, potenzialmente, mostra una verifica CAPTCHA all'utente prima che la richiesta originale continui. Il token di risposta generato viene allegato automaticamente all'intestazione X-Recaptcha-Token nella richiesta.

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:

client_settings:
  allowedDomains:
    - example.com
  protected_endpoint_group:
    protected_endpoints:
      - 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

Nota: il comando gcloud alpha recaptcha policies update aggiorna l'intera policy. Tutti i protected_endpoint_group o challenge_rule_groups esistenti devono essere inclusi nel file POLICY.yaml per evitare di eliminarli.

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.protectedEndpointGroup

Corpo JSON della richiesta:

{
"clientSettings": {
  "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:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup"

PowerShell (Windows)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings.protectedEndpointGroup" | Select-Object -Expand Content

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

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 non 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; /api/**/login non è valido).

Nota: AutoExecute trova le richieste con corrispondenza in base solo al percorso dell'URL e non controlla il dominio di destinazione. Ciò ha le seguenti implicazioni pratiche:

• 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 le intercetterà. Ciò può causare latenza di rete aggiuntiva, metriche distorte o test CAPTCHA imprevisti. 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, examplecdn.net 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à.

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

Importante: il backend deve specificare assessment.event.expected_action (o expectedAction in JSON) in CreateAssessmentRequest e deve corrispondere all'azione configurata in ProtectedEndpoint. Ad esempio, se configuri l'azione dell'endpoint protetto in modo che sia login, il tuo backend deve impostare expected_action su login quando crea un'analisi per la richiesta. In caso di mancata corrispondenza, ciò indica che un utente malintenzionato sta tentando di falsificare le azioni.

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 utente
• Aggiungi Fraud Defense a un pulsante HTML

Aggiungi la verifica a un'interazione dell'utente

1. Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la 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 località 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. Chiama grecaptcha.enterprise.execute() per ogni interazione che vuoi proteggere con la tua chiave universale. Specifica un nome significativo per un'interazione utente nel parametro action. Per ulteriori indicazioni, consulta Azioni.

      Suggerimento: aggiungi la chiamata execute ad azioni sensibili come LOGIN, SIGNUP, PASSWORD_RESET o PURCHASE.

      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 una valutazione entro due minuti.

   Importante: il backend deve specificare assessment.event.expected_action (o expectedAction in JSON) in CreateAssessmentRequest e deve corrispondere all'azione configurata nella chiamata execute(). Ad esempio, se configuri l'azione frontend in modo che sia LOGIN, il backend deve impostare expected_action su LOGIN durante la creazione di un test per la richiesta. In caso di mancata corrispondenza, ciò indica che un utente malintenzionato sta tentando di falsificare le azioni.

Aggiungi Fraud Defense a un pulsante HTML

1. Per caricare reCAPTCHA sulla tua pagina web, aggiungi l'API JavaScript con la 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().

   1. 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 contiene class="g-recaptcha". Per impostazione predefinita, la località è impostata su bottomright. Altri valori possibili sono inline e bottomleft.

   1. Quando questo pulsante viene utilizzato per inviare un modulo sul tuo sito, il parametro POST g-recaptcha-response contiene il token di risposta.
   Nota: se imposti il pulsante g-recaptcha come disabled, il pulsante viene attivato quando viene caricato Fraud Defense.

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

   Importante: il backend deve specificare assessment.event.expected_action (o expectedAction in JSON) in CreateAssessmentRequest e deve corrispondere all'azione configurata sul pulsante. Ad esempio, se configuri l'azione del pulsante in modo che sia submit, il tuo backend deve impostare expected_action su submit durante la creazione di un test per la richiesta. In caso di mancata corrispondenza, ciò indica che un utente malintenzionato sta tentando di falsificare le azioni.

Passaggi successivi

• Per attivare le verifiche CAPTCHA in base a regole personalizzate, configura le policy di verifica.

• Per valutare il token di risposta reCAPTCHA, crea una valutazione.