אסימוני אינטרנט JSON
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
אסימון JWT (JSON Web Token) הוא תקן אינטרנט פתוח שמשמש לאימות ולאישור של חילופי מידע בין לקוח לשרת. כשמשתמש באפליקציה נכנס בפעם הראשונה באמצעות פרטי הכניסה המתאימים לתפקיד, השרת יוצר JWT מקודד עם חתימה דיגיטלית ומחזיר אותו לשימוש בבקשות הבאות.
התהליך הזה מאמת את המשתמש ומאשר לו גישה למסלולים, לשירותים ולמשאבים על סמך התפקיד שלו בחשבון.
ב-Fleet Engine נדרש שימוש באסימוני JWT (JSON Web Tokens) לקריאות ל-API method מסביבות עם רמת אבטחה נמוכה: סמארטפונים ודפדפנים.
אסימון 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.
המאמרים הבאים
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-31 (שעון UTC).
[null,null,["עדכון אחרון: 2025-08-31 (שעון UTC)."],[[["\u003cp\u003eJSON Web Tokens (JWTs) are required for API calls to Fleet Engine from low-trust environments like smartphones and browsers, providing authentication and authorization.\u003c/p\u003e\n"],["\u003cp\u003eJWTs are digitally signed by a service account on your server, a trusted environment, and passed to the client for secure communication with Fleet Engine.\u003c/p\u003e\n"],["\u003cp\u003eJWTs contain header and claim sections with information about the private key, encryption algorithm, token lifespan, and authorized access scopes like vehicle or trip IDs.\u003c/p\u003e\n"],["\u003cp\u003eFleet Engine utilizes private claims within JWTs to ensure data security and limit access to specific resources based on assigned roles and vehicle or task IDs.\u003c/p\u003e\n"],["\u003cp\u003eUnlike API keys, JWTs are short-lived and restrict operations to those permitted by the associated service account role, enhancing security.\u003c/p\u003e\n"]]],[],null,["# JSON Web Tokens\n\nA JSON Web Token (JWT) is an open web standard that's used for authenticating\nand authorizing information exchanges between a client and a server. When an app\nuser first signs in with the appropriate role credentials, the server creates\nand returns an encoded, digitally-signed JWT for use with subsequent requests.\nThis process both authenticates the user and authorizes them to access routes,\nservices, and resources based on their account role.\n\nFleet Engine requires the use of **JSON Web Tokens** (JWTs) for API method calls\nfrom **low-trust environments**: smartphones and browsers.\n\nA JWT originates on your server, is signed, encrypted, and passed to the client\nfor subsequent server interactions until it expires or is no longer valid.\n\n**Key details**\n\n- Use [Application Default Credentials](https://google.aip.dev/auth/4110) to authenticate and authorize against Fleet Engine.\n- Use an appropriate service account to sign JWTs. See [Fleet Engine serviceaccount](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts#fleet_engine_service_account_roles) roles in **Fleet Engine Basics**.\n\nUnlike API keys, JWTs are short lived and limit operations to only those that\nthe role is authorized to perform. For more information on JWTs, see\n[JSON Web Tokens](https://en.wikipedia.org/wiki/JSON_Web_Token) on Wikipedia. For detail on access roles, see\n[Service account roles](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/service-accounts) in this guide.\n\nJWT elements\n------------\n\nJWTs contain a header and a claim section. The header section contains\ninformation such as the private key obtained from service accounts, and the\nencryption algorithm. The claim section contains information such as the JWT's\ncreate time, time to live, the services that the JWT claims\naccess to, and other authorization information to scope access; for\nexample, the delivery vehicle ID.\n\nThe following table provides descriptive details about JWT fields in general,\nas well as specific information about where you can find the values for these\nfields in your Fleet Engine Cloud project.\n\n| **Field** | **Description** |\n|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| alg | The algorithm to use. \\`RS256\\`. |\n| typ | The type of token. \\`JWT\\`. |\n| kid | Your service account's private key ID. You can find this value in the `private_key_id` field of your service account JSON file. Make sure to use a key from a service account with the correct level of permissions. |\n[JWT header fields]\n\n| **Field** | **Description** |\n|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| iss | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| sub | Your service account's email address, found in the `client_email` field of your service account JSON file. |\n| aud | Your service account's `SERVICE_NAME`, in this case `https://fleetengine.googleapis.com/` |\n| iat | The timestamp when the JWT was created, specified in seconds elapsed since 00:00:00 `UTC, January 1, 1970`. Allow 10 minutes for skew. If the timestamp is too far in the past, or in the future, the server might report an error. |\n| exp | The timestamp when the JWT expires, specified in seconds elapsed since `00:00:00 UTC, January 1, 1970`. The request fails if the timestamp is more than one hour in the future. |\n| authorization | Depending on the use case, may contain `deliveryvehicleid`, `trackingid`, `taskid`, or `taskids`. If specifying taskids, the authorization scope must be an array in one of the following forms: `\"taskids\": [\"task_id_one\",\"task_id_two\"]` or `\"taskids\": [\"*\"]` |\n[JWT claims fields]\n\n### Fleet Engine JWT claims\n\nFleet Engine uses private claims. Using private claims ensures that only\nauthorized clients can access their own data.\n\nFor example, when your server issues a JSON Web Token for a driver's mobile\ndevice, it should contain either the `vehicleid` claim or the\n`deliveryvehicleid` claim with the value of that driver's vehicle ID. Then,\ndepending on the driver role, JWTs enable access only for the specific vehicle\nID and not any other arbitrary vehicle ID.\n\nFleet Engine uses the following private claims: \n\n### On-demand trips\n\n- **`vehicleid`** :\n - The Driver SDK always uses this claim, whether operating on a trip or vehicle. The Fleet Engine backend assures that the vehicle is associated with the requested trip before doing the modification.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the JWT signing implementation.\n- **`tripid`** :\n - The Consumer SDK always uses this claim.\n - The JWT can cover both vehicle and trip operations, even if not required, which may simplify the token signing implementation.\n\n### Scheduled tasks\n\n- `deliveryvehicleid`\n\n Use when calling per-delivery-vehicle\n APIs.\n- `taskid`\n\n Use when calling per-task APIs.\n- `taskids`\n\n Use when calling\n `BatchCreateTasksAPI`. This claim must be in array form,\n and the array should contain all task IDs necessary to complete the\n request. Don't include `delivervehicleid`,\n `trackingid`, or `taskid` claims.\n- `trackingid`\n\n Use when calling the\n `GetTaskTrackingInfoAPI`. The claim must match the tracking\n ID in the request. Don't include `delivervehicleid`,\n `taskid`, or `taskids` claims.\n\nWhat's next\n-----------\n\n- Read about [Fleet Engine security design](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/security-design) to understand the complete authentication flow.\n- Learn how to [Issue JSON Web Tokens](/maps/documentation/mobility/fleet-engine/essentials/set-up-fleet/issue-jwt) from your server."]]
