הגדרה של reCAPTCHA express בשרתי אפליקציות

אפשר להגדיר את reCAPTCHA express בשרת אפליקציות כשאי אפשר לבצע שילוב בצד הלקוח עם reCAPTCHA JavaScript או עם SDK לנייד, למשל כדי להגן על נקודות קצה של API.

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

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

1. בדף לבחירת הפרויקט במסוף Google Cloud , בוחרים פרויקט ב- Google Cloud או יוצרים אותו.

   תפקידים שנדרשים כדי לבחור או ליצור פרויקט

   • Select a project: כדי לבחור פרויקט לא צריך תפקיד IAM ספציפי – אפשר לבחור כל פרויקט שקיבלתם בו תפקיד.
   • יצירת פרויקט: כדי ליצור פרויקט, צריך את התפקיד Project Creator (roles/resourcemanager.projectCreator), שכולל את ההרשאה resourcemanager.projects.create. איך מקצים תפקידים

   כניסה לדף לבחירת הפרויקט

   שומרים את מזהה הפרויקט Google Cloud לשימוש בהמשך.

2. מוודאים שהחיוב מופעל בפרויקט Google Cloud .

3. מפעילים את reCAPTCHA Enterprise API, אם הוא עדיין לא מופעל.

   תפקידים שנדרשים להפעלת ממשקי API

   כדי להפעיל ממשקי API, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

   להפעלת ה-API

4. יוצרים מפתח API לאימות:

   1. נכנסים לדף Credentials במסוף Google Cloud .

      כניסה לדף Credentials

   2. לוחצים על Create credentials ואז על API key.

   3. שומרים את מפתח ה-API במקום בטוח כי יהיה צורך בו בהמשך.

יצירת מפתח reCAPTCHA Express

כדי להטמיע את reCAPTCHA Express, צריך ליצור מפתח reCAPTCHA Express.

1. במסוף Google Cloud , מפעילים את Cloud Shell.

   הפעלת Cloud Shell

   בחלק התחתון של Google Cloud המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. gcloud

   כדי ליצור מפתחות reCAPTCHA, משתמשים בפקודה gcloud recaptcha keys create.

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

   • ‫INTEGRATION_TYPE: סוג השילוב. מציינים את score.
   • ‫DISPLAY_NAME: השם של המפתח. בדרך כלל שם האתר.

   מריצים את הפקודה gcloud recaptcha keys create:

   ‫Linux,‏ macOS או Cloud Shell

   gcloud recaptcha keys create \
   --express \
   --display-name=DISPLAY_NAME

   ‏Windows (PowerShell)

   gcloud recaptcha keys create `
   --express `
   --display-name=DISPLAY_NAME

   Windows‏ (cmd.exe)

   gcloud recaptcha keys create ^
   --express ^
   --display-name=DISPLAY_NAME

   התשובה תכיל את מפתח reCAPTCHA החדש שנוצר.

   REST

   למידע על סוגי מפתחות וסוגי שילובים, אפשר לעיין במאמרי העזרה של ה-API בנושא מפתח וסוג שילוב.

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

   • ‫INTEGRATION_TYPE: סוג השילוב. מציינים את score.
   • ‫DISPLAY_NAME: השם של המפתח. בדרך כלל שם האתר.
   • ‫DEFAULT_SCORE_THRESHOLD: במקרה של מפתחות אתגר שמבוססים על מדיניות, הערך הזה מגדיר את סף האתגר האוניברסלי למפתח כשלא מוגדר סף מותאם אישית. התכונה הזו נמצאת בתצוגה מקדימה.
   • ‫ACTION_SCORE_THRESHOLDS: במקרה של מפתחות אתגר שמבוססים על מדיניות, כאן מציינים את הפעולה ואת ערך הסף התואם בין 0.0 ל-1.0. לדוגמה, login='{"scoreThreshold": "0.3"}',signup='{"scoreThreshold": "0.1"}'. התכונה הזו נמצאת בתצוגה מקדימה.
     הערה: רק הציונים הסופיים שמחושבים אחרי כל האתגרים מוחזרים בהערכות. הציון הראשוני שמחושב על ידי reCAPTCHA מושווה לסף.

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

   POST https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys

   גוף בקשת JSON:

   
   {
     "displayName": "DISPLAY_NAME",
     "expressSettings": {}
   }
   
   

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

   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/projects/PROJECT_ID/keys"

   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/projects/PROJECT_ID/keys" | Select-Object -Expand Content

   אתם אמורים לקבל תגובת JSON שדומה לזו:

   
   {
     "name": "projects/project-id/keys/7Ldqgs0UBBBBBIn4k7YxEB-LwEh5S9-Gv6QQIWB8m",
   "displayName": "DISPLAY_NAME,
   "expressSettings": {
   }
   }
   
   

