הגדרת מדיניות לאתגרים

במאמר הזה מוסבר איך להגדיר כללי מדיניות לאימות באמצעות שילוב קיים של Google Cloud Fraud Defense.

כללי אימות מאפשרים להפעיל אתגרי CAPTCHA באופן סלקטיבי על סמך כללים בהתאמה אישית. הכללים האלה קובעים מתי להציג אתגר של Fraud Defense על סמך חישוב של ציון סיכונים, כתובות IP, סוכני משתמש, מספרי מערכות אוטונומיות (ASN), אזורים גיאוגרפיים או זהויות מאומתות של בוטים (סוכני AI).

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

  • הגדרת AutoExecute: מפשטת את השילוב של JavaScript באפליקציות לקוח.
  • אתגרים: הפעלת אימות משתמשים כשהדבר נדרש לפי כללי האתגרים. ב-Fraud Defense יש תמיכה בסוגי האתגרים הבאים:
    • אתגרים חזותיים: המשתמשים מתבקשים לבחור תמונות לפי הנחיה. כברירת מחדל, אתגר חזותי נבחר כשמגדירים כלל עם אפשרות האתגר.
    • אתגרי אודיו: מבקשים מהמשתמשים לזהות אותות אודיו של דיבור כחלופה נגישה.
    • אתגרי קוד QR: מבקשים מהמשתמשים לסרוק קוד QR באמצעות המכשיר הנייד שלהם כדי לפתור אתגר. כדי להשתמש בתכונה הזו, המפתח האוניברסלי צריך להיות ברשימת ההיתרים. כדי להוסיף את המפתח האוניברסלי לרשימת ההיתרים, פנו לצוות Fraud Defense בכתובת fraud-defense@google.com וציינו את המפתח האוניברסלי.

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

  1. הכנת הסביבה ל-Google Cloud Fraud Defense.
  2. מוודאים שהחיוב מופעל בפרויקט ב- Google Cloud . כדי להפעיל את החיוב, אתם יכולים להשתמש בכרטיס אשראי או במספר לקוח לחיוב קיים של פרויקט ב- Google Cloud . אם אתם צריכים עזרה בנושאי חיוב, פנו לתמיכה של חיוב ב-Cloud.

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

    • כדי להעתיק את המזהה של מפתח קיים ממסוף Google Cloud :

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

        מעבר אל Fraud Defense

      2. ברשימה Keys, מוצאים את המפתח שרוצים להעתיק ולוחצים על Copy to clipboard.

    • כדי להעתיק את המזהה של מפתח קיים באמצעות ה-API בארכיטקטורת REST, מפעילים את ה-method‏ projects.keys.list.

    • כדי להעתיק את המזהה של מפתח קיים באמצעות ה-CLI של gcloud, מריצים את הפקודה gcloud recaptcha keys list.

  4. כדי לתכנן את השילוב של Fraud Defense, צריך לזהות את פעולות המשתמשים שרוצים להגן עליהן (למשל login, ‏ signup או password_reset) ואת הדפים באתר שמפעילים את הפעולות האלה. אם אתם משתמשים בהגדרת AutoExecute, ודאו שהפעולות האלה תואמות לשמות הפעולות שצוינו ב-protected_endpoint_group.

  5. משלבים את Fraud Defense בדף האינטרנט. מומלץ להשתמש בהגדרה AutoExecute של Fraud Defense. הוראות כלליות להגדרה מפורטות במאמר הטמעת מפתחות אוניברסליים באתרים.

סקירה כללית על הגדרת המדיניות של Fraud Defense

הגדרת המדיניות של Fraud Defense מאפשרת לכם להתאים אישית את אופן הפעולה של ההגנה של Fraud Defense. אפשר להגדיר כללי מדיניות לאימות באמצעות הקטע challenge_rule_groups.

אפשר לראות ולעדכן את הגדרות המדיניות באמצעות מסוף Google Cloud , ה-CLI של gcloud או ה-API בארכיטקטורת REST של reCAPTCHA Enterprise.

המסוף

כדי להציג או לעדכן את הגדרות המדיניות במסוף Google Cloud :

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

    מעבר אל Fraud Defense

  2. מוודאים שהפרויקט נבחר בכלי לבחירת משאבים.

  3. בטבלה reCAPTCHA keys, לוחצים על שם המפתח שרוצים להגדיר לו מדיניות אתגרים.

  4. בדף פרטים עיקריים, עוברים לכרטיסייה מדיניות.

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

  6. לוחצים על Save.

gcloud

