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

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

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

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

לעומת זאת, הקצה העורפי צריך לבצע אימות והרשאה מול Fleet Engine באמצעות מנגנונים רגילים של Application Default Credentials.

בניגוד למפתחות 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": ["task_id_one","task_id_two"]

או

"taskids": ["*"]

הצהרות JWT של Fleet Engine

ב-Fleet Engine נעשה שימוש בהצהרות פרטיות. שימוש בטענות נכונות (claims) פרטיות מבטיח שרק ללקוחות מורשים תהיה גישה לנתונים שלהם.

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

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

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

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

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

  • deliveryvehicleid

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

  • taskid

    משתמשים באפשרות הזו כשקוראים לממשקי API לכל משימה.

  • taskids

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

  • trackingid

    משתמשים בה כשקוראים ל-GetTaskTrackingInfoAPI. התלונה צריכה להתאים למזהה המעקב שמופיע בבקשה. אסור לכלול הצהרות delivervehicleid,‏ taskid או taskids.

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