صدور «کدهای وب JSON»

این سند نحوه صدور JSON Web Tokens را به‌عنوان بخشی از فعال کردن دسترسی برنامه‌های مبتنی بر وب و تلفن همراه شما به داده‌های Fleet Engine پوشش می‌دهد. اگر قبلاً این کار را نکرده‌اید، JSON Web Tokens را در بخش Security in Fleet Engine بخوانید. با سرویس Fleet Engine، می‌توانید JWT را به یکی از روش‌های زیر صادر کنید:

  • از کتابخانه مجوزدهی استفاده کنید—Google توصیه می‌کند وقتی پایگاه کدتان به زبان Java نوشته شده است، از این رویکرد استفاده کنید. این کتابخانه صدور JWT را برای همه سناریوهای مورداستفاده‌ای که ممکن است با این سرویس نیاز داشته باشید مدیریت می‌کند و پیاده‌سازی شما را بسیار ساده می‌کند.
  • JWT خودتان را ایجاد کنید—اگر نمی‌توانید از کتابخانه JWT ما استفاده کنید، باید این‌ها را در پایگاه کد خودتان بسازید. این بخش نمونه‌های مختلفی از JWT را برای هر سناریو ارائه می‌دهد.

نحوه عملکرد JWT

برای محیط‌های غیرقابل‌اعتماد، مانند تلفن‌های همراه و مرورگرهای وب، سرور زیرینه شما JWTهایی صادر می‌کند که به شرح زیر عمل می‌کنند:

  • کد کارخواه شما که در محیطی با اعتماد پایین اجرا می‌شود، کد سرور شما را که در محیطی کاملاً قابل‌اعتماد اجرا می‌شود فراخوانی می‌کند تا JWT مناسب را برای ارسال به Fleet Engine درخواست کند.

  • ‫JWTها با حساب‌های سرویس مرتبط هستند، بنابراین درخواست‌های ارسال‌شده به Fleet Engine به‌طور ضمنی با حساب سرویسی که JWT را امضا کرده است مرتبط هستند.

  • ادعاهای JWT منابعی را که کارخواه می‌تواند روی آن‌ها کار کند، مثل وسایل نقلیه، سفرها، یا تکالیف خاص، بیشتر محدود می‌کند.

استفاده از کتابخانه مجوز برای Java

برای استفاده از کتابخانه مجوز Fleet Engine برای Java، به مخزن GitHub مراجعه کنید. این کتابخانه ساخت JWTهای Fleet Engine را ساده می‌کند و آن‌ها را به‌طور ایمن امضا می‌کند. این مؤلفه موارد زیر را ارائه می‌دهد:

  • اعلامیه‌های وابستگی پروژه
  • فهرست کاملی از همه نقش‌های حساب سرویس برای سفرهای درخواستی یا تکالیف زمان‌بندی‌شده
  • سازوکارهای امضای کد به‌جز استفاده از فایل‌های اطلاعات کاربری، مثل جعل هویت حساب سرویس
  • توکن‌های امضاشده را به درخواست‌های خروجی که از یک خرد gRPC یا یک کتابخانه کارخواه Google API Codegen (GAPIC) ایجاد شده‌اند، پیوست می‌کند.
  • دستورالعمل‌های مربوط به ادغام امضاکنندگان با کتابخانه‌های کارخواه Fleet Engine

اگر از کدتان JWT صادر می‌کنید

اگر نمی‌توانید از کتابخانه مجوز برای Java استفاده کنید، باید JWT را در پایگاه کد خودتان پیاده‌سازی کنید. این بخش چند دستورالعمل برای ایجاد نشان‌های خودتان ارائه می‌دهد. برای مشاهده فهرست فیلدها و ادعاهای JWT، به JSON Web Tokens در بخش Security in Fleet Engine مراجعه کنید. برای نقش‌های حساب سرویس مورداستفاده Fleet Engine، به نقش‌های حساب سرویس مراجعه کنید. برای مشاهده فهرستی از نمونه‌های JWT برای سفرهای درخواستی یا تکالیف زمان‌بندی‌شده، بخش زیر را ببینید.

دستورالعمل‌های کلی

  • از حساب‌ها و نقش‌های سرویس مناسب استفاده کنید. حساب سرویس و نقش منسوب به آن تضمین می‌کند که کاربر درخواست‌کننده کد مجاز است اطلاعاتی را که کد به او اجازه دسترسی می‌دهد مشاهده کند. به‌طور مشخص:
    • اگر JWT را برای ارسال به دستگاه همراه امضا می‌کنید، از حساب سرویس برای نقش Driver SDK یا Consumer SDK استفاده کنید. درغیراین‌صورت، دستگاه همراه می‌تواند داده‌هایی را که نباید به آن‌ها دسترسی داشته باشد تغییر دهد و به آن‌ها دسترسی پیدا کند.
    • اگر JWT را برای استفاده در تماس‌های ممتاز امضا می‌کنید، هنگام استفاده از ADC یا JWT، از حساب سرویس با نقش صحیح «سرپرست Fleet Engine» استفاده کنید. درغیراین‌صورت، عملیات ناموفق خواهد بود.
  • فقط نشان‌های ایجادشده را هم‌رسانی کنید. هرگز اعتبارنامه‌های مورداستفاده برای ایجاد کردن توکن‌ها را هم‌رسانی نکنید.
  • برای تماس‌های gRPC، سازوکار پیوست کردن توکن به زبان و چارچوب استفاده‌شده برای برقراری تماس بستگی دارد. سازوکار مشخص کردن یک نشان برای تماس HTTP، شامل کردن یک سرصفحه Authorization با یک نشان دارنده است که مقدار آن نشان است.
  • زمان انقضا را برگردانید. سرور شما باید زمان انقضای توکن را برگرداند، معمولاً برحسب ثانیه.
  • اگر لازم است JSON را مستقیماً به‌عنوان دارنده کد ایجاد و امضا کنید، به‌جای استفاده از کد دسترسی OAuth 2.0، دستورالعمل‌های مجوز حساب سرویس بدون OAuth را در اسناد توسعه‌دهنده هویت بخوانید.

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

  • هنگام ایجاد بار داده JWT، یک ادعای اضافی در بخش مجوز با کلید vehicleid یا tripid تنظیم‌شده روی مقدار شناسه خودرو یا شناسه سفر که تماس برای آن برقرار می‌شود اضافه کنید.

