Auf dieser Seite wird erläutert, wie Sie eine Bewertung erstellen, damit Ihr Back-End die Authentizität des Tokens prüfen kann, das reCAPTCHA Enterprise sendet. reCAPTCHA Enterprise sendet eine verschlüsselte Antwort, das reCAPTCHA-Antworttoken (Token), wenn der Endnutzer eine Aktion auslöst.
Sie müssen eine Bewertung erstellen, um die Ergebnisse von execute()
in Ihrem Back-End zu bewerten. Dazu senden Sie das generierte Token an den Endpunkt der Bewertung.
reCAPTCHA Enterprise verarbeitet das eingereichte Token und meldet die Gültigkeit und den Wert des Tokens.
Die ersten 1 Million reCAPTCHA Enterprise-Bewertungen pro Monat sind kostenlos. Damit Sie nach dem Erreichen des kostenlosen monatlichen Nutzungslimits (1 Million Bewertungen pro Monat) weiterhin Bewertungen erstellen können, müssen Sie die Abrechnung für Ihr Google Cloud-Projekt aktivieren. Weitere Informationen zur Abrechnung für reCAPTCHA Enterprise finden Sie unter Abrechnungsinformationen.
Hinweise
- Bereiten Sie Ihre Umgebung für reCAPTCHA Enterprise vor.
- Sie benötigen die folgende Rolle zu Identity and Access Management: reCAPTCHA Enterprise-Agent (
roles/recaptchaenterprise.agent
). - Installieren Sie auf Punktzahlen basierende Schlüssel in Ihrer iOS-App oder in Ihrer Android-App.
-
Richten Sie die Authentifizierung für reCAPTCHA Enterprise ein.
Die ausgewählte Authentifizierungsmethode hängt von der Umgebung ab, in der reCAPTCHA Enterprise eingerichtet wird. Die folgende Tabelle hilft Ihnen bei der Auswahl der geeigneten Authentifizierungsmethode und der unterstützten Schnittstelle zum Einrichten der Authentifizierung:
Umgebung Schnittstelle Authentifizierungsmethode Google Cloud - REST
- Clientbibliotheken
Verwenden Sie angehängte Dienstkonten. Lokal oder anderer Cloud-Anbieter REST Verwenden Sie API-Schlüssel oder die Identitätsföderation von Arbeitslasten. Wenn Sie API-Schlüssel verwenden möchten, sollten Sie Einschränkungen für API-Schlüssel anwenden, um sie zu sichern.
Clientbibliotheken Verwenden Sie:
- Verwenden Sie für Python oder Java API-Schlüssel oder die Identitätsföderation von Arbeitslasten.
Wenn Sie API-Schlüssel verwenden möchten, sollten Sie Einschränkungen für API-Schlüssel anwenden, um sie zu sichern.
- Verwenden Sie für andere Sprachen die Identitätsföderation von Arbeitslasten.
Token abrufen
Rufen Sie ein Token aus der Antwort des execute()
-Aufrufs ab.
Sie können nur einmal auf jedes Nutzertoken zugreifen.
Wenn Sie eine nachfolgende Aktion prüfen möchten, die ein Nutzer in Ihrer mobilen App ausführt, oder wenn ein Token abläuft, bevor eine Bewertung erstellt wird, müssen Sie execute()
noch einmal aufrufen, um ein neues Token zu generieren.
Bewertung erstellen
Nachdem Sie die Authentifizierung eingerichtet haben, erstellen Sie eine Bewertung. Dazu senden Sie eine Anfrage an die reCAPTCHA Enterprise API oder verwenden die reCAPTCHA Enterprise-Clientbibliotheken.
Um die Erkennung zu verbessern, sollten Sie beim Erstellen von Bewertungen die folgenden zusätzlichen Werte übergeben: userAgent
, userIpAddress
und ja3
.
REST API
Erstellen Sie eine Bewertung. Senden Sie dazu eine Anfrage an die reCAPTCHA Enterprise API. Sie können für die Authentifizierung entweder die gcloud CLI oder den API-Schlüssel verwenden.
gcloud CLI verwenden
Erstellen Sie eine Bewertung mit der Methode projects.assessments.create
. Senden Sie diese Anfrage an den API-Endpunkt v1
.
Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:
- PROJECT_ID: Ihre Google Cloud-Projekt-ID
- TOKEN: vom Aufruf
grecaptcha.enterprise.execute()
zurückgegebenes Token - KEY_ID: der reCAPTCHA-Schlüssel, der der Website oder App zugeordnet ist. Weitere Informationen finden Sie unter reCAPTCHA-Schlüssel.
- USER_AGENT: der User-Agent in der Anfrage vom Gerät des Nutzers.
- USER_IP_ADDRESS: die IP-Adresse in der Anfrage vom Gerät des Nutzers.
- JA3: JA3-Fingerabdruck für den SSL-Client. Wir empfehlen die Verwendung von salesforce/ja3 für die Berechnung von JA3.
- USER_ACTION: die vom Nutzer initiierte Aktion, die Sie im
grecaptcha.enterprise.execute()
-Aufruf füraction
angegeben haben, z. B.login
.Weitere Informationen finden Sie unter Aktionsnamen.
HTTP-Methode und URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
JSON-Text der Anfrage:
{ "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userAgent": "USER_AGENT", "userIpAddress": "USER_IP_ADDRESS", "ja3": "JA3", "expectedAction": "USER_ACTION" } }
Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:
curl
Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json
und führen Sie den folgenden Befehl aus:
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
Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json
und führen Sie den folgenden Befehl aus:
$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
Sie sollten in etwa folgende JSON-Antwort erhalten:
{ "tokenProperties": { "valid": true, "com.example.app" or "iosBundleId": "com.example.app", "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" }
Wir empfehlen, JSON-Parser im nicht strikten Parsing-Modus zu verwenden, um Ausfälle zu verhindern, falls zusätzliche Felder in die JSON-Antwort eingeführt werden.
API-Schlüssel verwenden
Erstellen Sie eine Bewertung mit der Methode projects.assessments.create
. Senden Sie diese Anfrage an den API-Endpunkt v1
.
Bevor Sie die Anfragedaten verwenden, ersetzen Sie die folgenden Werte:
- API_KEY: API-Schlüssel, der dem aktuellen Projekt zugeordnet ist
- PROJECT_ID: Ihre Google Cloud-Projekt-ID
- TOKEN: vom Aufruf
grecaptcha.enterprise.execute()
zurückgegebenes Token - KEY_ID: der reCAPTCHA-Schlüssel, der der Website oder App zugeordnet ist. Weitere Informationen finden Sie unter reCAPTCHA-Schlüssel.
- USER_AGENT: der User-Agent in der Anfrage vom Gerät des Nutzers.
- USER_IP_ADDRESS: die IP-Adresse in der Anfrage vom Gerät des Nutzers.
- JA3: JA3-Fingerabdruck für den SSL-Client. Wir empfehlen die Verwendung von salesforce/ja3 für die Berechnung von JA3.
- USER_ACTION: die vom Nutzer initiierte Aktion, die Sie im
grecaptcha.enterprise.execute()
-Aufruf füraction
angegeben haben, z. B.login
.Weitere Informationen finden Sie unter Aktionsnamen.
HTTP-Methode und URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY
JSON-Text der Anfrage:
{ "event": { "token": "TOKEN", "siteKey": "KEY_ID", "userAgent": "USER_AGENT", "userIpAddress": "USER_IP_ADDRESS", "ja3": "JA3", "expectedAction": "USER_ACTION" } }
Wenn Sie die Anfrage senden möchten, wählen Sie eine der folgenden Optionen aus:
curl
Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json
und führen Sie den folgenden Befehl aus:
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
Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json
und führen Sie den folgenden Befehl aus:
$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
Sie sollten in etwa folgende JSON-Antwort erhalten:
{ "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" }
Wir empfehlen, JSON-Parser im nicht strikten Parsing-Modus zu verwenden, um Ausfälle zu verhindern, falls zusätzliche Felder in die JSON-Antwort eingeführt werden.
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
Nächste Schritte
- Interpretieren Sie eine Bewertung und ergreifen Sie auf Grundlage des Ergebnisses geeignete Maßnahmen für Ihre App.