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

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

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

نحوه کار JWTها

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • وقتی سرور شما API های دیگر را فراخوانی می‌کند، توکن‌ها نیز باید حاوی claim (ادعای) مناسب باشند. برای این کار می‌توانید موارد زیر را انجام دهید:
    • مقدار هر کلید را روی * تنظیم کنید.
    • به کاربر دسترسی به همه taskids و deliveryvehicleids را اعطا کنید. برای انجام این کار، یک Claim اضافی در بخش مجوز با کلیدهای 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 برای یک سناریوی معمول در عملیات ناوگان ارائه می‌دهد.

توکن نمونه برای ردیابی تمام وظایف و وسایل نقلیه در یک ناوگان

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

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

   {
      "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": "*",
       }
    }

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

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

توکن نمونه برای عملیات سرور backend بر اساس تقاضا 

  {
    "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": "*"
     }
  }

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

    {
      "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": "*"
       }
    }

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

    {
      "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": ["*"]
       }
    }

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

    {
      "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ها برای عملیات سرور backend، به نمای کلی امنیت مراجعه کنید.