שימוש ב-App Check כדי לאבטח את מפתח ה-API

Firebase App Check מספק הגנה לשיחות מהאפליקציה שלכם אל הפלטפורמה של מפות Google על ידי חסימת תנועה שמגיעה ממקורות אחרים מלבד אפליקציות לגיטימיות. הבדיקה מתבצעת על ידי חיפוש טוקן מספק אימות כמו App Attest. שילוב של האפליקציות עם App Check עוזר להגן מפני בקשות זדוניות, כך שלא תחויבו על קריאות לא מורשות ל-API.

האם App Check מתאים לי?

ברוב המקרים מומלץ להשתמש ב-App Check, אבל אין צורך להשתמש בו או שהוא לא נתמך במקרים הבאים:

• אתם משתמשים בגרסה המקורית של Places SDK. יש תמיכה ב-App Check רק ב-Places SDK (חדש).
• אפליקציות פרטיות או ניסיוניות. אם האפליקציה שלכם לא נגישה לציבור, אין צורך ב-App Check.
• אם האפליקציה שלכם משמשת רק לתקשורת שרת-לשרת, אין צורך ב-App Check. עם זאת, אם השרת שמתקשר עם GMP משמש לקוחות ציבוריים (כמו אפליקציות לנייד), מומלץ להשתמש ב-App Check כדי להגן על השרת הזה במקום ב-GMP.
• ספקי האימות המומלצים של App Check לא יפעלו במכשירים שהוגדרו כפרוצים או לא מהימנים על ידי ספק האימות. אם אתם צריכים לתמוך במכשירים כאלה, אתם יכולים לפרוס שירות אימות מותאם אישית. מידע נוסף זמין בהוראות.

סקירה כללית של שלבי ההטמעה

באופן כללי, אלה השלבים שצריך לבצע כדי לשלב את האפליקציה עם App Check:

1. מוסיפים את Firebase לאפליקציה.
2. מוסיפים את ספריית App Check ומפעילים אותה.
3. מוסיפים את ספק הטוקנים לאפליקציה.
4. מפעילים את ממשקי ה-API של Places ו-App Check.
5. מפעילים את ניפוי הבאגים.
6. מעקב אחרי בקשות האפליקציה והחלטה לגבי אכיפה.

אחרי שתבצעו שילוב עם App Check, תוכלו לראות את מדדי התנועה של ה-Backend במסוף Firebase. המדדים האלה מספקים פירוט של הבקשות לפי השאלה אם הן מלוות בטוקן App Check תקין. מידע נוסף זמין במסמכי התיעוד של Firebase App Check.

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

שיקולים בתכנון שילוב של בדיקת אפליקציות

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

• ספקי האימות המומלצים שלנו, Device Check או App Attest, כפופים למכסות ולמגבלות שנקבעו על ידי Apple.

  אתם יכולים לבחור להשתמש בספק אימות מותאם אישית, אבל זהו תרחיש שימוש מתקדם. מידע נוסף זמין במסמכי התיעוד של Firebase App Check.

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

  משך הזמן שבו הטוקן של App Check תקף (אורך החיים, או TTL) קובע את תדירות האימותים מחדש. אפשר להגדיר את משך הזמן הזה במסוף Firebase. האימות מחדש מתבצע אחרי שעובר בערך חצי מהזמן שמוגדר ל-TTL. למידע נוסף, אפשר לעיין במסמכי Firebase של ספק האימות שלכם.

שילוב האפליקציה עם App Check

דרישות מוקדמות

• אפליקציה עם Places SDK בגרסה 9.2 ואילך.
• מזהה החבילה של האפליקציה.
• מזהה הצוות שלכם ממרכז החברים של אפל, בקטע Membership (חברות).
• אם אתם מתכננים להשתמש ב-Device Check, תצטרכו את קובץ המפתח הפרטי ואת מזהה המפתח.
• אתם צריכים להיות הבעלים של האפליקציה ב-Cloud Console.
• תצטרכו את מזהה הפרויקט של האפליקציה מ-Cloud Console.

שלב 1: מוסיפים את Firebase לאפליקציה

פועלים לפי ההוראות במסמכי התיעוד למפתחים של Firebase כדי להוסיף את Firebase לאפליקציה.

