הוספת הערות למבדקים

בדף הזה מוסבר איך אפשר לספק משוב על הדיוק של ההערכות שנוצרו על ידי reCAPTCHA. בעזרת המידע הזה, מערכת reCAPTCHA יכולה לשפר את המודל הספציפי לאתר שלכם ולספק ביצועים טובים יותר לאתר לאורך זמן.

מתי כדאי להוסיף הערות למבדקים

כשיוצרים מבדק, reCAPTCHA מספק ציון שעוזר להבין את רמת הסיכון שנובעת מאינטראקציות של משתמשים. בהמשך, כשהאתר יקבל מידע נוסף על אינטראקציות של משתמשים כדי לקבוע אם האינטראקציה הייתה לגיטימית או הונאה, תוכלו לאשר או לתקן את ההערכה של reCAPTCHA. כדי לעשות זאת, שולחים את מזהי בדיקת reCAPTCHA בחזרה אל Google עם התווית LEGITIMATE או FRAUDULENT. אישור או תיקון של ההערכה של reCAPTCHA משפרים את הביצועים של reCAPTCHA באתר שלכם.

כדי לשפר את הביצועים של reCAPTCHA, אפשר לאשר את ההערות לגבי חיוביים אמיתיים ושליליים אמיתיים בנוסף להערות לגבי שגיאות אפשריות בהערכה. לדוגמה, אם משתמש עבר אימות באמצעות שיטת אימות דו-שלבי וקיבל ציון גבוה ב-reCAPTCHA, אפשר להוסיף הערה לבדיקה ולציין שהיא LEGITIMATE. לחלופין, אם הציון של reCAPTCHA היה נמוך והאתר קבע שהאינטראקציה הייתה שמקורו בתרמית או התנהלות פוגעת, אפשר להוסיף הערה לבדיקה כFRAUDULENT.

ברשימה הבאה מוצג מידע נוסף על כמה דוגמאות לאינטראקציות של משתמשים, שמצביע על כך שהאינטראקציה לגיטימית או שהיא הונאה:

• החזרים כספיים על כרטיסי אשראי או הוכחות קונקרטיות אחרות להונאה מצביעים על כך שעסקה פיננסית קודמת הייתה הונאה.
• חשבון חדש ששולח הודעות שמסומנות כספאם על ידי משתמשים אחרים יכול להצביע על כך שהחשבון נוצר במרמה.
• אם משתמש מתקשה להיכנס לחשבון שלו ופותח פנייה לתמיכה, יכול להיות שהניסיון להתחבר הוא לגיטימי.
• רכישה או הזמנה באתר שמשתמש ב-reCAPTCHA כדי להתגונן מפני גירוד נתונים עשויות להעיד על כך שהמשתמש הוא לגיטימי.

לפני שמתחילים

• חשוב לוודא שיש לכם את התפקיד הבא לניהול זהויות והרשאות גישה (IAM): סוכן של reCAPTCHA Enterprise ‏(roles/recaptchaenterprise.agent).

• בהתאם למקום שבו הגדרתם את reCAPTCHA, משלימים את השלב המתאים:

  • יצירת בדיקה לאתר.
  • יצירת הערכה לאפליקציה לנייד
  • הגדרת השילוב של WAF.

אחזור מזהה ההערכה

כדי להוסיף הערה להערכה, מאחזרים את מזהה ההערכה הייחודי באחת מהדרכים הבאות:

• בשילובים עם אתרים ואפליקציות לנייד, אפשר לאחזר את מזהה ההערכה הייחודי מתגובת ההערכה.

  אחרי שיוצרים הערכה, מקבלים תגובת JSON כמו בדוגמה הבאה.

  מאחזרים את מזהה ההערכה הייחודי מהשדה name בתגובת ה-JSON.

  {
  'tokenProperties': {
    'valid': True,
    'hostname': 'www.google.com',
    'action': 'homepage',
    'createTime': u'2019-03-28T12:24:17.894Z'
  },
  'riskAnalysis': {
    'score': 0.1,
    'reasons': ['AUTOMATION']
  },
  'event': {
    'token': 'RESPONSE_TOKEN',
    'siteKey': 'KEY_ID'
  },
  'name': 'ASSESSMENT_ID'
  }

• באינטגרציות של WAF, אפשר לאחזר את מזהה ההערכה הייחודי מטוקן reCAPTCHA. מזהה ההערכה הייחודי הוא מחרוזת אלפאנומרית ייחודית באורך 16 תווים שמופיעה בסוף טוקן ה-reCAPTCHA אחרי :U=. לדוגמה, אם טוקן ה-reCAPTCHA הוא .................U=6ZZZZe73fZZZZZZ0, מזהה הבדיקה הוא 6ZZZZe73fZZZZZZ0.

הוספת הערה למבדק

