Questo documento mostra come utilizzare l'account defender di reCAPTCHA per rilevare e prevenire attività fraudolente relative all'account sui siti web.
reCAPTCHA ti aiuta a proteggere le azioni critiche, come l'accesso e il pagamento. Tuttavia, esistono molte forme sottili di abuso dell'account che possono essere rilevate osservando il comportamento di uno specifico utente su un sito web in un determinato periodo di tempo. L'account defender di reCAPTCHA aiuta a identificare questo tipo di comportamento illecito sottile creando un modello specifico per il sito web al fine di rilevare una tendenza di comportamento sospetto o un cambiamento nell'attività. Utilizzando il modello specifico del sito, il servizio di difesa dell'account reCAPTCHA consente di rilevare quanto segue:
- Attività sospette
- Account con comportamenti simili
- Richieste provenienti da dispositivi contrassegnati come attendibili per utenti specifici
In base all'analisi di reCAPTCHA account defender e al modello specifico per il sito, puoi eseguire le seguenti azioni:
- Limitare o disattivare gli account fraudolenti.
- Impedisci i tentativi di violazione dell'account.
- Mitigare le violazioni degli account riuscite.
- Concedere l'accesso solo alle richieste provenienti da account utente legittimi.
- Riduci i problemi per gli utenti che accedono da uno dei loro dispositivi attendibili.
Prima di iniziare
Configura le tue pagine web per l'account defender di reCAPTCHA
L'account defender di reCAPTCHA richiede una comprensione completa delle attività degli account per consentire un rilevamento efficace. Per iniziare ad inviare le attività relative all'account a reCAPTCHA account defender e per creare e migliorare il modello specifico per il tuo sito, segui questi passaggi:
- Abilita la raccolta di dati di telemetria orizzontali.
- Genera report sulle azioni critiche degli utenti.
- Valuta gli eventi critici degli utenti.
- Annota gli eventi utente per ottimizzare il modello specifico per il tuo sito.
Abilita la raccolta di dati di telemetria orizzontali
L'account defender di reCAPTCHA richiede una visione completa delle azioni dell'utente, ad esempio se ha eseguito o meno l'accesso. Per abilitare la raccolta passiva dei dati di telemetria orizzontali da parte del difensore dell'account di reCAPTCHA, carica lo script JavaScript reCAPTCHA con la chiave di sito basata sul punteggio che hai creato in background di tutte le pagine web che fanno parte del flusso di lavoro dell'utente.
L'esempio seguente mostra come caricare lo script JavaScript reCAPTCHA in una pagina web.
<head> <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script> .... </head>
Report sulle azioni critiche degli utenti
Per rilevare pattern di attività sospette e creare una migliore comprensione di quelli tipici sul tuo sito, il difensore dell'account reCAPTCHA ha bisogno delle informazioni sulle azioni critiche degli utenti. Pertanto, segnala le azioni utente critiche sulle pagine web chiamando grecaptcha.enterprise.execute() su queste azioni utente critiche.
Ti consigliamo di segnalare tutte le azioni critiche dell'utente perché è utile per la raccolta di indicatori aggiuntivi. Per ogni azione dell'utente che vuoi segnalare,
sostituisci il valore del parametro action
di grecaptcha.enterprise.execute()
con un nome di azione che descriva l'azione.
La seguente tabella elenca i nomi delle azioni che puoi utilizzare quando segnali le azioni critiche degli utenti.
Nome azione | Evento o azione avviata dall'utente |
---|---|
LOGIN |
Accedi al sito web. |
REGISTRATION |
Registrazione sul sito web. |
SECURITY_QUESTION_CHANGE |
Richiedi di cambiare la domanda di sicurezza. |
PASSWORD_RESET |
Richiedi la reimpostazione della password. |
PHONE_NUMBER_UPDATE |
Richiedi l'aggiornamento del numero di telefono. |
EMAIL_UPDATE |
Richiedi l'aggiornamento dell'indirizzo email. |
ACCOUNT_UPDATE |
Richiedere l'aggiornamento delle informazioni relative all'account, ad esempio i dati di contatto. |
TRIGGER_MFA |
Un'azione che attiva una verifica MFA. |
REDEEM_CODE |
Richiedi il codice. |
LIST_PAYMENT_METHODS |
Recupera l'elenco dei metodi di pagamento. |
L'esempio seguente mostra come chiamare grecaptcha.enterprise.execute()
in un
aggiornamento del numero di telefono:
<script> function onClick(e) { e.preventDefault(); grecaptcha.enterprise.ready(async () => { const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'PHONE_NUMBER_UPDATE'}); }); } </script>
Valutare gli eventi critici degli utenti
Quando chiami grecaptcha.enterprise.execute()
su un'azione dell'utente, viene generato un token. Per gli eventi critici degli utenti, come accessi riusciti e non riusciti, registrazioni e azioni degli utenti che hanno eseguito l'accesso, crea una valutazione per valutare i risultati della chiamata grecaptcha.enterprise.execute()
. La valutazione fornisce un esito di rischio, che puoi utilizzare per decidere come gestire le attività potenzialmente fraudolente. Alcune delle azioni che puoi intraprendere sono il blocco delle richieste sospette, la sfida agli accessi rischiosi e l'indagine sugli account di interesse.
L'account defender di reCAPTCHA richiede che tu fornisca un identificatore di account stabile per attribuire l'attività utente, come richieste di accesso, richieste di accesso e richieste di registrazione, a un account specifico. Ciò consente all'account defender di reCAPTCHA di comprendere i pattern di attività utente e di creare un modello di attività per ciascun account al fine di rilevare meglio il traffico anomalo e illecito.
Scegli un identificatore dell'account stabile accountId
che non viene modificato spesso dall'utente
e forniscilo alla valutazione nel metodo
projects.assessments.create
. Questo identificatore di account stabile deve avere lo stesso valore per tutti gli eventi relativi allo stesso utente. Puoi fornire il seguente
identificatore dell'account:
Identificatori degli utenti
Se ogni account può essere associato in modo univoco a un nome utente, un indirizzo email o un numero
di telefono stabile, puoi utilizzarlo come accountId
. Quando fornisci questi identificatori tra siti (identificatori che possono essere riutilizzati in più siti), reCAPTCHA utilizza queste informazioni per migliorare la protezione dei tuoi account utente in base a modelli cross-site segnalando gli identificatori di account illeciti e utilizzando la conoscenza dei pattern di abuso tra siti correlati a questi identificatori.
In alternativa, se hai un ID utente interno associato in modo univoco a ogni account, puoi
fornirlo come accountId
.
Con hash o criptato
Se non disponi di un ID utente interno associato in modo univoco a ciascun account, puoi trasformare qualsiasi identificatore stabile in un identificatore di account opaco specifico per il sito. Questo identificatore è ancora necessario affinché l'account defender di reCAPTCHA possa comprendere i pattern di attività utente e rilevare comportamenti anomali, ma non viene condiviso tra altri siti.
Scegli qualsiasi identificatore dell'account stabile e rendilo opaco prima di inviarlo a reCAPTCHA utilizzando la crittografia o l'hashing:
crittografia (consigliata): cripta l'identificatore dell'account utilizzando un metodo di crittografia deterministico che produce un testo crittografato stabile. Per istruzioni dettagliate, consulta la sezione sulla crittografia dei dati in modo deterministico. Quando scegli la crittografia simmetrica rispetto all'hashing, non è necessario mantenere una mappatura tra gli identificatori utente e i corrispondenti identificatori utente opaci. Decripta gli identificatori opachi restituiti da reCAPTCHA per convertirli in identificatori utente.
Hashing: consigliamo di eseguire l'hashing dell'identificatore dell'account utilizzando il metodo SHA256-HMAC con un sale personalizzato a tua scelta. Poiché gli hash sono solo unidirezionali, devi mantenere una mappatura tra gli hash generati e gli identificatori utente in modo da poter mappare gli identificatori dell'account con hash che vengono restituiti agli account originali.
Oltre a fornire un identificatore dell'account stabile per tutte le richieste relative all'account, puoi fornire identificatori di account aggiuntivi, potenzialmente non stabili, per alcune richieste specifiche.
Gli identificatori dell'account specifici del contesto forniti in aggiunta a accountId
aiutano
il difensore dell'account reCAPTCHA a comprendere meglio l'attività utente e a rilevare
i tentativi di violazione dell'account per proteggere gli account utente. Se fornisci identificatori aggiuntivi, reCAPTCHA utilizza queste informazioni per migliorare la protezione dei tuoi account utente in base a modelli cross-site segnalando gli identificatori di account illeciti e usando la conoscenza dei modelli di abuso tra siti correlati a questi identificatori. Ad esempio, puoi fornire quanto segue:
Il nome utente, l'indirizzo email o il numero di telefono utilizzato come handle di accesso per le richieste di accesso
L'indirizzo email o il numero di telefono verificato per una richiesta di autenticazione a più fattori
Un indirizzo email o un numero di telefono (principale o secondario) fornito dall'utente durante una richiesta di aggiornamento dell'account
Gli indirizzi email e i numeri di telefono forniti dall'utente durante una richiesta di registrazione
Aggiungi l'identificatore dell'account stabile scelto al parametro accountId
nel metodo
projects.assessments.create
per tutte le richieste relative all'account. Se vuoi,
fornisci identificatori di account aggiuntivi per le richieste pertinenti utilizzando il campo userIds
nella valutazione.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- PROJECT_ID: l'ID del tuo progetto Google Cloud
- TOKEN: token restituito dalla chiamata
grecaptcha.enterprise.execute()
- KEY_ID: chiave reCAPTCHA associata al sito
- ACCOUNT_ID: l'identificatore associato in modo univoco all'account utente per un account utente sul tuo sito web
- EMAIL_ADDRESS: facoltativo. Un indirizzo email associato a questa richiesta, se presente
- PHONE_NUMBER: facoltativo. Un numero di telefono associato a questa richiesta, se presente
- USERNAME: facoltativo. Un nome utente associato a questa richiesta, se presente
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Corpo JSON della richiesta:
{ "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userInfo": { "accountId": "ACCOUNT_ID", "userIds": [ { "email": "EMAIL_ADDRESS" }, { "phoneNumber": "PHONE_NUMBER" }, { "username": "USERNAME" } ] } } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
curl -X POST \
-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/assessments"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "login", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.6, }, "event": { "token": "TOKEN", "siteKey": "KEY", "userInfo": { "accountId": "ACCOUNT_ID" } }, "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000", "accountDefenderAssessment": { "labels": ["SUSPICIOUS_LOGIN_ACTIVITY"] } }
Esempio di codice
Java
Per eseguire l'autenticazione a reCAPTCHA, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Interpreta l'esito del rischio degli eventi utente critici
Quando crei una valutazione con account defender abilitato, account defender restituisce accountDefenderAssessment
come parte della risposta della valutazione.
Il valore accountDefenderAssessment
ti consente di
valutare se l'attività utente è legittima o fraudolenta. Restituisce anche un ID valutazione che devi utilizzare per annotare gli eventi utente.
Di seguito è riportato un esempio di risposta JSON:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "login", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.6, }, "event": { "token": "TOKEN", "siteKey": "KEY_ID", "expectedAction": "USER_ACTION" }, "name": "projects/PROJECT_ID/assessments/b6ac310000000000X", "accountDefenderAssessment": { labels: ["SUSPICIOUS_LOGIN_ACTIVITY"] } }
Il campo accountDefenderAssessment
può avere uno qualsiasi dei seguenti valori:
Valore | Descrizione |
---|---|
SUSPICIOUS_LOGIN_ACTIVITY |
Indica che la richiesta rappresenta un rischio elevato di credential stuffing o violazione di account. |
SUSPICIOUS_ACCOUNT_CREATION |
Indica che la richiesta rappresenta un rischio elevato di creazione di account illecita. |
PROFILE_MATCH |
Indica che gli attributi dell'utente corrispondono a quelli visualizzati in precedenza per questo utente specifico. Questo valore indica che l'utente si trova su un dispositivo attendibile che è stato utilizzato in precedenza per accedere al tuo sito web.
|
RELATED_ACCOUNTS_NUMBER_HIGH |
Indica che la richiesta ha un numero elevato di account correlati. Ciò non implica necessariamente che l'account sia non valido, ma potrebbe richiedere ulteriori indagini. |
Annota gli eventi per ottimizzare il modello specifico per il tuo sito
Per fornire ulteriori informazioni a reCAPTCHA account defender e migliorare il tuo modello di rilevamento specifico per il sito, devi annotare gli eventi che hai valutato creando valutazioni.
Per annotare una valutazione, invia una richiesta al metodo projects.assessments.annotate
con l'ID valutazione. Nel corpo della richiesta, includi etichette che forniscono informazioni aggiuntive su un evento descritto nella valutazione.
Per annotare un test:
-
Determina le informazioni e le etichette da aggiungere nel corpo JSON della richiesta a seconda del caso d'uso.
La seguente tabella elenca le etichette e i valori che puoi utilizzare per annotare gli eventi:
Etichetta Descrizione Esempio di richiesta reasons
Obbligatorio. Un'etichetta a supporto delle valutazioni. Fornisci i dettagli dell'evento in tempo reale nell'etichetta
reasons
pochi secondi o minuti dopo l'evento perché influenzano il rilevamento in tempo reale.Per l'elenco dei valori possibili, consulta i valori dei motivi.
Esempio: per rilevare le violazioni degli account, annota se la password inserita è corretta con i valori
CORRECT_PASSWORD
oINCORRECT_PASSWORD
. Se hai eseguito il deployment della tua MFA, puoi aggiungere i seguenti valori:INITIATED_TWO_FACTOR
ePASSED_TWO_FACTOR
oFAILED_TWO_FACTOR
.{ "reasons": ["INCORRECT_PASSWORD"] }
annotation
Facoltativo. Un'etichetta per indicare la legittimità delle valutazioni. Fornisci informazioni sugli eventi di accesso e registrazione per convalidare o correggere le valutazioni dei rischi nell'etichetta
annotation
.Valori possibili:
LEGITIMATE
oFRAUDULENT
.Puoi inviare queste informazioni in qualsiasi momento o come parte di un job batch. Tuttavia, ti consigliamo di inviare queste informazioni entro pochi secondi o minuti dopo l'evento perché influiscono sul rilevamento in tempo reale.
{ "annotation": "LEGITIMATE" }
accountId
Facoltativo. Un'etichetta per associare un ID account a un evento.
Se hai creato una valutazione senza un ID account, utilizza questa etichetta per fornire l'ID account di un evento, se disponibile.
{ "accountId": "ACCOUNT_ID" }
Crea una richiesta di annotazione con le etichette appropriate.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- ASSESSMENT_ID: valore del campo
name
restituito dalla chiamataprojects.assessments.create
. - ANNOTATION: facoltativo. Un'etichetta per indicare se la valutazione è legittima o fraudolenta.
- REASONS: facoltativo. Motivi a supporto della tua annotazione. Per l'elenco dei valori possibili, consulta i valori dei motivi.
- ACCOUNT_ID: facoltativo. L'identificatore associato in modo univoco all'account utente sul tuo sito web.
Per maggiori informazioni, consulta la sezione Etichette per le annotazioni.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate
Corpo JSON della richiesta:
{ "annotation": ANNOTATION, "reasons": REASONS, "accountId": ACCOUNT_ID }
Per inviare la richiesta, scegli una delle seguenti opzioni:
curl
Salva il corpo della richiesta in un file denominato
request.json
ed esegui questo comando:curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate"PowerShell
Salva il corpo della richiesta in un file denominato
request.json
ed esegui questo comando:$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate" | Select-Object -Expand ContentDovresti ricevere un codice di stato di operazione riuscita (2xx) e una risposta vuota.
- ASSESSMENT_ID: valore del campo
Esempio di codice
Java
Per eseguire l'autenticazione a reCAPTCHA, configura le Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale.
Abilita reCAPTCHA account defender
Dopo aver configurato le pagine web per reCAPTCHA account defender, puoi abilitare reCAPTCHA account defender.
Nella console Google Cloud, vai alla pagina reCAPTCHA.
Verifica che il nome del progetto venga visualizzato nel selettore di risorse nella parte superiore della pagina.
Se non vedi il nome del progetto, fai clic sul selettore di risorse e poi seleziona il progetto.
- Fai clic su Impostazioni.
Nel riquadro Account defender, fai clic su Abilita.
Nella finestra di dialogo Configura account defender, fai clic su Abilita.
La propagazione dell'abilitazione del defender dell'account reCAPTCHA ai nostri sistemi potrebbe richiedere alcune ore. Dopo che l'abilitazione della funzionalità è stata propagata ai nostri sistemi, dovresti iniziare a ricevere risposte relative a account defender nell'ambito delle valutazioni.