Questa pagina spiega come creare una valutazione per consentire al backend di verificare l'autenticità del token inviato da reCAPTCHA Enterprise. reCAPTCHA Enterprise invia una risposta criptata, il token di risposta reCAPTCHA (noto anche come token), quando l'utente finale attiva un'azione HTML.
Per qualsiasi tipo di integrazione della chiave reCAPTCHA (casella di controllo o punteggio), devi creare una valutazione per valutare i risultati di execute()
nel tuo backend inviando il token generato all'endpoint di valutazione.
reCAPTCHA Enterprise elabora il
token inviato e ne segnala la validità e il punteggio.
Il primo milione di valutazioni mensili di reCAPTCHA Enterprise è gratuito. Per continuare a creare valutazioni dopo aver raggiunto il limite di utilizzo mensile gratuito (1 milione di valutazioni al mese), devi abilitare la fatturazione per il tuo progetto Google Cloud. Per ulteriori informazioni sulla fatturazione per reCAPTCHA Enterprise, consulta Dati di fatturazione.
Prima di iniziare
- Prepara l'ambiente per reCAPTCHA Enterprise.
- Assicurati di disporre del seguente ruolo di Identity and Access Management:
Agente reCAPTCHA Enterprise (
roles/recaptchaenterprise.agent
). - Installa le chiavi basate sul punteggio o le chiavi delle caselle di controllo sul tuo sito web.
-
Configura l'autenticazione a reCAPTCHA Enterprise.
Il metodo di autenticazione scelto dipende dall'ambiente in cui è configurato reCAPTCHA Enterprise. La tabella seguente ti aiuta a scegliere il metodo di autenticazione appropriato e l'interfaccia supportata per configurare l'autenticazione:
Ambiente Interfaccia Metodo di autenticazione Google Cloud - REST
- Librerie client
Utilizza gli account di servizio collegati. On-premise o un cloud provider diverso REST Utilizza le chiavi API o la Federazione delle identità per i carichi di lavoro. Se vuoi utilizzare chiavi API, ti consigliamo di proteggere le chiavi API applicando restrizioni alle chiavi API.
Librerie client Utilizza quanto segue:
- Per Python o Java, utilizza le chiavi API o la Federazione delle identità per i carichi di lavoro.
Se vuoi utilizzare chiavi API, ti consigliamo di proteggere le chiavi API applicando restrizioni alle chiavi API.
- Per gli altri linguaggi, utilizza la federazione delle identità per i carichi di lavoro.
Recupera un token
Recupera un token dalle pagine web in uno dei seguenti modi:
- Il valore risolto della promessa restituita dalla chiamata a
grecaptcha.enterprise.execute()
. - Utilizza il parametro POST
g-recaptcha-response
quando un utente invia un modulo sul tuo sito. - Come argomento di stringa per la funzione di callback se
data-callback
è specificato nell'attributo del tag HTMLg-recaptcha
o nel parametro di callback nel metodogrecaptcha.enterprise.render
.
Puoi accedere al token di ciascun utente solo una volta.
Se devi valutare un'azione successiva che un utente esegue sul tuo sito o se un token scade prima della creazione di una valutazione, devi chiamare di nuovo execute()
per generare un nuovo token.
Crea una valutazione
Dopo aver configurato l'autenticazione, crea una valutazione inviando una richiesta all'API reCAPTCHA Enterprise o utilizzando le librerie client di reCAPTCHA Enterprise.
Per migliorare il rilevamento, ti consigliamo di passare i seguenti valori aggiuntivi durante la creazione delle valutazioni: userAgent
, userIpAddress
e ja3
.
Il modo in cui crei una valutazione è lo stesso per le chiavi basate sul punteggio e quelle delle caselle di controllo.
API REST
Crea una valutazione inviando una richiesta all'API reCAPTCHA Enterprise. Per l'autenticazione puoi utilizzare gcloud CLI o la chiave API.
Utilizza gcloud CLI
Crea una valutazione utilizzando il metodo projects.assessments.create
. Invia questa richiesta all'endpoint API v1
.
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: la chiave reCAPTCHA associata al sito o all'app. Per ulteriori informazioni, consulta le chiavi reCAPTCHA.
- USER_AGENT: lo user agent nella richiesta proveniente dal dispositivo dell'utente.
- USER_IP_ADDRESS: l'indirizzo IP nella richiesta inviata dal dispositivo dell'utente.
- JA3: impronta JA3 per il client SSL. Ti consigliamo di utilizzare salesforce/ja3 per il calcolo di JA3.
- USER_ACTION: l'azione avviata dall'utente che hai specificato per
action
nella chiamatagrecaptcha.enterprise.execute()
, ad esempiologin
.Per maggiori informazioni, consulta la sezione Nomi delle azioni.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
Corpo JSON della richiesta:
{ "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userAgent": "USER_AGENT", "userIpAddress": "USER_IP_ADDRESS", "ja3": "JA3", "expectedAction": "USER_ACTION" } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
arricciatura
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": "homepage", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.1, "reasons": ["AUTOMATION"] }, "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userAgent": "USER_AGENT", "userIpAddress": "USER_IP_ADDRESS", "ja3": "JA3", "expectedAction": "USER_ACTION" }, "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000" }
Ti consigliamo di utilizzare qualsiasi parser JSON in modalità di analisi non rigida per evitare interruzioni nel caso in cui vengano introdotti campi aggiuntivi nella risposta JSON.
Usa una chiave API
Crea una valutazione utilizzando il metodo projects.assessments.create
. Invia questa richiesta all'endpoint API v1
.
Prima di utilizzare i dati della richiesta, effettua le seguenti sostituzioni:
- API_KEY: chiave API associata al progetto corrente
- PROJECT_ID: l'ID del tuo progetto Google Cloud
- TOKEN: token restituito dalla chiamata
grecaptcha.enterprise.execute()
- KEY_ID: la chiave reCAPTCHA associata al sito o all'app. Per ulteriori informazioni, consulta le chiavi reCAPTCHA.
- USER_AGENT: lo user agent nella richiesta proveniente dal dispositivo dell'utente.
- USER_IP_ADDRESS: l'indirizzo IP nella richiesta inviata dal dispositivo dell'utente.
- JA3: impronta JA3 per il client SSL. Ti consigliamo di utilizzare salesforce/ja3 per il calcolo di JA3.
- USER_ACTION: l'azione avviata dall'utente che hai specificato per
action
nella chiamatagrecaptcha.enterprise.execute()
, ad esempiologin
.Per maggiori informazioni, consulta la sezione Nomi delle azioni.
Metodo HTTP e URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY
Corpo JSON della richiesta:
{ "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userAgent": "USER_AGENT", "userIpAddress": "USER_IP_ADDRESS", "ja3": "JA3", "expectedAction": "USER_ACTION" } }
Per inviare la richiesta, scegli una delle seguenti opzioni:
arricciatura
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
curl -X POST \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY"
PowerShell
Salva il corpo della richiesta in un file denominato request.json
ed esegui questo comando:
$headers = @{ }
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?key=API_KEY" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente:
{ "tokenProperties": { "valid": true, "hostname": "www.google.com", "action": "homepage", "createTime": "2019-03-28T12:24:17.894Z" }, "riskAnalysis": { "score": 0.1, "reasons": ["AUTOMATION"] }, "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userAgent": "USER_AGENT", "userIpAddress": "USER_IP_ADDRESS", "ja3": "JA3", "expectedAction": "USER_ACTION" }, "name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000" }
Ti consigliamo di utilizzare qualsiasi parser JSON in modalità di analisi non rigida per evitare interruzioni nel caso in cui vengano introdotti campi aggiuntivi nella risposta JSON.
C#
using System; using Google.Api.Gax.ResourceNames; using Google.Cloud.RecaptchaEnterprise.V1; public class CreateAssessmentSample { // Create an assessment to analyze the risk of a UI action. // projectID: Google Cloud project ID. // recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use reCAPTCHA Enterprise. // token: The token obtained from the client on passing the recaptchaKey. // recaptchaAction: Action name corresponding to the token. public void createAssessment(string projectID = "project-id", string recaptchaKey = "recaptcha-key", string token = "action-token", string recaptchaAction = "action-name") { // Create the client. // TODO: To avoid memory issues, move this client generation outside // of this example, and cache it (recommended) or call client.close() // before exiting this method. RecaptchaEnterpriseServiceClient client = RecaptchaEnterpriseServiceClient.Create(); ProjectName projectName = new ProjectName(projectID); // Build the assessment request. CreateAssessmentRequest createAssessmentRequest = new CreateAssessmentRequest() { Assessment = new Assessment() { // Set the properties of the event to be tracked. Event = new Event() { SiteKey = recaptchaKey, Token = token, ExpectedAction = recaptchaAction }, }, ParentAsProjectName = projectName }; Assessment response = client.CreateAssessment(createAssessmentRequest); // Check if the token is valid. if (response.TokenProperties.Valid == false) { System.Console.WriteLine("The CreateAssessment call failed because the token was: " + response.TokenProperties.InvalidReason.ToString()); return; } // Check if the expected action was executed. if (response.TokenProperties.Action != recaptchaAction) { System.Console.WriteLine("The action attribute in reCAPTCHA tag is: " + response.TokenProperties.Action.ToString()); System.Console.WriteLine("The action attribute in the reCAPTCHA tag does not " + "match the action you are expecting to score"); return; } // Get the risk score and the reasons. // For more information on interpreting the assessment, // see: https://cloud.google.com/recaptcha/docs/interpret-assessment System.Console.WriteLine("The reCAPTCHA score is: " + ((decimal)response.RiskAnalysis.Score)); foreach (RiskAnalysis.Types.ClassificationReason reason in response.RiskAnalysis.Reasons) { System.Console.WriteLine(reason.ToString()); } } public static void Main(string[] args) { new CreateAssessmentSample().createAssessment(); } }
Go
import ( "context" "fmt" recaptcha "cloud.google.com/go/recaptchaenterprise/apiv1" recaptchapb "google.golang.org/genproto/googleapis/cloud/recaptchaenterprise/v1" ) func main() { // TODO(developer): Replace these variables before running the sample. projectID := "project-id" recaptchaKey := "recaptcha-key" token := "action-token" recaptchaAction := "action-name" createAssessment(projectID, recaptchaKey, token, recaptchaAction) } /** * Create an assessment to analyze the risk of a UI action. * * @param projectID: Google Cloud project ID * @param recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use the services of reCAPTCHA Enterprise. * @param token: The token obtained from the client on passing the recaptchaKey. * @param recaptchaAction: Action name corresponding to the token. */ func createAssessment(projectID string, recaptchaKey string, token string, recaptchaAction string) { // Create the recaptcha client. // TODO: To avoid memory issues, move this client generation outside // of this example, and cache it (recommended) or call client.close() // before exiting this method. ctx := context.Background() client, err := recaptcha.NewClient(ctx) if err != nil { fmt.Printf("Error creating reCAPTCHA client\n") } defer client.Close() // Set the properties of the event to be tracked. event := &recaptchapb.Event{ Token: token, SiteKey: recaptchaKey, } assessment := &recaptchapb.Assessment{ Event: event, } // Build the assessment request. request := &recaptchapb.CreateAssessmentRequest{ Assessment: assessment, Parent: fmt.Sprintf("projects/%s", projectID), } response, err := client.CreateAssessment( ctx, request) if err != nil { fmt.Printf("%v", err.Error()) } // Check if the token is valid. if response.TokenProperties.Valid == false { fmt.Printf("The CreateAssessment() call failed because the token"+ " was invalid for the following reasons: %v", response.TokenProperties.InvalidReason) return } // Check if the expected action was executed. if response.TokenProperties.Action == recaptchaAction { // Get the risk score and the reason(s). // For more information on interpreting the assessment, // see: https://cloud.google.com/recaptcha/docs/interpret-assessment fmt.Printf("The reCAPTCHA score for this token is: %v", response.RiskAnalysis.Score) for _,reason := range response.RiskAnalysis.Reasons { fmt.Printf(reason.String()+"\n") } return } fmt.Printf("The action attribute in your reCAPTCHA tag does " + "not match the action you are expecting to score") }
Java
Node.js
const {RecaptchaEnterpriseServiceClient} = require('@google-cloud/recaptcha-enterprise'); /** * Create an assessment to analyze the risk of a UI action. Note that * this example does set error boundaries and returns `null` for * exceptions. * * projectID: Google Cloud project ID * recaptchaKey: reCAPTCHA key obtained by registering a domain or an app to use the services of reCAPTCHA Enterprise. * token: The token obtained from the client on passing the recaptchaKey. * recaptchaAction: Action name corresponding to the token. */ async function createAssessment({ projectID = "your-project-id", recaptchaKey = "your-recaptcha-key", token = "action-token", recaptchaAction = "action-name", }) { // Create the reCAPTCHA client & set the project path. There are multiple // ways to authenticate your client. For more information see: // https://cloud.google.com/docs/authentication // TODO: To avoid memory issues, move this client generation outside // of this example, and cache it (recommended) or call client.close() // before exiting this method. const client = new RecaptchaEnterpriseServiceClient(); const projectPath = client.projectPath(projectID); // Build the assessment request. const request = ({ assessment: { event: { token: token, siteKey: recaptchaKey, }, }, parent: projectPath, }); // client.createAssessment() can return a Promise or take a Callback const [ response ] = await client.createAssessment(request); // Check if the token is valid. if (!response.tokenProperties.valid) { console.log("The CreateAssessment call failed because the token was: " + response.tokenProperties.invalidReason); return null; } // Check if the expected action was executed. // The `action` property is set by user client in the // grecaptcha.enterprise.execute() method. if (response.tokenProperties.action === recaptchaAction) { // Get the risk score and the reason(s). // For more information on interpreting the assessment, // see: https://cloud.google.com/recaptcha/docs/interpret-assessment console.log("The reCAPTCHA score is: " + response.riskAnalysis.score); response.riskAnalysis.reasons.forEach((reason) => { console.log(reason); }); return response.riskAnalysis.score; } else { console.log("The action attribute in your reCAPTCHA tag " + "does not match the action you are expecting to score"); return null; } }
PHP
?<php // Include Google Cloud dependencies using Composer // composer require google/cloud-recaptcha-enterprise require 'vendor/autoload.php'; use Google\Cloud\RecaptchaEnterprise\V1\RecaptchaEnterpriseServiceClient; use Google\Cloud\RecaptchaEnterprise\V1\Event; use Google\Cloud\RecaptchaEnterprise\V1\Assessment; use Google\Cloud\RecaptchaEnterprise\V1\TokenProperties\InvalidReason; /** * Create an assessment to analyze the risk of a UI action. * @param string $siteKey The key ID for the reCAPTCHA key (See https://cloud.google.com/recaptcha/docs/create-key) * @param string $token The user's response token for which you want to receive a reCAPTCHA score. (See https://cloud.google.com/recaptcha/docs/create-assessment#retrieve_token) * @param string $project Your Google Cloud project ID */ function create_assessment( string $siteKey, string $token, string $project ): void { // TODO: To avoid memory issues, move this client generation outside // of this example, and cache it (recommended) or call client.close() // before exiting this method. $client = new RecaptchaEnterpriseServiceClient(); $projectName = $client->projectName($project); $event = (new Event()) ->setSiteKey($siteKey) ->setToken($token); $assessment = (new Assessment()) ->setEvent($event); try { $response = $client->createAssessment( $projectName, $assessment ); // You can use the score only if the assessment is valid, // In case of failures like re-submitting the same token, getValid() will return false if ($response->getTokenProperties()->getValid() == false) { printf('The CreateAssessment() call failed because the token was invalid for the following reason: '); printf(InvalidReason::name($response->getTokenProperties()->getInvalidReason())); } else { printf('The score for the protection action is:'); printf($response->getRiskAnalysis()->getScore()); // Optional: You can use the following methods to get more data about the token // Action name provided at token generation. // printf($response->getTokenProperties()->getAction() . PHP_EOL); // The timestamp corresponding to the generation of the token. // printf($response->getTokenProperties()->getCreateTime()->getSeconds() . PHP_EOL); // The hostname of the page on which the token was generated. // printf($response->getTokenProperties()->getHostname() . PHP_EOL); } } catch (exception $e) { printf('CreateAssessment() call failed with the following error: '); printf($e); } } // TODO(Developer): Replace the following before running the sample create_assessment( 'YOUR_RECAPTCHA_KEY', 'YOUR_USER_RESPONSE_TOKEN', 'YOUR_GOOGLE_CLOUD_PROJECT_ID' ); ?>
Python
Ruby
Passaggi successivi
- Interpreta una valutazione e intraprendi un'azione appropriata per il tuo sito in base al punteggio.