בקשות הערכה ב-Google Cloud Fraud Defense מאפשרות לכם להעריך את חישוב של ציון סיכונים ולאמת את תקינות הטוקן של הלקוח באינטראקציות באתר. אתם יכולים ליצור הערכות שיעזרו לכם להבחין בין תנועה לגיטימית לבין בוטים אוטומטיים לפני שאתם מעבדים עסקאות רגישות.
בדף הזה מוסבר איך ליצור בדיקה כדי לאפשר לקצה העורפי לאמת את האותנטיות של האסימון ש-Google Cloud Fraud Defense שולח. כשמשתמש קצה מפעיל פעולת HTML, Fraud Defense שולח תגובה מוצפנת, אסימון התגובה (שנקרא גם אסימון).
בכל סוג של שילוב מפתחות של reCAPTCHA (תיבת סימון, ניקוד או אוניברסלי), צריך ליצור הערכה כדי לבדוק את התוצאות של execute() בקצה העורפי. כדי לעשות את זה, שולחים את האסימון שנוצר לנקודת הקצה של ההערכה.
Fraud Defense מעבד את הטוקן שנשלח ומדווח על התוקף והניקוד של הטוקן.
10,000 הבדיקות הראשונות של Fraud Defense בכל חודש הן בחינם. כדי להמשיך ליצור הערכות אחרי שמגיעים למגבלת השימוש החודשית בחינם (10,000 הערכות בחודש), צריך להפעיל את החיוב בפרויקט ב- Google Cloud . מידע נוסף על החיוב ב-Fraud Defense זמין במאמר פרטי חיוב.
לפני שמתחילים
- הכנת הסביבה ל-Google Cloud Fraud Defense.
- מוודאים שיש לכם את התפקיד הבא בניהול זהויות והרשאות גישה (IAM): סוכן reCAPTCHA Enterprise (
roles/recaptchaenterprise.agent). - מטמיעים באתר מפתחות שמבוססים על ניקוד, מפתחות של תיבות סימון או מפתחות של אתגרים שמבוססים על מדיניות.
-
מגדירים אימות ל-Fraud Defense.
שיטת האימות שתבחרו תלויה בסביבה שבה מוגדר Fraud Defense. הטבלה הבאה תעזור לכם לבחור את שיטת האימות המתאימה ואת הממשק הנתמך להגדרת האימות:
סביבה ממשק שיטת אימות Google Cloud - REST
- ספריות לקוח
להשתמש בחשבונות שירות מצורפים. בארגון או אצל ספק אחר של שירותי ענן REST משתמשים במפתחות API או באיחוד שירותי אימות הזהות של עומסי העבודה. אם אתם רוצים להשתמש במפתחות API, מומלץ לאבטח אותם באמצעות החלת הגבלות על מפתחות API.
ספריות לקוח מומלץ להשתמש במשאבים הבאים:
- ב-Python או ב-Java, משתמשים במפתחות API או באיחוד שירותי אימות הזהות של עומסי עבודה.
אם אתם רוצים להשתמש במפתחות API, מומלץ לאבטח אותם באמצעות החלת הגבלות על מפתחות API.
- בשפות אחרות, צריך להשתמש באיחוד שירותי אימות הזהות של עומסי עבודה.
אחזור טוקן
אפשר לאחזר אסימון מדפי אינטרנט באחת מהדרכים הבאות:
- הערך המוסכם של ה-promise שהוחזר על ידי הקריאה ל-
grecaptcha.enterprise.execute(). - משתמשים בפרמטר POST מסוג
g-recaptcha-responseכשהמשתמש שולח טופס באתר. - כארגומנט מחרוזת לפונקציית הקריאה החוזרת אם
data-callbackמוגדר בg-recaptchaמאפיין תג HTML או בפרמטר הקריאה החוזרת ב-methodgrecaptcha.enterprise.render.
אפשר לגשת לטוקן של כל משתמש רק פעם אחת.
אם אתם צריכים להעריך פעולה נוספת שהמשתמש מבצע באתר, או אם פג התוקף של הטוקן לפני שנוצרה הערכה, אתם צריכים לקרוא שוב ל-execute() כדי ליצור טוקן חדש.
יצירת הערכה
אחרי שמגדירים את האימות, יוצרים הערכה על ידי שליחת בקשה ל-reCAPTCHA Enterprise API או באמצעות ספריות הלקוח של reCAPTCHA.
כדי לשפר את הזיהוי, מומלץ להעביר את הערכים הנוספים הבאים כשיוצרים בדיקות:
-
userAgent: סוכן המשתמש נכלל בבקשת ה-HTTP בכותרת הבקשה. מידע נוסף זמין במאמר מידע על כותרת הבקשהUser-Agentבמסמכי התיעוד של Mozilla Developer Network. -
userIpAddress: כתובת ה-IP של המשתמש ששולח בקשה לקצה העורפי זמינה בבקשת ה-HTTP. אם אתם משתמשים בשרת proxy, כתובת ה-IP זמינה בכותרת הבקשהX-Forwarded-For. מידע נוסף על קבלת כתובת ה-IP זמין במאמרX-Forwarded-For. -
ja4: JA4 היא שיטת קוד פתוח לטביעת אצבע של לקוחות TLS. מידע נוסף על יצירת טביעת אצבע של JA4 זמין במסמכי התיעוד של JA4 ב-GitHub. -
ja3: JA3 היא שיטת קוד פתוח ליצירת טביעות אצבע של לקוחות TLS. מידע נוסף על יצירת טביעת אצבע מסוג JA3 זמין במסמכי התיעוד של JA3 ב-GitHub.
כך אפשר להגן על האתר ועל האפליקציות לנייד מפני דפוסי התקפה מתקדמים וניצול לרעה על ידי בני אדם.
במאמרים האם Fraud Defense עומד בדרישות של GDPR? וGDPR ב-Google – פרטיות, בטיחות ואבטחה מוסבר איך Fraud Defense מטפל בנתונים.
הדרך ליצור הערכה זהה למפתחות שמבוססים על ניקוד, מפתחות של תיבות סימון, מפתחות של אתגרים שמבוססים על מדיניות ומפתחות אוניברסליים.
API בארכיטקטורת REST
יוצרים הערכה על ידי שליחת בקשה ל-reCAPTCHA API. כדי לבצע אימות, אתם יכולים להשתמש ב-CLI של gcloud או במפתח API.
שימוש ב-CLI של gcloud
יוצרים הערכה באמצעות השיטה projects.assessments.create. שולחים את הבקשה הזו לנקודת קצה ל-API של v1.
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud
- TOKEN: אסימון שהוחזר מהקריאה ל-
grecaptcha.enterprise.execute() - KEY_ID: מפתח reCAPTCHA שמשויך לאתר או לאפליקציה. מידע נוסף זמין במאמר מפתחות reCAPTCHA.
- USER_AGENT: סוכן המשתמש בבקשה מהמכשיר של המשתמש.
- USER_IP_ADDRESS: כתובת ה-IP בבקשה ממכשיר המשתמש.
- JA4: טביעת אצבע של JA4 ללקוח TLS. מומלץ להשתמש ב-
FoxIO-LLC/ja4כדי לחשב את טביעת האצבע של JA4. - JA3: טביעת אצבע של JA3 ללקוח TLS. מומלץ להשתמש ב-
salesforce/ja3כדי לחשב את טביעת האצבע של JA3. - USER_ACTION: הפעולה שהמשתמש התחיל, שציינתם בשביל
actionבקריאה ל-grecaptcha.enterprise.execute(), למשלlogin.מידע נוסף זמין במאמר שמות של פעולות.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments
גוף בקשת JSON:
{
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"userAgent": "USER_AGENT",
"userIpAddress": "USER_IP_ADDRESS",
"ja4": "JA4",
"ja3": "JA3",
"expectedAction": "USER_ACTION"
}
}
כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:
curl
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
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
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
$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
אתם אמורים לקבל תגובת JSON שדומה לזו:
{
"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",
"ja4": "JA4",
"ja3": "JA3",
"expectedAction": "USER_ACTION"
},
"name": "projects/PROJECT_NUMBER/assessments/b6ac310000000000"
}
כדי למנוע הפסקות זמניות בשירות אם נוספים שדות לתגובה, מומלץ להשתמש במצב ניתוח לא מחמיר במנתח ה-JSON.
שימוש במפתח API
יוצרים הערכה באמצעות השיטה projects.assessments.create. שולחים את הבקשה הזו לנקודת קצה ל-API של v1.
לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:
- API_KEY: מפתח ה-API שמשויך לפרויקט הנוכחי
- PROJECT_ID: מזהה הפרויקט ב- Google Cloud
- TOKEN: אסימון שהוחזר מהקריאה ל-
grecaptcha.enterprise.execute() - KEY_ID: מפתח reCAPTCHA שמשויך לאתר או לאפליקציה. מידע נוסף זמין במאמר מפתחות reCAPTCHA.
- USER_AGENT: סוכן המשתמש בבקשה מהמכשיר של המשתמש.
- USER_IP_ADDRESS: כתובת ה-IP בבקשה ממכשיר המשתמש.
- JA3: טביעת אצבע JA3 ללקוח SSL. מומלץ להשתמש ב-salesforce/ja3 כדי לחשב את JA3.
- USER_ACTION: הפעולה שהמשתמש התחיל, שציינתם בשביל
actionבקריאה ל-grecaptcha.enterprise.execute(), למשלlogin.מידע נוסף זמין במאמר שמות של פעולות.
ה-method של ה-HTTP וכתובת ה-URL:
POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments?key=API_KEY
גוף בקשת JSON:
{
"event": {
"token": "TOKEN",
"siteKey": "KEY_ID",
"userAgent": "USER_AGENT",
"userIpAddress": "USER_IP_ADDRESS",
"ja3": "JA3",
"expectedAction": "USER_ACTION"
}
}
כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:
curl
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
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
שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:
$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אתם אמורים לקבל תגובת JSON שדומה לזו:
{
"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"
}
כדי למנוע הפסקות זמניות בשירות אם נוספים שדות לתגובה, מומלץ להשתמש במצב ניתוח לא מחמיר במנתח ה-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 the 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/v2/apiv1" recaptchapb "cloud.google.com/go/recaptchaenterprise/v2/apiv1/recaptchaenterprisepb" ) 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 Fraud Defense. * @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 Fraud Defense. * token: The token obtained from the client on passing the `recaptchaKey`. * recaptchaAction: Action name corresponding to the token. * userIpAddress: The IP address of the user sending a request to your backend is available in the HTTP request. * userAgent: The user agent is included in the HTTP request in the request header. * ja4: JA4 fingerprint associated with the request. * ja3: JA3 fingerprint associated with the request. */ async function createAssessment({ projectID = "your-project-id", recaptchaKey = "your-recaptcha-key", token = "action-token", recaptchaAction = "action-name", userIpAddress = "user-ip-address", userAgent = "user-agent", ja4 = "ja4", ja3 = "ja3" }) { // 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, userIpAddress: userIpAddress, userAgent: userAgent, ja4: ja4, ja3: ja3, }, }, 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 the 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\Client\RecaptchaEnterpriseServiceClient; use Google\Cloud\RecaptchaEnterprise\V1\Event; use Google\Cloud\RecaptchaEnterprise\V1\Assessment; use Google\Cloud\RecaptchaEnterprise\V1\CreateAssessmentRequest; 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); $request = (new CreateAssessmentRequest()) ->setParent($projectName) ->setAssessment($assessment); try { $response = $client->createAssessment($request); // 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
המאמרים הבאים
- לפרש את ההערכה ולבצע פעולה מתאימה באתר על סמך הציון.