שומרים את המפתח המהיר לשימוש בהמשך.

יצירת הערכה

כדי לשלוח בקשה משרת האפליקציה אל reCAPTCHA, צריך ליצור בדיקה באמצעות ה-method‏ projects.assessments.create.

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

• ‫API_KEY: מפתח ה-API שיצרתם לצורך האימות.
• ‫EXPRESS_KEY: מפתח reCAPTCHA express שיצרתם לאפליקציה.
• ‫USER_IP_ADDRESS: כתובת ה-IP בבקשה ממכשיר המשתמש שקשורה לאירוע הזה.
• ‫HEADER_INFO: אופציונלי. כותרות ה-HTTP שהלקוח שלח לשרת האפליקציות. זהו מערך מחרוזות שמכיל כותרות של בקשות בפורמט [key:value]. לדוגמה, ‎`[key:value, key:value,...]`‎. מומלץ לשתף כמה שיותר כותרות בסדר הנדרש. חשוב לוודא שסדר הכותרות עקבי בכל הבקשות באותו סשן.
• ‫JA4_FINGERPRINT: אופציונלי. ‫JA4 הוא טביעת אצבע של שדות מסוימים בחבילת Client Hello של TLS. מידע נוסף זמין במאמר JA4+™ Network Fingerprinting.
• ‫URI_NAME: אופציונלי. ה-URI שהמשתמש ניגש אליו.
• ‫USER_AGENT: אופציונלי. סוכן המשתמש שמופיע בבקשה מהמכשיר של המשתמש שקשור לאירוע הזה.
• ‫ACCOUNT_ID: אופציונלי. מזהה ייחודי וקבוע של חשבון המשתמש, כמו שם חשבון שעבר גיבוב.

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

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

גוף בקשת JSON:

{
  "event": {
    "siteKey": "EXPRESS_KEY",
    "express": true,
    "userIpAddress": "USER_IP_ADDRESS",
    "headers": ["HEADER_INFO"],
    "ja4": "JA4_FINGERPRINT",
    "requestedUri": "URI_NAME",
    "userAgent": "USER_AGENT",
    "user_info": {
      "account_id": "ACCOUNT_ID"
    }
  }
}

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

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 שדומה לזו:

{
  "name": "projects/123456789/assessments/abcdef1234000000",
  "event": {
    "token": "",
    "siteKey": "6L...",
    "userAgent": "Mozilla/5.0 (X11; CrOS x86_64 13816.55.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.86 Safari/537.36",
    "userIpAddress": "1.2.3.4",
    "express": true,
    "requestedUri": "https://example.com/",
    "user_info": {
      "account_id": "123456789"
    },
    "headers": [ "Origin: https://example.com", "Referer: https://example.com.login"],
  },
  "riskAnalysis": {
    "score": 0.7,
    "reasons": []
  }
}

פירוש הציונים

‫reCAPTCHA Express מחזירה רק שני ציונים: 0.3 ו-0.7. ‫0.3 מציין שהאינטראקציה של המשתמש מסוכנת יותר וסביר להניח שהיא הונאה, ו-0.7 מציין שהאינטראקציה של המשתמש מסוכנת פחות וסביר להניח שהיא לגיטימית.

אם אין מספיק אותות, reCAPTCHA express מחזיר 0.7 כברירת מחדל.

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

• איך מפרשים את ציוני הסיכון
• איך משתמשים ב-reCAPTCHA Express בשכבת ה-WAF