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

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

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

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

פרטים חשובים

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

רכיבי JWT

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

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

שדות בכותרת ה-JWT

שדה

תיאור

alg

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

typ

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

ילד/ה

מזהה המפתח הפרטי של חשבון השירות. הערך הזה מופיע בשדה private_key_id בקובץ ה-JSON של חשבון השירות. חשוב להשתמש במפתח מחשבון שירות עם רמת ההרשאות הנכונה.
שדות של טענות נכונות (claims) ב-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": ["*"]

טענות נכונות (claims) של Fleet Engine JWT

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

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

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

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

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

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

  • deliveryvehicleid

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

  • taskid

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

  • taskids

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

  • trackingid

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

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