אסימוני אינטרנט JSON

אסימון JWT‏ (JSON Web Token) הוא תקן אינטרנט פתוח שמשמש לאימות ולאישור של חילופי מידע בין לקוח לשרת. כשמשתמש באפליקציה נכנס בפעם הראשונה באמצעות פרטי הכניסה המתאימים לתפקיד, השרת יוצר JWT מקודד עם חתימה דיגיטלית ומחזיר אותו לשימוש בבקשות הבאות. במהלך התהליך הזה, המשתמש מאומת ומקבל הרשאה לגשת למסלולים, לשירותים ולמשאבים על סמך התפקיד שלו בחשבון.

ב-Fleet Engine נדרש שימוש באסימוני JWT (‏JSON Web Tokens) לקריאות לשיטות API מסביבות עם רמת אבטחה נמוכה: סמארטפונים ודפדפנים.

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

פרטים חשובים

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

רכיבי JWT

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

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

שדות הכותרת של JWT

שדה

תיאור

alg

האלגוריתם שבו יש להשתמש. ‫`RS256`.

typ

סוג האסימון. ‫`JWT`.

ילד/ה

המזהה של המפתח הפרטי של חשבון השירות. אפשר למצוא את הערך הזה בשדה private_key_id בקובץ ה-JSON של חשבון השירות. חשוב להשתמש במפתח מחשבון שירות עם רמת ההרשאות הנכונה.
שדות של הצהרות JWT

שדה

תיאור

iss

כתובת האימייל של חשבון השירות, שמופיעה בשדה client_email בקובץ ה-JSON של חשבון השירות.

sub

כתובת האימייל של חשבון השירות, שמופיעה בשדה client_email בקובץ ה-JSON של חשבון השירות.

aud

ערך המדד SERVICE_NAME של חשבון השירות, במקרה הזה https://fleetengine.googleapis.com/

IAT

חותמת הזמן שבה נוצר ה-JWT, שמוגדרת בשניות שחלפו מאז 00:00:00 UTC, January 1, 1970. ההטיה נמשכת 10 דקות. אם חותמת הזמן רחוקה מדי בעבר או בעתיד, יכול להיות שהשרת ידווח על שגיאה.

exp

חותמת הזמן שבה יפוג תוקף ה-JWT, בשניות שחלפו מאז 00:00:00 UTC, January 1, 1970. הבקשה תיכשל אם חותמת הזמן תהיה יותר משעה קדימה.

הרשאה

בהתאם לתרחיש השימוש, יכול להיות שהמאפיין יכיל את הערכים deliveryvehicleid, trackingid, taskid או taskids.

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

"taskids": ["task_id_one","task_id_two"]

או

"taskids": ["*"]

טענות JWT ב-Fleet Engine

‫Fleet Engine משתמש בטענות פרטיות. שימוש בטענות פרטיות מבטיח שרק לקוחות מורשים יוכלו לגשת לנתונים שלהם.

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

‫Fleet Engine משתמש בהצהרות הפרטיות הבאות:

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

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

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

  • deliveryvehicleid

    השימוש הוא כשקוראים לממשקי API של כלי רכב למשלוחים.

  • taskid

    משתמשים בו כשמפעילים ממשקי API לכל משימה.

  • taskids

    שימוש ב-BatchCreateTasksAPI לשיחות. התביעה הזו צריכה להיות בפורמט של מערך, והמערך צריך להכיל את כל מזהי המשימות שנדרשים להשלמת הבקשה. אל תכללו טענות לגבי delivervehicleid, trackingid או taskid.

  • trackingid

    כדאי להשתמש בקידומת הזו כשמתקשרים למספר GetTaskTrackingInfoAPI. המזהה שמופיע בבקשה חייב להיות זהה למזהה המעקב שמופיע בבקשה. אל תכללו טענות לגבי delivervehicleid, taskid או taskids.

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