1. קובעים את המידע והתוויות שרוצים להוסיף בגוף הבקשה ב-JSON, בהתאם לתרחיש השימוש.

   בטבלה הבאה מפורטים התוויות והערכים שאפשר להשתמש בהם כדי להוסיף הערות לאירועים:

   תווית	תיאור	דוגמה לבקשה
   reasons	זה שינוי אופציונלי. תווית שתעזור לכם בבדיקות. פרטי האירוע בזמן אמת מוצגים בתווית reasons תוך כמה שניות או דקות אחרי האירוע, כי הם משפיעים על הזיהוי בזמן אמת. רשימה של הערכים האפשריים זמינה במאמר ערכי הסיבות. דוגמה: כדי לזהות השתלטות על חשבון, מוסיפים הערה אם הסיסמה שהוזנה הייתה נכונה עם הערכים CORRECT_PASSWORD או INCORRECT_PASSWORD. אם פרסתם אימות רב-שלבי משלכם, אתם יכולים להוסיף את הערכים הבאים: INITIATED_TWO_FACTOR, ו- PASSED_TWO_FACTOR או FAILED_TWO_FACTOR.	{ "reasons": ["INCORRECT_PASSWORD"] }
   annotation	זה שינוי אופציונלי. תווית שמציינת את הלגיטימיות של ההערכות. הוספת עובדות לגבי אירועי כניסה ורישום כדי לאמת או לתקן את הערכות הסיכון בתווית annotation. ערכים אפשריים: LEGITIMATE או FRAUDULENT. אפשר לשלוח את המידע הזה בכל שלב או כחלק ממשימה באצווה. עם זאת, מומלץ לשלוח את המידע הזה כמה שניות או דקות אחרי האירוע, כי הוא משפיע על הזיהוי בזמן אמת.	{ "annotation": "LEGITIMATE" }

2. אפשר להוסיף הערה להערכה באמצעות השיטה projects.assessments.annotate עם ה-CLI של gcloud או מפתח API.

   הערה: אם אתם משתמשים בגרסה v1beta1 של ה-API, מומלץ להשתמש בגרסה v1 כי תכונות חדשות כמו reCAPTCHA Account defense זמינות רק בגרסה v1. כדי לעבור מ-v1beta1 ל-v1, אפשר לעיין במאמר מעבר מ-v1beta API ל-v1 API .

   ‫CLI של gcloud

   לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

   • ‫ASSESSMENT_ID: הערך של השדה name שמוחזר מהקריאה projects.assessments.create.
   • ‫ANNOTATION_LABEL: התווית שמציינת אם ההערכה לגיטימית או מזויפת. הערכים האפשריים הם LEGITIMATE או FRAUDULENT.
   • ‫ANNOTATION_REASON: תיאור ההקשר של ההערה שנבחרה להערכה הזו. מידע על הערכים האפשריים זמין במאמר סיבות להוספת הערות להערכה.

   ה-method של ה-HTTP וכתובת ה-URL:

   POST https://recaptchaenterprise.googleapis.com/v1/ASSESSMENT_ID:annotate

   גוף בקשת JSON:

   {
   "annotation": "ANNOTATION_LABEL"
   "reasons": "ANNOTATION_REASON"
   }
   

   כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

   curl

   הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

   שומרים את גוף הבקשה בקובץ בשם 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/ASSESSMENT_ID:annotate"

   PowerShell

   הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

   שומרים את גוף הבקשה בקובץ בשם 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/ASSESSMENT_ID:annotate" | Select-Object -Expand Content

   אמורים לקבל קוד סטטוס של הצלחה (2xx) ותגובה ריקה.

   מפתח API

   לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

   • ‫ASSESSMENT_ID: הערך של השדה name שמוחזר מהקריאה projects.assessments.create
   • ‫ANNOTATION_LABEL: התווית שמציינת אם ההערכה לגיטימית או מזויפת. הערכים האפשריים הם LEGITIMATE או FRAUDULENT.
   • ‫ANNOTATION_REASON: תיאור ההקשר של ההערה שנבחרה להערכה הזו. מידע על הערכים האפשריים זמין במאמר סיבות להוספת הערות להערכה.

   ה-method של ה-HTTP וכתובת ה-URL:

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/assessments/ASSESSMENT_ID:annotate?key=API_KEY

   גוף בקשת JSON:

   {
   "annotation": "ANNOTATION_LABEL"
   "reasons": "ANNOTATION_REASON"
   }
   

   כדי לשלוח את הבקשה עליכם לבחור אחת מהאפשרויות הבאות:

   curl

   הערה: כדי לבצע אימות באמצעות ה-API, צריך ליצור מפתח API.

   שומרים את גוף הבקשה בקובץ בשם 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/ASSESSMENT_ID:annotate?key=API_KEY"

   PowerShell

   הערה: כדי לבצע אימות באמצעות ה-API, צריך ליצור מפתח API.

   שומרים את גוף הבקשה בקובץ בשם 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/ASSESSMENT_ID:annotate?key=API_KEY" | Select-Object -Expand Content

   אמורים לקבל קוד סטטוס של הצלחה (2xx) ותגובה ריקה.

המאמרים הבאים

• מידע נוסף על אמצעי ההגנה על חשבונות משתמשים ב-reCAPTCHA