‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

התקנת מקשים אוניברסליים בדפי אינטרנט

מפתח Fraud Defense Universal עוזר להגן על אפליקציות האינטרנט ונקודות הקצה ל-API מפני התקפות אוטומטיות של בוטים, שימוש לרעה בפרטי כניסה והונאות. באמצעות מפתח אוניברסלי, אתם יכולים לפרוס אמצעי הגנה באתר באמצעות יירוט אוטומטי של בקשות לאחזור מהרשת (AutoExecute), הפעלה ידנית של JavaScript או שילוב של שתי השיטות.

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

הכנת הסביבה ל-Google Cloud Fraud Defense.
יצירת מפתח אוניברסלי.
מגדירים דומיינים למפתח האוניברסלי.
כדי לראות את העמודה Status של נקודות קצה מוגנות במסוףGoogle Cloud , ודאו שיש לכם את ההרשאה monitoring.timeSeries.list ב-Cloud Monitoring. ההרשאה הזו כלולה בתפקידים המוגדרים מראש של Fraud Defense: אדמין ב-reCAPTCHA Enterprise, עריכה ב-reCAPTCHA Enterprise וצפייה ב-reCAPTCHA Enterprise.

התקנת מפתחות אוניברסליים באתר

כדי להתקין את המפתח האוניברסלי ולהגן על דפי האינטרנט, אתם יכולים להשתמש בהגדרה AutoExecute, בהתקנה ידנית של JavaScript או בשתי השיטות יחד בנקודות קצה שונות באמצעות אותו מפתח אוניברסלי:

הגדרת AutoExecute (מומלץ): המערכת מיירטת באופן אוטומטי בקשות אסינכרוניות לאחזור מהרשת לנתיבי כתובות URL שהוגדרו, ומצרפת את האסימון של reCAPTCHA לכותרת הבקשה.
הטמעה ידנית: משתמשת בקריאות grecaptcha.enterprise.execute() ידניות או במאפייני לחצן HTML. אתם יכולים להשתמש בשיטה הזו לבד או לצד AutoExecute בשביל בקשות לאחזור מהרשת שלא נתמכות ב-AutoExecute, בקשות שדורשות מיקום אסימון בהתאמה אישית במטען הייעודי (payload) או במהלך העברות מצטברות ל-AutoExecute.

הגדרת AutoExecute

התכונה AutoExecute יכולה לפשט את השילוב של JavaScript בממשק הקצה (frontend) על ידי יירוט בקשות לאחזור מהרשת בדפי האינטרנט שלכם, וביטול קריאות ידניות ל-grecaptcha.enterprise.execute() לכל פעולה בממשק הקצה.

איך פועלת התכונה AutoExecute

הסקריפט של Fraud Defense משתלב באופן אוטומטי עם פעולות הרשת שמוגדרות במדיניות של המפתח האוניברסלי. כשהסקריפט מזהה בקשה אסינכרונית לאחזור מהרשת לנתיב שהוגדר, הוא מיירט את הבקשה, מפעיל הערכת סיכונים ויכול להיות שיציג למשתמש אתגר CAPTCHA לפני שהבקשה המקורית תמשיך. האסימון שנוצר בתגובה מצורף באופן אוטומטי לכותרת X-Recaptcha-Token בבקשה.

ממשקי API נתמכים של רשתות

התכונה AutoExecute מיירטת רק בקשות אסינכרוניות לאחזור מהרשת שנוצרות על ידי ממשקי ה-API הבאים (כולל מסגרות כמו AJAX שמסתמכות עליהם):

שם ה-API	הגדרת זמן קצוב לתפוגה	דוגמה של הטמעה
Fetch API	מגדירים את הזמן הקצוב לתפוגה באמצעות הבקר `AbortSignal`.	`AbortSignal.timeout(n)`
XMLHttpRequest	מגדירים פסקי זמן באמצעות המאפיין המקורי `.timeout`.	`xhr.timeout = n`

שיטות מומלצות לשילוב