כדי לעדכן את הגדרת המדיניות של מפתח, מריצים את הפקודה gcloud alpha recaptcha policies update:

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

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

gcloud alpha recaptcha policies describe --key=KEY_ID

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

כדי לעדכן את הגדרת המדיניות של מפתח, מפעילים את ה-method‏ projects.keys.updatePolicy:

PATCH https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

{
  "clientSettings": {
    "allowedDomains": [
      "example.com"
    ]
  },
  "challengeRuleGroups": [
    {
      "actions": ["login"],
      "challengeRules": [
        {
          "condition": "score < 0.7",
          "challenge": {}
        }
      ]
    }
  ]
}

כדי לראות את הגדרת המדיניות הנוכחית של מפתח, מפעילים את ה-method‏ projects.keys.getPolicy:

GET https://recaptchaenterprise.googleapis.com/v1/projects/PROJECT_ID/keys/KEY_ID/policy

הגדרת המדיניות משתמשת בפורמט YAML ל-Google Cloud CLI ובפורמט JSON ל-API בארכיטקטורת REST. הסכימה המלאה של הקטע challenge_rule_groups מופיעה במאמר הגדרת כללי מדיניות לאימות.

במאמר הגדרות לדוגמה של כללי אימות מפורטות דוגמאות לתרחישים שונים.

הגדרת כללי מדיניות לאימותים

אתם יכולים להגדיר מדיניות אימות בקטע challenge_rule_groups בהגדרות המדיניות של Fraud Defense. אם כבר יש לכם מדיניות עם client_settings, כולל פרטי הדומיינים, אתם יכולים לעדכן את המדיניות כך שתכלול את כללי המדיניות של האתגר.

המבנה של הקטע challenge_rule_groups:

challenge_rule_groups:
  - actions: [string, ...]
    challenge_rules:
      - condition: string
        challenge:
          # difficulty is optional: USABILITY | BALANCE (default) | SECURITY
          difficulty: BALANCE
        # OR no_challenge: {}
      - condition: string
        challenge:
          difficulty: BALANCE
        # OR no_challenge: {}

בכל כלל אימות, השדה condition הוא אופציונלי. אם לא מציינים את condition או שהוא ריק, הכלל חל ללא תנאי. בנוסף, השדות challenge ו-no_challenge הם בלעדיים, ורק אחד מהם צריך להופיע בכל כלל.

סדר הערכת הכללים

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

רמות הקושי של האתגרים

אתם יכולים לציין את רמת הקושי כשאתם מפעילים אתגר. רשימה מלאה של ערכי קושי תקינים מופיעה במאמרי העזרה של ה-API של ChallengeSecurityPreference.

תחביר התנאי

השדה condition הוא מחרוזת אופציונלית בפורמט של ביטוי Common Expression Language (CEL). אם condition לא צוין או שהוא ריק, הכלל חל ללא תנאי. שפת CEL מספקת אופרטורים סטנדרטיים דמויי C, כולל אופרטורים יחסיים (<,‏ <=,‏ >,‏ >=,‏ ==,‏ !=), אריתמטיים (+,‏ -,‏ /,‏ *,‏ %), לוגיים (!,‏ &&,‏ ||) ומאגרים ([],‏ in). שפת CEL תומכת בסוגי נתונים פרימיטיביים נפוצים (bool,‏ int,‏ uint,‏ double,‏ string), בסוגי מאגרים בסיסיים (lists,‏ messages) ובקבועים (כמו true,‏ 1,‏ 0.5,‏ "hello" ו-[1, 2, 3]).

בזמן הריצה, אפשר לגשת למשתנים הבאים של Fraud Defense:

משתנה סוג תיאור
score double ציון הבוט של Fraud Defense.
user_ip_address string כתובת ה-IP (מסוג IPv4 או IPv6) של המשתמש ששלח את הבקשה.
user_agent string סוכן המשתמש של המשתמש ששלח את הבקשה.
user_asn int מספר המערכת האוטונומית (ASN) של המשתמש ששלח את הבקשה. צריך להשמיט את הקידומת AS (לדוגמה, להשתמש ב-12345 במקום ב-AS12345).
region_code string קוד האזור של Unicode CLDR (מבוסס על ISO 3166-1 alpha-2) שמשויך למיקום הבקשה (לדוגמה, "US",‏ "CA" או "FR").
verified_bots list(Bot) רשימה של סוכנים או סורקים אוטומטיים מאומתים (כמו סוכני אינדקס של מנועי חיפוש, עוזרי חיפוש מבוססי-AI וסורקי תוכן של שותפים) שזוהו על ידי Fraud Defense.

