הגדרה של 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, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

    להפעלת ה-API

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

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

      כניסה לדף Credentials

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

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

יצירת מפתח מהיר של reCAPTCHA

כדי להטמיע את 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

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

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

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

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

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

    גוף בקשת JSON: 

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

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

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

    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/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,...]`‎. מומלץ לשתף כמה שיותר כותרות בסדר הנדרש. חשוב לוודא שסדר הכותרות עקבי בכל הבקשות באותו ביקור.
  • ‫JA3_FINGERPRINT: אופציונלי. ‫JA3 היא טביעת אצבע MD5 של שדות מסוימים בחבילת ClientHello של TLS. מידע נוסף זמין במאמר JA3 – שיטה ליצירת פרופיל של לקוחות SSL/TLS.
  • ‫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"],
    "ja3": "JA3_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 כברירת מחדל.

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