פעולות שמופעלות על ידי המשתמש בלבד: AutoExecute לא תומך במשאבים שנטענים באופן אוטומטי במהלך טעינת הדף. כדי למנוע כשל בשילוב, צריך להחיל את AutoExecute רק על בקשות שמופעלות על ידי אינטראקציות מפורשות של משתמשים (לדוגמה, לחיצה על כפתור התחברות או שליחה).
מניעת זמן קצוב לתפוגה של זמן אחזור: תהליכי האימות של Fraud Defense עלולים לפעמים לגרום לעיכובים ברשת. כדי למנוע זמן קצוב לתפוגה בצד הלקוח, תמיד צריך להגדיר זמן קצוב לתפוגה של בקשות מפורשות ישירות באמצעות המנגנונים שמפורטים בטבלה.
הגנה על נתיבים רגישים בלבד: מציינים את protectedEndpoints רק לנתיבים רגישים, ומשתמשים בשם משמעותי לאינטראקציה של המשתמש בפרמטר action. אל תגנו על כל נקודת קצה, כי הפעלת Fraud Defense בכל בקשה לקצה העורפי עלולה לפגוע בביצועים. הנחיות נוספות זמינות בקטע פעולות.

הוספת תג הסקריפט לדפי האינטרנט

כדי לטעון את Fraud Defense בדף האינטרנט, מוסיפים את JavaScript API עם המפתח האוניברסלי בתוך הרכיב <head></head> של דף האינטרנט:

<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>

כברירת מחדל, Fraud Defense משתמש בשפת הדפדפן. אם רוצים לציין שפה אחרת, משתמשים במאפיין hl=LANG בסקריפט. לדוגמה, כדי להשתמש בצרפתית, מציינים את הפרטים הבאים:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

מידע ולמידה על השפות הנתמכות, ראו קודי השפות של Fraud Defense.

הגדרת נקודות קצה מוגנות

כדי להגדיר נקודות קצה מוגנות למפתח האוניברסלי, בוחרים כרטיסייה:

המסוף

נכנסים לדף Fraud Defense במסוף Google Cloud .

מעבר אל Fraud Defense
בסרגל הכלים של המסוף, מוודאים שהפרויקט מופיע בכלי לבחירת משאבים. אם לא, לוחצים על בורר המשאבים ובוחרים את הפרויקט.
לוחצים על הכרטיסייה Keys.

בכרטיסייה Keys יש שתי תצוגות: Cards ו-Table. אם בפרויקט יש הרבה מפתחות, רק התצוגה Table זמינה.
בקטע reCAPTCHA keys, מאתרים את המפתח האוניברסלי שרוצים להגדיר:
- בתצוגת כרטיסים, לוחצים על פרטי המפתח בכרטיס המפתח.
- בתצוגה Table, לוחצים על שם המפתח.
בדף Key details, לוחצים על הכרטיסייה Integration.
בשלב Add reCAPTCHA to your website, בוחרים בכרטיסייה AutoExecute (recommended).

