הנפקת אסימוני אינטרנט מסוג 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 וחותמת עליהם בצורה מאובטחת. הוא מספק את האפשרויות הבאות:

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

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

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

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

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

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

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

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

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

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

בדוגמה הבאה מוצג אסימון שעוקב אחרי כל המשימות וכלי הרכב בצי מאפליקציה מבוססת-אינטרנט שמשמשת את המפעיל. ההרשאות שנדרשות לפעולות האלה גדולות יותר מההרשאות שנדרשות לאפליקציות לקוח. במאמר הגדרת ספריית 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": "*"
       }
    }

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