برای تکالیف زمان‌بندی‌شده

  • وقتی سرور شما میاناهای برنامه‌سازی کاربردی دیگر را فراخوانی می‌کند، این توکن‌ها باید حاوی ادعای مناسب نیز باشند. برای این کار، می‌توانید موارد زیر را انجام دهید:
    • مقدار هر کلید را روی * تنظیم کنید.
    • به کاربر اجازه دهید به همه taskids و deliveryvehicleids دسترسی داشته باشد. برای انجام این کار، ادعای دیگری را در بخش مجوز با کلیدهای taskid و deliveryvehicleid اضافه می‌کنید.
    • هنگام استفاده از ستاره (*) در ادعای taskids، باید تنها عنصر در آرایه باشد.

نمونه‌های JWT برای سفرهای درخواستی

این بخش نمونه‌های JWT را برای سناریوهای رایج درصورت استفاده از سفرهای درخواستی ارائه می‌دهد.

نمونه کد برای عملکرد برنامه راننده

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_driver_service_account"
}
.
{
  "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
  "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "vehicleid": "driver_12345"
   }
}

نمونه کد برای عملیات برنامه مصرف‌کننده

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "private_key_id_of_consumer_service_account"
}
.
{
  "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
  "aud": "https://fleetengine.googleapis.com/",
  "iat": 1511900000,
  "exp": 1511903600,
  "authorization": {
     "tripid": "trip_54321"
   }
}

نمونه‌های JWT برای تکالیف زمان‌بندی‌شده

این بخش نمونه JWT را برای سناریوهای معمول درصورت استفاده از کارهای زمان‌بندی‌شده ارائه می‌دهد.

نمونه کد برای برنامه راننده

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_driver_service_account"
    }
    .
    {
      "iss": "driver@yourgcpproject.iam.gserviceaccount.com",
      "sub": "driver@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "driver_12345"
       }
    }

نمونه کد برای برنامه مصرف‌کننده

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_delivery_consumer_service_account"
    }
    .
    {
      "iss": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "sub": "consumer@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "trackingid": "shipment_12345"
       }
    }

نمونه‌های JWT برای عملیات ناوگان

این بخش یک نمونه JWT برای سناریوی معمول در عملیات ناوگان ارائه می‌دهد.

نمونه کد برای ردیابی همه تکالیف و خودروها در ناوگان

مثال زیر نشان‌دهنده توکنی است که همه تکالیف و وسایل نقلیه ناوگان را ازطریق برنامه تحت وب مورداستفاده اپراتور ردیابی می‌کند. اجازه‌های لازم برای این عملیات‌ها بیشتر از اجازه‌های لازم برای برنامه‌های کارخواه است. برای پیاده‌سازی سمت کارخواه که از این توکن استفاده می‌کند، راه‌اندازی کتابخانه ردیابی ناوگان جاوا اسکریپت را ببینید:

  • بااستفاده از نقش Fleet Engine Delivery Fleet Reader Cloud IAM، نشان را امضا کنید.

   {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_consumer_service_account"
    }
    .
    {
      "iss": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "sub": "superuser@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "scope": "https://www.googleapis.com/auth/xapi",
      "authorization": {
         "taskid": "*",
         "deliveryvehicleid": "*",
       }
    }

روش اصالت‌سنجی جایگزین برای عملیات سرور زیرینه

Google توصیه می‌کند برای اصالت‌سنجی کردن عملیات سرور زیرینه از ADC استفاده کنید. اگر نمی‌توانید از ADC استفاده کنید و باید از JWT استفاده کنید، به این نمونه‌ها مراجعه کنید.

نمونه کد برای عملیات سرور زیرینه درخواستی

  {
    "alg": "RS256",
    "typ": "JWT",
    "kid": "private_key_id_of_provider_service_account"
  }

  {
    "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
    "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
    "aud": "https://fleetengine.googleapis.com/",
    "iat": 1511900000,
    "exp": 1511903600,
    "authorization": {
       "vehicleid": "*",
       "tripid": "*"
     }
  }

نمونه کد برای عملیات سرور زیرینه زمان‌بندی‌شده

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskid": "*"
       }
    }

نمونه کد برای عملیات ایجاد دسته‌ای تکالیف زمان‌بندی‌شده سرور زیرینه

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "taskids": ["*"]
       }
    }

نمونه کد برای عملیات زمان‌بندی‌شده سرور زیرینه به‌ازای هر خودرو تحویل

    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "private_key_id_of_provider_service_account"
    }
    .
    {
      "iss": "provider@yourgcpproject.iam.gserviceaccount.com",
      "sub": "provider@yourgcpproject.iam.gserviceaccount.com",
      "aud": "https://fleetengine.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600,
      "authorization": {
         "deliveryvehicleid": "*"
       }
    }

قدم بعدی چیست