توکن های وب JSON را صادر کنید

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

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

JWT ها چگونه کار می کنند

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

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

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

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

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

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

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

اگر JWT ها را از کد خود صادر می کنید

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

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

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

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

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

برای کارهای برنامه ریزی شده

  • هنگامی که سرور شما API های دیگر را فراخوانی می کند، توکن ها نیز باید حاوی ادعای مناسب باشند. برای این کار می توانید کارهای زیر را انجام دهید:
    • مقدار هر کلید را روی * تنظیم کنید.
    • به کاربر اجازه دسترسی به تمام 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": "*",
       }
    }

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

گوگل توصیه می کند از 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": "*"
       }
    }

بعدش چی

  • تنظیمات خود را تأیید کنید تا بتوانید یک وسیله نقلیه آزمایشی ایجاد کنید و اطمینان حاصل کنید که توکن‌های شما طبق برنامه کار می‌کنند
  • برای اطلاعات در مورد استفاده از ADC به جای JWT برای عملیات سرور باطن، به نمای کلی امنیت مراجعه کنید.