כשרושמים את האפליקציה, מקבלים קובץ תצורה, GoogleService-Info.plist. מוסיפים את הקובץ הזה, ללא שינוי, לרמת הבסיס של האפליקציה.

import FirebaseCore
import FirebaseAppCheck
import GooglePlacesSwift

import FirebaseCore
import FirebaseAppCheck
import GooglePlaces

@import FirebaseCore;      
@import FirebaseAppCheck;
@import GooglePlaces;

שלב 2: מוסיפים את ספריית App Check ומפעילים את App Check

ב-Firebase יש הוראות לכל ספק אימות ברירת מחדל. במאמר הזה מוסבר איך להגדיר פרויקט Firebase ולהוסיף את ספריית App Check לאפליקציה. כדי לאתחל את App Check, צריך לפעול לפי דוגמאות הקוד שמופיעות כאן.

1. פועלים לפי ההוראות של Firebase כדי להוסיף את ספריית App Check:
   • הוראות לשימוש ב-App Attest
   • הוראות לבדיקת המכשיר
2. מפעילים את App Check.
   • אם אתם משתמשים ב-App Attest, אתם צריכים לפעול לפי מסמכי התיעוד למפתחים של Firebase בנושא App Attest.

     פועלים לפי ההוראות להטמעה של Firebase App Check כדי ליצור הטמעה של AppCheckProviderFactory ולהוסיף אותה לקובץ AppDelegate.

     Places Swift SDK ל-iOS

     let providerFactory = YourAppCheckProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)

     Swift

     let providerFactory = YourAppCheckProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)

     Objective-C

     YourAppCheckProviderFactory *providerFactory =
         [[YourAppCheckProviderFactory alloc] init];
     [FIRAppCheck setAppCheckProviderFactory:providerFactory];
        

   • אם אתם משתמשים ב-Device Check, מוסיפים את הקוד הבא ל-AppDelegate:

     Places Swift SDK ל-iOS

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

     [FIRAppCheck setAppCheckProviderFactory:providerFactory];
           

שלב 3: מוסיפים את ספק הטוקנים

יוצרים קובץ בשם AppCheckTokenProvider (או, אם משתמשים ב-Objective-C, שני קבצים בשם AppCheckTokenProvider.h ו-AppCheckTokenProvider.m) ברמת השורש של האפליקציה. מוסיפים את הצהרות הייבוא והגדרת המחלקה הבאות:

// AppCheckTokenProvider.swift

import FirebaseAppCheck
import Foundation
import GooglePlacesSwift
      
struct TokenProvider: AppCheckTokenProvider {
  func fetchAppCheckToken() async throws -> String {
    return try await AppCheck.appCheck().token(forcingRefresh: false).token
  }
}
      

// AppCheckTokenProvider.swift

import FirebaseAppCheck
import Foundation
import GooglePlaces

class AppCheckTokenProvider: NSObject, GMSPlacesAppCheckTokenProvider {
  func fetchAppCheckToken() async throws -> String {
    return try await AppCheck.appCheck().token(forcingRefresh: false).token
  }
}

// AppCheckTokenProvider.h

@import Foundation;
@import GooglePlaces;

@interface AppCheckTokenProvider : NSObject <GMSPlacesAppCheckTokenProvider>
@end

// AppCheckTokenProvider.m

#import "AppCheckTokenProvider.h"

@import FirebaseAppCheck;

@implementation AppCheckTokenProvider

- (void)fetchAppCheckTokenWithCompletion:(nonnull GMSAppCheckTokenCompletion)completion {
  [[FIRAppCheck appCheck]
      tokenForcingRefresh:NO
               completion:^(FIRAppCheckToken *_Nullable token, NSError *_Nullable error) {
                 if (token) {
                   completion(token.token, nil);
                 } else {
                   completion(nil, error);
                 }
               }];
}

@end

שלב 4: מאתחלים את ממשקי ה-API של Places ו-App Check

1. בקובץ AppDelegate, מאתחלים את Places API:

   Places Swift SDK ל-iOS

   PlacesClient.provideAPIKey("YOUR_API_KEY")

   Swift

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

   Objective-C

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

