JSON Web Tokens

توکن وب JSON (JWT) یک استاندارد وب باز است که برای احراز هویت و مجوز تبادل اطلاعات بین کلاینت و سرور استفاده می‌شود. هنگامی که یک کاربر برنامه برای اولین بار با اعتبارنامه‌های نقش مناسب وارد سیستم می‌شود، سرور یک JWT رمزگذاری شده و دارای امضای دیجیتالی را برای استفاده در درخواست‌های بعدی ایجاد و ارسال می‌کند. این فرآیند هم کاربر را احراز هویت می‌کند و هم به آنها اجازه می‌دهد تا بر اساس نقش حساب کاربری خود به مسیرها، سرویس‌ها و منابع دسترسی داشته باشند.

موتور ناوگان (Fleet Engine) برای فراخوانی متدهای API از محیط‌های کم‌اعتماد (مثل تلفن‌های هوشمند و مرورگرها) نیاز به استفاده از توکن‌های وب JSON (JWT) دارد.

یک JWT از سرور شما سرچشمه می‌گیرد، امضا و رمزگذاری می‌شود و برای تعاملات بعدی با سرور به کلاینت ارسال می‌شود تا زمانی که منقضی شود یا دیگر معتبر نباشد.

جزئیات کلیدی

برخلاف کلیدهای API، JWTها کوتاه‌مدت هستند و عملیات را فقط به مواردی محدود می‌کنند که نقش مجاز به انجام آنها است. برای اطلاعات بیشتر در مورد JWTها، به JSON Web Tokens در ویکی‌پدیا مراجعه کنید. برای جزئیات بیشتر در مورد نقش‌های دسترسی، به نقش‌های حساب سرویس در این راهنما مراجعه کنید.

عناصر JWT

JWTها شامل یک سربرگ و یک بخش Claim هستند. بخش Header شامل اطلاعاتی مانند کلید خصوصی به دست آمده از حساب‌های سرویس و الگوریتم رمزگذاری است. بخش Claim شامل اطلاعاتی مانند زمان ایجاد JWT، زمان حیات، سرویس‌هایی که JWT ادعای دسترسی به آنها را دارد و سایر اطلاعات مجوز برای دسترسی به محدوده؛ به عنوان مثال، شناسه وسیله نقلیه تحویل است.

جدول زیر جزئیات توصیفی در مورد فیلدهای JWT به طور کلی، و همچنین اطلاعات خاصی در مورد محل یافتن مقادیر این فیلدها در پروژه Fleet Engine Cloud شما ارائه می‌دهد.

فیلدهای هدر JWT

میدان

توضیحات

الج

الگوریتم مورد استفاده. `RS256`.

تایپ

نوع توکن. `JWT`.

بچه

شناسه کلید خصوصی حساب سرویس شما. می‌توانید این مقدار را در فیلد private_key_id فایل JSON حساب سرویس خود پیدا کنید. مطمئن شوید که از کلیدی از یک حساب سرویس با سطح مجوزهای صحیح استفاده می‌کنید.

JWT فیلدهای مورد نیاز را ادعا می‌کند

میدان

توضیحات

ایس

آدرس ایمیل حساب سرویس شما، که در فیلد client_email فایل JSON حساب سرویس شما یافت می‌شود.

فرعی

آدرس ایمیل حساب سرویس شما، که در فیلد client_email فایل JSON حساب سرویس شما یافت می‌شود.

آد

SERVICE_NAME حساب سرویس شما، در این مورد https://fleetengine.googleapis.com/

آی تی

مهر زمانی هنگام ایجاد JWT، که بر حسب ثانیه از ساعت 00:00:00 UTC, January 1, 1970 گذشته است، مشخص می‌شود. 10 دقیقه برای انحراف در نظر بگیرید. اگر مهر زمانی خیلی مربوط به گذشته یا آینده باشد، ممکن است سرور خطایی گزارش دهد.

تاریخ انقضا

مهر زمانی که JWT منقضی می‌شود، که بر حسب ثانیه از 00:00:00 UTC, January 1, 1970 گذشته است، مشخص می‌شود. اگر مهر زمانی بیش از یک ساعت در آینده باشد، درخواست ناموفق خواهد بود.

مجوز

بسته به مورد استفاده، ممکن است حاوی deliveryvehicleid ، trackingid ، taskid یا taskids باشد.

در صورت مشخص کردن taskidها، محدوده مجوز باید یک آرایه به یکی از شکل‌های زیر باشد:

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

یا

"taskids": ["*"]

ادعاهای JWT در مورد موتور ناوگان

موتور ناوگان از ادعاهای خصوصی استفاده می‌کند. استفاده از ادعاهای خصوصی تضمین می‌کند که فقط مشتریان مجاز می‌توانند به داده‌های خود دسترسی داشته باشند.

برای مثال، وقتی سرور شما یک JSON Web Token برای دستگاه تلفن همراه راننده صادر می‌کند، باید شامل یا ادعای vehicleid یا ادعای deliveryvehicleid با مقدار شناسه وسیله نقلیه آن راننده باشد. سپس، بسته به نقش راننده، JWTها فقط دسترسی را برای شناسه وسیله نقلیه خاص و نه هیچ شناسه وسیله نقلیه دلخواه دیگری فعال می‌کنند.

موتور ناوگان از ادعاهای خصوصی زیر استفاده می‌کند:

سفرهای درخواستی

  • vehicleid :
    • درایور SDK همیشه از این ادعا استفاده می‌کند، چه در حال رانندگی در سفر باشد و چه در حال رانندگی در وسیله نقلیه. بخش پشتیبانی Fleet Engine قبل از انجام اصلاحات، اطمینان حاصل می‌کند که وسیله نقلیه با سفر درخواستی مرتبط است.
    • JWT می‌تواند عملیات مربوط به وسیله نقلیه و سفر را پوشش دهد، حتی اگر مورد نیاز نباشد، که این امر می‌تواند پیاده‌سازی امضای JWT را ساده‌تر کند.
  • tripid :
    • SDK مصرف‌کننده همیشه از این ادعا استفاده می‌کند.
    • JWT می‌تواند عملیات مربوط به وسیله نقلیه و سفر را پوشش دهد، حتی اگر مورد نیاز نباشد، که این امر می‌تواند پیاده‌سازی امضای توکن را ساده‌تر کند.

وظایف برنامه‌ریزی‌شده

  • deliveryvehicleid

    هنگام فراخوانی APIهای مربوط به هر وسیله نقلیه تحویلی، از این مورد استفاده کنید.

  • taskid

    هنگام فراخوانی APIهای هر وظیفه، از آن استفاده کنید.

  • taskids

    هنگام فراخوانی BatchCreateTasksAPI استفاده شود. این ادعا باید به صورت آرایه باشد و آرایه باید شامل تمام شناسه‌های وظیفه لازم برای تکمیل درخواست باشد. ادعاهای delivervehicleid ، trackingid یا taskid را وارد نکنید.

  • trackingid

    هنگام فراخوانی GetTaskTrackingInfoAPI استفاده شود. claim باید با tracking ID موجود در درخواست مطابقت داشته باشد. claim های delivervehicleid ، taskid یا taskids را وارد نکنید.

قدم بعدی چیست؟