שילוב עם Google Cloud Armor לאפליקציות לנייד

במאמר הזה מוסבר איך לשלב את התכונות של reCAPTCHA עם Cloud Armor באפליקציות לנייד.

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

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

1. מפעילים את reCAPTCHA Enterprise API.

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

   כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

   להפעלת ה-API

2. מזהים את הפעולות שרוצים להגן עליהן.

הטמעה של טוקנים של פעולות reCAPTCHA

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

כדי להטמיע טוקן פעולה של reCAPTCHA, מבצעים את הפעולות הבאות:

1. יוצרים מפתח של טוקן פעולה לאפליקציה לנייד.

   המסוף

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

      מעבר אל reCAPTCHA

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

      אם שם הפרויקט לא מופיע, לוחצים על בורר המשאבים ובוחרים את הפרויקט.

   3. לוחצים על Create key.
   4. בשדה שם לתצוגה, מזינים שם לתצוגה של המפתח.
   5. בהתאם לסוג האפליקציה שעבורה רוצים ליצור את מפתחות ה-reCAPTCHA ל-WAF, מבצעים את הפעולה המתאימה:
   הערה: אפשר ליצור רק מפתחות של טוקנים לפעולות באפליקציות לנייד.

   יצירת מפתחות reCAPTCHA ל-WAF עבור אפליקציות ל-iOS

   מומלץ ליצור מפתח reCAPTCHA אחד לכל אפליקציית iOS.

   1. בקטע Application type, בוחרים באפשרות iOS.
   1. בקטע רשימת מזהי חבילות ל-iOS, לוחצים על הוספת מזהה חבילה ל-iOS.

   2. בשדה Bundle ID (מזהה החבילה), מזינים את השם של מזהה החבילה של iOS.

   3. אופציונלי: כדי להוסיף מזהה חבילה נוסף ל-iOS, לוחצים על הוספת מזהה חבילה ל-iOS ומזינים את השם של מזהה החבילה ל-iOS בשדה מזהה חבילה.
   4. כדי להגן על מפתח reCAPTCHA של מזהי החבילות, מוודאים שהמתג השבתת אימות מזהה החבילה מושבת.

   5. אופציונלי: מציינים הגדרות של Apple Developer.

      מומלץ לספק את הנתונים האלה כי הם מאפשרים ל-reCAPTCHA לספק ציוני סיכון מדויקים יותר לגבי התנועה באתר.

      מזינים את פריטי המידע האלה:

      • מפתח פרטי (‎.p8): המפתח הזה נוצר ב-Apple Developer Center בקטע Certificates, Identifiers & Profiles (אישורים, מזהים ופרופילים).
      • מזהה המפתח: מזהה המפתח למפתחים של Apple (מחרוזת בת 10 תווים).
      • מזהה צוות: מזהה הצוות של אפל (מחרוזת בת 10 תווים) שבבעלותו פרופיל ההקצאה שמשמש ליצירת האפליקציה.
   6. אופציונלי: לוחצים על השלב הבא (אופציונלי).
   1. כדי ליצור מפתח reCAPTCHA ל-WAF, מבצעים את הפעולות הבאות:
      1. בהגדרות נוספות, מפעילים את
      2. בהגדרות נוספות, מפעילים את המתג האם תפרסו את המפתח הזה בחומת אש של אפליקציית אינטרנט (WAF)?.
      3. באפשרויות Service, בוחרים באפשרות Cloud Armor.
      4. באפשרויות של תכונה, בוחרים באפשרות פעולה.

   2. אם רוצים לציין ציון שהמפתח יחזיר כשייווצרו עבורו הערכות כלשהן בסביבה שאינה סביבת ייצור, צריך לבצע את הפעולות הבאות:

      1. בקטע הגדרות נוספות, לוחצים על המתג האם המפתח הזה נוצר למטרות בדיקה בלבד?.
      2. משתמשים בפס ההזזה הגדרת ציון כדי לציין ציון בין 0 ל-1.0.
   7. לוחצים על Create key.

   המפתח החדש שנוצר מופיע בדף מפתחות reCAPTCHA.

   יצירת מפתחות reCAPTCHA ל-WAF עבור אפליקציות ל-Android

   1. בקטע Application type, בוחרים באפשרות Android.
      
   2. בקטע רשימת חבילות Android, לוחצים על הוספת חבילת Android.
   3. בשדה Android package (חבילת Android), מזינים את השם של חבילת Android.
   4. אופציונלי: כדי להוסיף חבילה נוספת, לוחצים על הוספת חבילת Android ומזינים את השם של חבילת Android נוספת בשדה חבילת Android.
   5. כדי לוודא שמפתח reCAPTCHA ישמש רק באפליקציה שלכם, משביתים את המתג השבתת אימות שם החבילה.
   6. אם רוצים ליצור מפתח לאפליקציה שזמינה בחנויות אפליקציות אחרות בנוסף לחנות Google Play, מפעילים את האפשרות תמיכה באפליקציות שמופצות מחוץ לחנות Google Play.
   7. אופציונלי: לוחצים על השלב הבא (אופציונלי).
   1. כדי ליצור מפתח reCAPTCHA ל-WAF, מבצעים את הפעולות הבאות:
      1. בהגדרות נוספות, מפעילים את
      2. בהגדרות נוספות, מפעילים את המתג האם תפרסו את המפתח הזה בחומת אש של אפליקציית אינטרנט (WAF)?.
      3. באפשרויות Service, בוחרים באפשרות Cloud Armor.
      4. באפשרויות של תכונה, בוחרים באפשרות פעולה.

   2. אם רוצים לציין ציון שהמפתח יחזיר כשייווצרו עבורו הערכות כלשהן בסביבה שאינה סביבת ייצור, צריך לבצע את הפעולות הבאות:

      1. בקטע הגדרות נוספות, לוחצים על המתג האם המפתח הזה נוצר למטרות בדיקה בלבד?.
      2. משתמשים בפס ההזזה הגדרת ציון כדי לציין ציון בין 0 ל-1.0.
   8. לוחצים על Create key.

   המפתח החדש שנוצר מופיע בדף מפתחות reCAPTCHA.

   ‫gcloud ‏ (iOS)

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

   הערה: יצירת מפתחות reCAPTCHA ל-WAF באפליקציות לנייד נתמכת רק בשילוב עם Cloud Armor. באינטגרציה הזו, אפשר ליצור רק מפתחות של טוקנים לפעולות באפליקציות לנייד.

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

   • ‫DISPLAY_NAME: שם המפתח. בדרך כלל שם האתר.
   • ‫BUNDLE_IDs: מזהי החבילות של אפליקציות ל-iOS שמורשות להשתמש במפתח. אפשר לציין כמה מזהי חבילות כרשימה מופרדת בפסיקים.
   • ‫WAF_FEATURE: השם של התכונה ב-WAF. מציינים את action-token.
   • ‫WAF_SERVICE: השם של ספק שירותי ה-WAF. מציינים את CA ל-Cloud Armor.

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

   ‫Linux,‏ macOS או Cloud Shell

   gcloud recaptcha keys create \
   --display-name=DISPLAY_NAME  \
   --ios --bundle-ids=BUNDLE_IDs \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE 

   ‏Windows (PowerShell)

   gcloud recaptcha keys create `
   --display-name=DISPLAY_NAME  `
   --ios --bundle-ids=BUNDLE_IDs `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE 

   Windows‏ (cmd.exe)

   gcloud recaptcha keys create ^
   --display-name=DISPLAY_NAME  ^
   --ios --bundle-ids=BUNDLE_IDs ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE 

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

   ‫gcloud ‏ (Android)

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

   הערה: יצירת מפתחות reCAPTCHA ל-WAF באפליקציות לנייד נתמכת רק בשילוב עם Cloud Armor. באינטגרציה הזו, אפשר ליצור רק מפתחות של טוקנים לפעולות באפליקציות לנייד.

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

   • ‫DISPLAY_NAME: שם המפתח. בדרך כלל שם האתר.
   • ‫PACKAGE_NAMES: שמות החבילות של אפליקציות ל-Android שמורשות להשתמש במפתח. אפשר לציין כמה שמות של חבילות כרשימה מופרדת בפסיקים.
   • ‫WAF_FEATURE: השם של התכונה ב-WAF. מציינים את action-token.
   • ‫WAF_SERVICE: השם של ספק שירותי ה-WAF. מציינים את CA ל-Cloud Armor.

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

   ‫Linux,‏ macOS או Cloud Shell

   gcloud recaptcha keys create \
   --display-name=DISPLAY_NAME  \
   --android --package-names=PACKAGE_NAMES \
   --waf-feature=WAF_FEATURE \
   --waf-service=WAF_SERVICE 

   ‏Windows (PowerShell)

   gcloud recaptcha keys create `
   --display-name=DISPLAY_NAME  `
   --android --package-names=PACKAGE_NAMES `
   --waf-feature=WAF_FEATURE `
   --waf-service=WAF_SERVICE 

   Windows‏ (cmd.exe)

   gcloud recaptcha keys create ^
   --display-name=DISPLAY_NAME  ^
   --android --package-names=PACKAGE_NAMES ^
   --waf-feature=WAF_FEATURE ^
   --waf-service=WAF_SERVICE 

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

   ‫REST (iOS)

   הערה: יצירת מפתחות reCAPTCHA ל-WAF באפליקציות לנייד נתמכת רק בשילוב עם Cloud Armor. באינטגרציה הזו, אפשר ליצור רק מפתחות של טוקנים לפעולות באפליקציות לנייד.

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

   • ‫DISPLAY_NAME: שם המפתח. בדרך כלל שם האפליקציה.
   • ‫BUNDLE_IDs: מזהי החבילות של אפליקציות ל-iOS שמורשות להשתמש במפתח. אפשר לציין כמה מזהי חבילות כרשימה מופרדת בפסיקים.
   • ‫WAF_FEATURE: השם של התכונה ב-WAF. מציינים את action-token.
   • ‫WAF_SERVICE: השם של ספק שירותי ה-WAF. מציינים את CA ל-Cloud Armor.

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

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

   גוף בקשת JSON:

   {
     "displayName": "DISPLAY_NAME",
     "iosSettings": {
    "allowedBundleIds": "BUNDLE_IDS"
    },
      'wafSettings': "  {
          "wafService": "CA",
    "wafFeature": "ACTION_TOKEN"
     }
    }
   
   

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

   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/6LfhtywnAAAAABY3sCS2duZ6A55kmDXz-PNEgKgT",
     "displayName": "DISPLAY_NAME",
     "iosSettings": {
       "allowAllBundleIds": false,
       "allowedBundleIds": [
           BUNDLE_IDS
       ]
     },
     "labels": {},
     "wafSettings": {
         "wafService": "CA",
         "wafFeature": "ACTION_TOKEN"
     }
   }
   
   

   ‫REST (Android)

   הערה: יצירת מפתחות reCAPTCHA ל-WAF באפליקציות לנייד נתמכת רק בשילוב עם Cloud Armor. באינטגרציה הזו, אפשר ליצור רק מפתחות של טוקנים לפעולות באפליקציות לנייד.

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

   • ‫DISPLAY_NAME: שם המפתח. בדרך כלל שם האפליקציה.
   • ‫PACKAGE_NAMES: שמות החבילות של אפליקציות ל-Android שמורשות להשתמש במפתח. אפשר לציין כמה שמות של חבילות כרשימה מופרדת בפסיקים.
   • ‫WAF_FEATURE: השם של התכונה ב-WAF. מציינים את action-token.
   • ‫WAF_SERVICE: השם של ספק שירותי ה-WAF. מציינים את CA ל-Cloud Armor.

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

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

   גוף בקשת JSON:

   {
     "displayName": "DISPLAY_NAME",
     "androidSettings": {
     "allowedPackageNames":"PACKAGE_NAMES"
    },
      'wafSettings': "  {
          "wafService": "CA",
    "wafFeature": "ACTION_TOKEN"
     }
    }
   
   

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

   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/6LcioSknAAAAABrjlMuZv2fjIGYMqwaAFC9izhoy",
     "displayName": "DISPLAY_NAME",
     "androidSettings": {
         "allowAllPackageNames": false,
         "allowedPackageNames": [
             PACKAGE_NAMES
         ],
         "supportNonGoogleAppStoreDistribution": false
     },
     "labels": {},
     "wafSettings": {
         "wafService": "CA",
         "wafFeature": "ACTION_TOKEN"
     }
   }
   
   

2. משלבים את reCAPTCHA Mobile SDK באפליקציות לנייד עם מפתח action-token שיצרתם. הוראות מפורטות מופיעות במסמך שמתאים לסוג האפליקציה לנייד.

   • ל-Android, אפשר לעיין במאמר שילוב של Google Cloud Fraud Defense עם אפליקציות ל-Android.
   • לגבי iOS, אפשר לעיין במאמר בנושא שילוב של Google Cloud Fraud Defense עם אפליקציות ל-iOS.

3. אחרי שמקבלים את הטוקן מ-reCAPTCHA, מצרפים אותו לכותרת בקשה מוגדרת מראש בפורמט הבא:

   X-Recaptcha-Token: value-of-your-action-token
   

   בדוגמת קוד לדוגמה הבאה אפשר לראות איך לצרף את האסימון:

   Android

   קוד לדוגמה ב-Java

   // This example shows how to send an HTTP request to the backend server
   // attached with the reCAPTCHA token in the header.
   //
   // @param serverUrl: the URL of the backend server.
   // @param rceToken: reCAPTCHA token that is attached to the header of the
   // HTTP request.
   
   public static void sendRequestToServerWithRceToken(
       String serverUrl, String rceToken) throws JSONException, IOException {
    URL url = new URL(String.format("http://%s/decryptcaptchacookie/accesswafserver", serverUrl));
    HttpURLConnection connection = (HttpURLConnection) url.openConnection();
    connection.setRequestProperty("X-Recaptcha-Token", rceToken);
   
    try {
       String requestBody = "['']";
       sendRequest(connection, requestBody, "AccessWithRceToken", "GET");
    } finally {
       connection.disconnect();
    }
   }
   
   private static void sendRequest(
       HttpURLConnection connection, String requestString, String requestName, String action)
       throws IOException {
    connection.setConnectTimeout(HTTP_CONNECT_TIMEOUT_MS);
    connection.setReadTimeout(HTTP_READ_TIMEOUT_MS);
    connection.setRequestProperty("Content-type", CONTENT_TYPE);
    connection.setRequestProperty(
       "Content-Length", Integer.toString(Utf8.encodedLength(requestString)));
    connection.setRequestMethod(action);
    connection.setDoOutput(true);
    connection.connect();
    try (OutputStream postStream = connection.getOutputStream()) {
       postStream.write(requestString.getBytes(UTF_8));
    }
   
    int responseCode = connection.getResponseCode();
    String response = connection.getResponseMessage();
    if (responseCode != HttpURLConnection.HTTP_OK) {
       throw new IOException(
          String.format(
             "Failed to complete request.\nResponse code:%s\nError Detail:\n%s",
             responseCode, response));
    }
   }

   iOS

   קוד לדוגמה ב-Swift

   // This example shows how to send an HTTP request to the backend server
   // attached with the reCAPTCHA token in the header.
   // @param serverUrl: the URL of the backend server.
   // @param rceToken: reCAPTCHA token that is attached to the header of
   // the HTTP request.
   
    public static func accessWafServer(rceToken: String, serverUrl: String)
       async throws -> String
    {
       let requestURL = try HttpHelper.createRequestURL(endpoint: serverUrl)
       var request = try HttpHelper.createRequest(requestURL: requestURL, action: "GET")
       request.setValue(rceToken, forHTTPHeaderField: "X-Recaptcha-Token")
   
       let data = try await HttpHelper.getDataFromServer(request)
   
       return String(decoding: data, as: UTF8.self)
    }

הגדרת כללי מדיניות האבטחה של Cloud Armor

אחרי שמטמיעים את התכונות של reCAPTCHA for WAF, צריך להגדיר מדיניות אבטחה של Cloud Armor שמעריכה טוקנים של reCAPTCHA לניהול בוטים.

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

קבלת תוצאות reCAPTCHA

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

בדוגמה הבאה מוצגת כותרת לדוגמה של X-Recaptcha-Wafdata:

X-Recaptcha-Wafdata: waf_service="Google Cloud Armor", action_token;score=0.9\r\n

אפשר גם לראות את הציונים של reCAPTCHA ביומנים של Google Cloud Armor.

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

• הגדרת כללים לניהול בוטים