2. לאחר מכן, מאתחלים את App Check API:

   Places Swift SDK ל-iOS

   PlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

   Swift

   GMSPlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

   Objective-C

   [GMSPlacesClient setAppCheckTokenProvider:[[AppCheckTokenProvider alloc] init]];

שלב 5: הפעלת ניפוי באגים (אופציונלי)

אם אתם רוצים לפתח ולבדוק את האפליקציה באופן מקומי, או להריץ אותה בסביבת שילוב רציף (CI), אתם יכולים ליצור גרסת build לניפוי באגים של האפליקציה שמשתמשת בסוד לניפוי באגים כדי לקבל אסימונים תקפים של App Check. כך תוכלו להימנע משימוש בספקי אימות אמיתיים בגרסת הניפוי שלכם.

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

• יוצרים ומגדירים את מפעל ספקי הניפוי באגים של App Check.

  דוגמת הקוד הזו מטפלת בתרחישי ניפוי הבאגים ובתרחישי הייצור:

  Places Swift SDK ל-iOS

  #if targetEnvironment(simulator)
        let providerFactory = AppCheckDebugProviderFactory()
  #else
        let providerFactory = YourAppCheckProviderFactory()
  #endif

  Swift

  #if targetEnvironment(simulator)
        let providerFactory = AppCheckDebugProviderFactory()
  #else
        let providerFactory = YourAppCheckProviderFactory()
  #endif

  Objective-C

  if (targetEnvironment == simulator){
  
  FIRAppCheckDebugProviderFactory *providerFactory =
        [[FIRAppCheckDebugProviderFactory alloc] init];
  [FIRAppCheck setAppCheckProviderFactory:providerFactory];
  }
  
  else {
  
  YourAppCheckProviderFactory *providerFactory =
        [[YourAppCheckProviderFactory alloc] init];
  [FIRAppCheck setAppCheckProviderFactory:providerFactory];
  }
      

• מפעילים את הרישום ביומן בפרויקט Xcode, מפעילים את האפליקציה ומחפשים את אסימון הניפוי באגים המקומי ביומן.
• מוסיפים את הטוקן למסוף Firebase.
• מידע נוסף והוראות זמינים במאמרי העזרה בנושא App Check.

כדי להריץ את האפליקציה בסביבת CI:

• יוצרים אסימון לניפוי באגים במסוף Firebase ומוסיפים אותו למאגר המפתחות המאובטח של מערכת ה-CI.
• ב-Xcode, מוסיפים משתנה סביבה לתוכנית הבדיקה עם השם FIRAAppCheckDebugToken והערך $(APP_CHECK_DEBUG_TOKEN) (או ערך דומה).
• בסקריפט הבדיקה של CI, מעבירים את אסימון ניפוי הבאגים כסביבה

• יוצרים ומגדירים את מפעל ספקי הניפוי באגים של App Check.

  דוגמת הקוד הזו מטפלת בתרחישי ניפוי הבאגים ובתרחישי הייצור:

  Places Swift SDK ל-iOS

  #if DEBUG
    let providerFactory = AppCheckDebugProviderFactory()
  #else
    let providerFactory = YourAppCheckProviderFactory()
  #endif
  AppCheck.setAppCheckProviderFactory(providerFactory)
    

  Swift

  #if DEBUG
    let providerFactory = AppCheckDebugProviderFactory()
  #else
    let providerFactory = YourAppCheckProviderFactory()
  #endif
  AppCheck.setAppCheckProviderFactory(providerFactory)
    

  Objective-C

  #if DEBUG
  id<FIRAppCheckProviderFactory> providerFactory =
      [[FIRAppCheckDebugProviderFactory alloc] init];
  #else  // DEBUG
  id<FIRAppCheckProviderFactory> providerFactory =
      [[YourAppCheckProviderFactory alloc] init];
  #endif  // DEBUG
  AppCheck.setAppCheckProviderFactory(providerFactory)

• מידע נוסף והוראות זמינים במאמרי העזרה בנושא App Check.

שלב 6: מעקב אחרי בקשות האפליקציה והחלטה לגבי אכיפה

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

מידע נוסף והוראות מופיעים במסמכי התיעוד של Firebase App Check.