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

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

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

איך אסימוני JWT פועלים

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

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

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

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

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

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

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

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

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

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

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

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

  • כשיוצרים את המטען הייעודי (payload) של JWT, צריך להוסיף בקטע ההרשאה עוד הצהרה כשהמפתח 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 JavaScript:

  • חותמים על האסימון באמצעות התפקיד 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": "*"
       }
    }

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