הסוגים הנוספים הבאים שאינם פרימיטיביים מוגדרים. לרשימה המלאה של הערכים, ראו בוט.

message Bot {
  name [string] - the name of the bot
  bot_type [BotType] - the type of automated agent
}

למידע נוסף על ערכי name אפשריים, עיינו במאמרי העזרה של ה-API של Bot. מידע נוסף על ערכי enum חוקיים של bot_type זמין במאמרי העזרה של ה-API של BotType.

בכללי המדיניות של Fraud Defense לאימות, אתם יכולים להשתמש בכל אחד מהמשתנים האלה כדי ליצור ביטוי בוליאני. לדוגמה, score > 0.5,‏ user_ip_address == "192.0.2.1",‏ region_code == "US" ו-user_asn == 12345 הם ביטויי תנאי תקינים שמוערכים כערך בוליאני. שימו לב: מכיוון שהשדה user_asn הוא מסוג מספר שלם, צריך להשמיט את הקידומת AS כשבודקים מספרי ASN.

אפשר להשתמש בפונקציות הבאות בתנאי המדיניות של Fraud Defense לאימות:

שם חתימה תיאור
contains string.contains(string) -> bool בודקת אם האופרנד של המחרוזת מכיל את מחרוזת המשנה.
startsWith string.startsWith(string) -> bool הפונקציה בודקת אם האופרנד של המחרוזת מתחיל בקידומת שצוינה.
endsWith string.endsWith(string) -> bool בודקת אם האופרנד של המחרוזת מסתיים בסיומת שצוינה.
size size(string) -> int
size(list) -> int
string.size() -> int
list.size() -> int		 הפונקציה מחזירה את הגודל של מחרוזת (מספר נקודות הקוד) או של רשימה (מספר הרכיבים).

פונקציות הבנה הן סגנון של פקודות מאקרו שמובנות ב-CEL. אלה סוגי ההבנה שזמינים:

שם חתימה תיאור דוגמה
has has(message.field) -> bool בודק אם שדה זמין. has(verified_bots[0].name)
all list(A).all(A, predicate(A) -> bool) -> bool הפונקציה בודקת אם כל הרכיבים x ברשימה e תואמים לפרדיקט p. [1, 2, 3].all(x, x > 0)
exists list(A).exists(A, predicate(A) -> bool) -> bool בודק אם רכיב כלשהו x ברשימה e תואם לפרדיקט p. [1, 2, 3].exists(i, i % 2 != 0)
exists_one list(A).exists_one(A, predicate(A)) -> bool הפונקציה בודקת אם בדיוק רכיב אחד x ברשימה e תואם לפרדיקט p. [1, 2, 2].exists_one(i, i < 2)

הגדרות לדוגמה של כללי אימות

בקטע הזה יש דוגמאות להגדרות תקינות של כללי אימות.

הצגת אתגר לכל הבקשות עם ציון נמוך

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

בחירת אתגר עם חיכוך גבוה לכל הבקשות עם ציון נמוך

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge:
          difficulty: 'SECURITY'

ערעור על פעולות ספציפיות שקיבלו ציון נמוך

challenge_rule_groups:
  - actions: ['login', 'signup']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}

הגדרת ערכי סף שונים לכללים לפעולות שונות

challenge_rule_groups:
  - actions: ['login']
    challenge_rules:
      - condition: 'score < 0.5'
        challenge: {}
  - actions: ['signup']
    challenge_rules:
      - condition: 'score < 0.7'
        challenge: {}

לא להציג אתגר לכתובות IP ברשימת ההיתרים

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address in ["123.255.255.1", "123.255.255.2"]'
        no_challenge: {}

הערה: הכלל הזה שונה מהתכונה רשימות היתרים של כתובות IP ב-Fraud Defense.

לא להציג אתגר לרשת משנה של כתובות IP

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'user_ip_address.startsWith("123.255.255")'
        no_challenge: {}

לא להציג אתגר לבקשות ממספרי ASN ספציפיים

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      # Note that ASNs must be specified as integers without the AS prefix (e.g., 12345 instead of AS12345)
      - condition: 'user_asn in [12345, 67890]'
        no_challenge: {}

לא להציג אתגר לנציג של Google

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: 'verified_bots.exists(e, e.name == "google-agent")'
        no_challenge: {}

הצגת אתגר על סמך תנאים מורכבים

challenge_rule_groups:
  - actions: ['*']
    challenge_rules:
      - condition: '(user_agent.contains("Chrome/143") && score < 0.5) || (user_agent.contains("Chrome/149") && score < 0.7)'
        challenge: {}

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