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

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

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

نحوه عملکرد JWT

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

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

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

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

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

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

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

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

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

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

  • از حساب‌های خدمات و نقش‌های مناسب استفاده کنید. حساب سرویس و نقش منسوب تضمین می‌کند که کاربری که درخواست کد می‌کند برای مشاهده اطلاعاتی که کد به او اجازه دسترسی می‌دهد مجاز است. به‌طور مشخص:
    • اگر درحال امضای JWT برای ارسال به دستگاه همراه هستید، از حساب سرویس برای نقش «کیت توسعه نرم‌افزار» راننده یا مصرف‌کننده استفاده کنید. درغیراین‌صورت، دستگاه همراه می‌تواند داده‌هایی را که نباید به آن‌ها دسترسی داشته باشد تغییر دهد و به آن‌ها دسترسی پیدا کند.
    • اگر 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": "*"
       }
    }

قدم بعدی چیست