הנפקת אסימוני אינטרנט מסוג JSON

במסמך הזה מוסבר איך להנפיק טוקנים של JSON Web כחלק מהפעלת הגישה של אפליקציות מבוססות אינטרנט ונייד לנתוני Fleet Engine. אם עדיין לא עשיתם את זה, כדאי לקרוא על טוקנים של JSON Web בקטע אבטחה ב-Fleet Engine. עם שירות Fleet Engine, אפשר להנפיק JWT באחת מהדרכים הבאות:

  • שימוש בספריית ההרשאות – Google ממליצה להשתמש בגישה הזו אם בסיס הקוד כתוב ב-Java. הספרייה הזו מטפלת בהנפקת JWT לכל תרחישי השימוש שנדרשים לכם בשירות, ומפשטת מאוד את ההטמעה.
  • יצירת אסימוני JWT משלכם – אם אתם לא יכולים להשתמש בספריית ה-JWT שלנו, תצטרכו ליצור אותם בבסיס הקוד שלכם. בקטע הזה מופיעות דוגמאות שונות ל-JWT לכל תרחיש.

איך פועלים JWT

בסביבות לא מהימנות, כמו טלפונים ניידים ודפדפני אינטרנט, שרת הבק-אנד שלכם מנפיק JWT שפועלים באופן הבא:

  • קוד הלקוח שפועל בסביבה עם רמת אמון נמוכה קורא לקוד השרת שפועל בסביבה עם רמת אמון מלאה כדי לבקש את ה-JWT המתאים להעברה ל-Fleet Engine.

  • אסימוני JWT משויכים לחשבונות שירות, כך שבקשות שנשלחות אל Fleet Engine משויכות באופן מרומז לחשבון השירות שחתם על ה-JWT.

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

שימוש בספריית ההרשאות ל-Java

כדי להשתמש בספריית ההרשאות של Fleet Engine ל-Java, אפשר לעבור אל מאגר GitHub. הספרייה מפשטת את יצירת ה-JWT של Fleet Engine ומבצעת חתימה מאובטחת שלהם. הוא מספק את האפשרויות הבאות:

  • הצהרות על תלות של הפרויקט במשאבים
  • רשימה מלאה של כל התפקידים בחשבון השירות לנסיעות לפי דרישה או למשימות מתוזמנות
  • מנגנוני חתימה על אסימונים שאינם מבוססים על שימוש בקובצי פרטי כניסה, כמו התחזות לחשבון שירות
  • מצרף אסימונים חתומים לבקשות יוצאות שנשלחות מ-stub של gRPC או מספריית לקוח של Google API Codegen ‏ (GAPIC)
  • הוראות לשילוב החותמים עם ספריות הלקוח של Fleet Engine

אם אתם מנפיקים JWTs מהקוד שלכם

אם אין לכם אפשרות להשתמש בספריית ההרשאות ל-Java, אתם צריכים להטמיע אסימוני JWT בבסיס הקוד שלכם. בקטע הזה אנחנו מפרטים כמה הנחיות ליצירת טוקנים משלכם. בקטע אבטחה ב-Fleet Engine מופיעה רשימה של שדות וטענות JWT. במאמר תפקידים בחשבון השירות מפורטים התפקידים בחשבון השירות שמשמשים את Fleet Engine. בקטע הבא מופיעה רשימה של דוגמאות ל-JWT לנסיעות לפי דרישה או למשימות מתוזמנות.

