JSON Web Tokens
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
JSON Web Token (JWT) یک استاندارد وب باز است که برای احراز هویت و اجازه تبادل اطلاعات بین مشتری و سرور استفاده می‌شود. هنگامی که یک کاربر برنامه برای اولین بار با اعتبار نقش مناسب وارد سیستم می شود، سرور یک JWT رمزگذاری شده و با امضای دیجیتالی را برای استفاده در درخواست های بعدی ایجاد و برمی گرداند. این فرآیند هم کاربر را احراز هویت می کند و هم به آنها اجازه می دهد تا بر اساس نقش حساب کاربری خود به مسیرها، خدمات و منابع دسترسی داشته باشند.
Fleet Engine به استفاده از JSON Web Tokens (JWT) برای تماس‌های روش API از محیط‌های کم‌اعتماد : گوشی‌های هوشمند و مرورگرها نیاز دارد.
یک JWT در سرور شما ایجاد می شود، امضا می شود، رمزگذاری می شود و برای تعاملات بعدی سرور به مشتری ارسال می شود تا زمانی که منقضی شود یا دیگر معتبر نباشد.
جزئیات کلیدی
برخلاف کلیدهای API، JWT ها عمر کوتاهی دارند و عملیات را فقط به مواردی محدود می کنند که نقش مجاز به انجام آنها باشد. برای اطلاعات بیشتر در مورد JWT ها، به JSON Web Tokens در ویکی پدیا مراجعه کنید. برای جزئیات بیشتر در مورد نقش‌های دسترسی، نقش‌های حساب سرویس را در این راهنما ببینید.
عناصر JWT
JWT ها شامل یک هدر و یک بخش ادعا هستند. بخش هدر حاوی اطلاعاتی مانند کلید خصوصی به دست آمده از حساب های سرویس و الگوریتم رمزگذاری است. بخش ادعا شامل اطلاعاتی مانند زمان ایجاد JWT، زمان زندگی، خدماتی است که JWT ادعا می کند به آنها دسترسی دارد و سایر اطلاعات مجوز برای دسترسی به محدوده. به عنوان مثال، شناسه وسیله نقلیه تحویل.
جدول زیر جزئیات توصیفی در مورد فیلدهای JWT به طور کلی، و همچنین اطلاعات خاصی در مورد جایی که می توانید مقادیر این فیلدها را در پروژه Fleet Engine Cloud خود بیابید، ارائه می دهد.
فیلدهای هدر JWT میدان | توضیحات |
|---|
alg | الگوریتم مورد استفاده "RS256". |
تایپ کنید | نوع توکن "JWT". |
بچه | شناسه کلید خصوصی حساب سرویس شما. می توانید این مقدار را در قسمت private_key_id فایل JSON حساب سرویس خود بیابید. اطمینان حاصل کنید که از یک کلید از یک حساب سرویس با سطح صحیح مجوز استفاده می کنید. |
فیلدهای ادعایی JWT میدان | توضیحات |
|---|
iss | آدرس ایمیل حساب سرویس شما که در قسمت client_email فایل JSON حساب سرویس شما یافت می شود. |
فرعی | آدرس ایمیل حساب سرویس شما که در قسمت client_email فایل JSON حساب سرویس شما یافت می شود. |
aud | SERVICE_NAME حساب سرویس شما، در این مورد https://fleetengine.googleapis.com/ |
iat | مهر زمانی که JWT ایجاد شد، مشخص شده بر حسب ثانیه های سپری شده از ساعت 00:00:00 UTC, January 1, 1970 . 10 دقیقه برای کج شدن زمان بگذارید. اگر مهر زمانی در گذشته یا در آینده خیلی دور باشد، سرور ممکن است خطا را گزارش کند. |
انقضا | مهر زمانی که JWT منقضی می‌شود، مشخص شده بر حسب ثانیه از 00:00:00 UTC, January 1, 1970 . اگر مهر زمانی بیش از یک ساعت در آینده باشد، درخواست انجام نمی‌شود. |
مجوز | بسته به مورد استفاده، ممکن است حاوی deliveryvehicleid ، trackingid ، taskid یا taskids باشد. در صورت تعیین وظایف، محدوده مجوز باید یک آرایه به یکی از اشکال زیر باشد: "taskids": ["task_id_one","task_id_two"] یا "taskids": ["*"] |
Fleet Engine JWT ادعا می کند
Fleet Engine از ادعاهای خصوصی استفاده می کند. استفاده از ادعاهای خصوصی تضمین می کند که فقط مشتریان مجاز می توانند به داده های خود دسترسی داشته باشند.
برای مثال، وقتی سرور شما یک رمز وب 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 را شامل نشود.
بعدش چی
جز در مواردی که غیر از این ذکر شده باشد،محتوای این صفحه تحت مجوز Creative Commons Attribution 4.0 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده Oracle و/یا شرکتهای وابسته به آن است.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[[["\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."]]