אופציונלי: כדי להגן באופן ידני על נקודות קצה ספציפיות, לוחצים על הכרטיסייה Manual כדי להציג את קטע הקוד של grecaptcha.enterprise.execute().
בקטע Protected endpoints, לוחצים על Add endpoint כדי להגדיר כל נקודת קצה שרוצים להגן עליה:
1. בשדה פעולה, מזינים שם לאינטראקציה של המשתמש. לדוגמה, login, register או add_to_cart. הנחיות נוספות
2. בשדה Path, מזינים את נתיב כתובת ה-URL הייחודי או את תבנית ה-glob שרוצים ליירט. לדוגמה, /login_api, /register_api או /cart_api/add/*.
3. אופציונלי: כדי להוסיף עוד נקודת קצה, לוחצים על הוספת נקודת קצה.
לוחצים על שמירה כדי לשמור את נקודות הקצה המוגנות.

אחרי ששומרים את ההגדרות, בעמודה Status בטבלה Protected endpoints אפשר לראות אם Fraud Defense קיבל תנועה לכל פעולה ב-24 השעות האחרונות. סטטוס התנועה יכול להתעדכן תוך 10 דקות אחרי שנקודת הקצה מקבלת תנועה בפעם הראשונה.

gcloud

כדי לבדוק את הגדרת המדיניות הנוכחית של המפתח האוניברסלי, משתמשים בפקודה gcloud alpha recaptcha policies describe:

gcloud alpha recaptcha policies describe --key=KEY_ID

כדי לעדכן את הגדרת המדיניות עם נקודות הקצה המוגנות, יוצרים קובץ YAML (לדוגמה, POLICY.yaml) שמגדיר את הנתיבים והפעולות המוגנים:

clientSettings:
  allowedDomains:
    - example.com
  protectedEndpointGroup:
    protectedEndpoints:
      - path: "/login_api"
        action: login
      - path: "/register_api"
        action: register
      - path: "/cart_api/add/*"
        action: add_to_cart

מעדכנים את הגדרת המפתח באמצעות קובץ ה-YAML, בעזרת הפקודה gcloud alpha recaptcha policies update:

gcloud alpha recaptcha policies update \
    --key=KEY_ID \
    --policy=POLICY.yaml

‫API בארכיטקטורת REST

כדי לעדכן את הגדרת המדיניות ולהגדיר נקודות קצה מוגנות באמצעות ה-API בארכיטקטורת REST, משתמשים ב-method‏ projects.keys.updatePolicy.

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

‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
‫KEY_ID: המזהה של המפתח האוניברסלי

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

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings

תוכן בקשת JSON:

{
"clientSettings": {
  "allowedDomains": [
    "example.com"
  ],
  "protectedEndpointGroup": {
    "protectedEndpoints": [
      {
        "path": "/login_api",
        "action": "login"
      },
      {
        "path": "/register_api",
        "action": "register"
      },
      {
        "path": "/cart_api/add/*",
        "action": "add_to_cart"
      }
    ]
  }
}
}

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

‫Curl (Linux,‏ macOS או Cloud Shell)

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

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X PATCH \
     -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/KEY_ID/policy?updateMask=clientSettings"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-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 PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy?updateMask=clientSettings" | Select-Object -Expand Content

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

תחביר ומגבלות של נקודות קצה מוגנות

אפשר להגדיר עד 25 נקודות קצה מוגנות לכל מפתח אוניברסלי. כל נקודת קצה צריכה לעמוד בדרישות הבאות:

‫action: שם הפעולה חייב להכיל בין תו אחד ל-100 תווים, ורק אותיות, מספרים, קווים נטויים (/) וקווים תחתונים (_).
path (תלוי אותיות רישיות): הנתיב חייב לעמוד בקריטריונים הבאים:
- להיות ייחודי, להתחיל ב-/ ולהכיל בין תו אחד ל-200 תווים, בלי קווים נטויים עוקבים (//).
- צריך לכלול לפחות פלח אחד שהוא לא תו כללי לחיפוש. לדוגמה, אי אפשר להשתמש ב-/, /*, /** או /*/.
- תווים כלליים לחיפוש חייבים לתפוס קטעים שלמים: * תואם לקטע בודד. לדוגמה, /api/*/login או /api/* הם ערכים תקינים, /api/login* הוא ערך לא תקין, ו-** תואם לכמה קטעים כקטע הסופי בלבד. לדוגמה, /api/** הוא ערך תקין, אבל /api/**/login הוא ערך לא תקין.

התנהגות של התאמת נתיב

התכונה AutoExecute מעריכה נקודות קצה מוגנות ברצף מלמעלה למטה, רק לפי נתיב כתובת ה-URL. הוא מתעלם מהדומיין, מהסכימה ומהפרמטרים של השאילתה של היעד. להתנהגות הזו יש את ההשלכות המעשיות הבאות:

סדר ההתאמה של הנתיבים: AutoExecute מחיל את נקודת הקצה התואמת הראשונה. אם אין נקודת קצה תואמת, AutoExecute לא מיירט את הבקשה. כדי למנוע הסתרה של נתיבים ספציפיים יותר, הציבו נתיבים ספציפיים לפני תבניות של תווים כלליים לחיפוש. לדוגמה, צריך לציין את /mysite/login לפני /*/login.
בקשות של צד שלישי: אם כלים של צד שלישי שפועלים בדף (כמו סקריפטים של ניתוח נתונים או של שותפים) שולחים בקשות לנתיבים שתואמים לנקודות הקצה המוגנות (לדוגמה, https://analytics.example.net/login שתואם ל-/login), AutoExecute מיירט גם אותן. זה יכול לגרום לזמן אחזור נוסף ברשת, למדדים מוטים או לאתגרי CAPTCHA לא צפויים. כדי למנוע התנגשויות, ודאו שהנתיבים המוגנים ייחודיים (לדוגמה, /auth/v1/login), או השתמשו בהתקנה ידנית אם יש התנגשויות בנתיבים.
ממשקי API חוצי-דומיינים: אם ה-API לקצה העורפי מתארח בדומיין שונה מהאתר (לדוגמה, cdn.example.com לעומת www.example.com), AutoExecute פועל באופן אוטומטי בלי הגדרת דומיין נוספת.

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

אימות טוקנים בקצה העורפי

ב-backend, מקבלים את אסימון התגובה מהכותרת של בקשת X-Recaptcha-Token ויוצרים הערכה תוך שתי דקות.

התקנה ידנית

מומלץ להוסיף אימות של Fraud Defense לאינטראקציה של משתמש שצריך לאמת. לדוגמה, אם רוצים לאמת את פעולת השליחה של טופס, צריך להוסיף אימות של Fraud Defense לפעולת השליחה.

בהתאם למקום שבו רוצים להוסיף את האימות של Fraud Defense, בוחרים באפשרות המתאימה:

הוספת אימות לאינטראקציה של משתמש
הוספת Fraud Defense ללחצן HTML

הוספת אימות באינטראקציה של המשתמש

כדי לטעון את reCAPTCHA בדף האינטרנט, מוסיפים את ה-API של JavaScript עם המפתח האוניברסלי בתוך הרכיב <head></head> של דף האינטרנט:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
כברירת מחדל, Fraud Defense משתמש בשפת הדפדפן. אם רוצים לציין שפה אחרת, משתמשים במאפיין hl=LANG בסקריפט. לדוגמה, כדי להשתמש בצרפתית, מציינים את הפרטים הבאים:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

מידע ולמידה על השפות הנתמכות, ראו קודי השפות של Fraud Defense.

אם רוצים לציין מיקום לתג, משתמשים ב-badge=LOCATION כפרמטר של שאילתה בתג הסקריפט. לדוגמה, https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&badge=bottomleft. כברירת מחדל, המיקום מוגדר כ-bottomright. ערכים אפשריים אחרים הם inline ו-bottomleft.
כדי להוסיף אימות של Fraud Defense לאינטראקציה של משתמש:
1. כדי לוודא שהפונקציה grecaptcha.enterprise.execute() תפעל אחרי שספריית Fraud Defense תיטען, צריך להשתמש ב-grecaptcha.enterprise.ready().
2. מפעילים את grecaptcha.enterprise.execute() בכל אינטראקציה שרוצים להגן עליה באמצעות המפתח האוניברסלי. ציינו שם משמעותי לאינטראקציה של משתמש בפרמטר action. הנחיות נוספות
  
  טיפ: הוסיפו את הקריאה execute לפעולות רגישות כמו LOGIN,‏ SIGNUP,‏ PASSWORD_RESET או PURCHASE.
  
  בדוגמה הבאה אפשר לראות איך להפעיל את grecaptcha.enterprise.execute() בפעולת התחברות:
```
<script>
  // Use `requestSubmit()` for extra features like browser input
  // validation.
  function onClick(e) {
    e.preventDefault();
    grecaptcha.enterprise.ready(async () => {
      const token = await grecaptcha.enterprise.execute(
        'KEY_ID',
        {action: 'LOGIN'}
      );
      // IMPORTANT: The 'token' that results from execute is an
      // encrypted response sent by Fraud Defense to
      // the end user's browser.
      // This token must be validated by creating an assessment.
      // See https://cloud.google.com/recaptcha/docs/create-assessment
    });
  }
</script>
```
אחרי שהטוקן נוצר, שולחים את הטוקן של reCAPTCHA לקצה העורפי ויוצרים הערכה תוך שתי דקות.

חשוב: בקצה העורפי צריך לציין את הערך assessment.event.expected_action (או expectedAction ב-JSON) בשדה CreateAssessmentRequest, והוא צריך להתאים לפעולה שהוגדרה בקריאה ל-execute(). לדוגמה, אם מגדירים את הפעולה של ממשק המשתמש ל-LOGIN, ה-backend צריך להגדיר את expected_action ל-LOGIN כשיוצרים הערכה לבקשה הזו. אם יש חוסר התאמה, זה מצביע על כך שתוקף מנסה לזייף פעולות.

הוספת Fraud Defense לכפתור HTML

כדי לטעון את reCAPTCHA בדף האינטרנט, מוסיפים את ה-API של JavaScript עם המפתח האוניברסלי בתוך הרכיב <head></head> של דף האינטרנט:
```
<head>
  <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
  ...
</head>
```
כברירת מחדל, Fraud Defense משתמש בשפת הדפדפן. אם רוצים לציין שפה אחרת, משתמשים במאפיין hl=LANG בסקריפט. לדוגמה, כדי להשתמש בצרפתית, מציינים את הפרטים הבאים:

<script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID&hl=fr"></script>

מידע ולמידה על השפות הנתמכות, ראו קודי השפות של Fraud Defense.
כדי להוסיף את Fraud Defense ללחצן HTML:
1. מגדירים פונקציית קריאה חוזרת (callback) כדי לטפל בטוקן.
```
<script>
  function onSubmit(token) {
    document.getElementById("demo-form").submit();
  }
  // Use `requestSubmit()` for extra features like browser input
  // validation.
</script>
```
  מידע נוסף זמין במאמר בנושא השיטה requestSubmit()‎.
2. מוסיפים מאפיינים ללחצן ה-HTML.
```
<button class="g-recaptcha"
    data-sitekey="KEY_ID"
    data-callback="onSubmit"
    data-action="submit">Submit</button>
```
  אם רוצים לציין מיקום לתג, משתמשים במאפיין data-badge="LOCATION" ברכיב שכולל את class="g-recaptcha". כברירת מחדל, המיקום מוגדר כ-bottomright. ערכים אפשריים אחרים הם inline ו-bottomleft.
3. כשמשתמשים בלחצן הזה כדי לשלוח טופס באתר, פרמטר ה-POST מסוג g-recaptcha-response מכיל את אסימון התגובה.
  
  הערה: אם מגדירים את הכפתור g-recaptcha כ-disabled, הכפתור מופעל כש-Fraud Defense נטען.
אחרי שהטוקן נוצר, שולחים את הטוקן של reCAPTCHA לקצה העורפי ויוצרים הערכה תוך שתי דקות.

חשוב: בקצה העורפי צריך לציין את הערך assessment.event.expected_action (או expectedAction ב-JSON) ב-CreateAssessmentRequest, והוא צריך להתאים לפעולה שהוגדרה בכפתור. לדוגמה, אם מגדירים את פעולת הלחצן כ-submit, ה-backend צריך להגדיר את expected_action כ-submit כשיוצרים הערכה לבקשה הזו. אם יש חוסר התאמה, זה מצביע על כך שתוקף מנסה לזייף פעולות.

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

כדי להפעיל אתגרי CAPTCHA על סמך כללים מותאמים אישית, מגדירים כללי מדיניות לאתגרים.
כדי להעריך את אסימון התגובה של reCAPTCHA, יוצרים הערכה.