הנחיות כלליות

  • שימוש בחשבונות שירות ובתפקידים מתאימים. חשבון השירות והתפקיד המשויך מבטיחים שהמשתמש שמבקש את האסימון מורשה לצפות במידע שהאסימון מאפשר לו לגשת אליו. באופן ספציפי:
    • אם חותמים על JWT כדי להעביר אותו למכשיר נייד, משתמשים בחשבון השירות לתפקיד Driver או Consumer SDK. אחרת, יכול להיות שיהיה אפשר לשנות את הנתונים במכשיר הנייד ולגשת אליהם, גם אם אין למכשיר הרשאה לגשת אליהם.
    • אם חותמים על ה-JWT כדי להשתמש בו לקריאות עם הרשאות, צריך להשתמש בחשבון השירות עם תפקיד האדמין הנכון ב-Fleet Engine כשמשתמשים ב-ADC או ב-JWT. אחרת, הפעולה תיכשל.
  • משתפים רק את האסימונים שנוצרו. אף פעם אל תשתפו את פרטי הכניסה שבהם השתמשתם כדי ליצור את האסימונים.
  • במקרה של קריאות gRPC, המנגנון לצירוף האסימון תלוי בשפה ובמסגרת שבהן נעשה שימוש כדי לבצע את הקריאה. כדי לציין אסימון לקריאת HTTP, צריך לכלול כותרת Authorization עם אסימון bearer שהערך שלו הוא האסימון.
  • החזרת מועד התפוגה. השרת צריך להחזיר מועד תפוגה עבור הטוקן, בדרך כלל בשניות.
  • אם אתם צריכים ליצור ולחתום על JSON ישירות כנושא אסימון, במקום להשתמש באסימוני גישה מסוג OAuth 2.0, תוכלו לקרוא את ההוראות בנושא הרשאה של חשבון שירות ללא OAuth במסמכי התיעוד למפתחים בנושא זהויות.

לנסיעות לפי דרישה

  • כשיוצרים את מטען ה-JWT, מוסיפים תביעה נוספת בקטע authorization עם המפתח vehicleid או tripid שמוגדר לערך של מזהה הרכב או מזהה הנסיעה שעבורם מתבצעת הקריאה.

למשימות מתוזמנות

  • כששרת קורא לממשקי API אחרים, האסימונים צריכים לכלול גם את הטענה המתאימה. כדי לעשות את זה, אפשר לבצע את הפעולות הבאות:
    • מגדירים את הערך של כל מפתח ל-*.
    • נותנים למשתמש גישה לכל taskids ולכל deliveryvehicleids. כדי לעשות את זה, מוסיפים טענה נוספת בקטע ההרשאה עם המפתחות taskid ו-deliveryvehicleid.
    • כשמשתמשים בכוכבית (*) בטענה taskids, היא צריכה להיות הרכיב היחיד במערך.

דוגמאות ל-JWT לנסיעות על פי דרישה

בקטע הזה מופיעות דוגמאות ל-JWT לתרחישים נפוצים אם אתם משתמשים בנסיעות על פי דרישה.

דוגמה לטוקן של פעולה באפליקציית נהג

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

דוגמה לטוקן של פעולה באפליקציה למשתמשים

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

דוגמאות ל-JWT למשימות מתוזמנות

בקטע הזה מופיעה דוגמה ל-JWT לתרחישים אופייניים אם משתמשים במשימות מתוזמנות.

דוגמה לטוקן של אפליקציית נהג

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_driver_service_account"
    }
    .
    {
      "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
      "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "driver_12345"
       }
    }

דוגמה לטוקן של אפליקציה למשתמשים

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_consumer_service_account"
    }
    .
    {
      "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

דוגמאות ל-JWT לפעולות בצי

בקטע הזה מופיעה דוגמה ל-JWT לתרחיש אופייני בפעולות של Fleet.

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

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

  • חתימה על האסימון באמצעות תפקיד Fleet Engine Delivery Fleet Reader Cloud IAM.

   {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_consumer_service_account"
    }
    .
    {
      "iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "scope": "https://www.googleapis.com/auth/xapi",
      "authorization": {
         "taskid": "*",
         "deliveryvehicleid": "*",
       }
    }

שיטת אימות חלופית לפעולות בשרת העורפי

‫Google ממליצה להשתמש ב-ADC כדי לאמת פעולות של שרתים בעורף המערכת. אם אי אפשר להשתמש ב-ADC וצריך להשתמש ב-JWT, אפשר להיעזר בדוגמאות האלה.

טוקן לדוגמה לפעולה בשרת קצה עורפי על פי דרישה

  {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "private_key_id_of_provider_service_account"
  }

  {
    "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
    "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
    "aud": "https://fleetengine.googleapis.com/",
    "iat": 1511900000,
    "exp": 1511903600,
    "authorization": {
       "vehicleid": "*",
       "tripid": "*"
     }
  }

אסימון לדוגמה לפעולה מתוזמנת בשרת קצה עורפי

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }

דוגמה לטוקן של פעולת יצירת משימות באצווה בשרת קצה עורפי מתוזמן

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }

טוקן לדוגמה לפעולה מתוזמנת של שרת קצה עורפי לכל כלי רכב למסירה

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "*"
       }
    }

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