إصدار رموز JSON المميّزة للويب

يتناول هذا المستند كيفية إصدار رموز JSON المميّزة للويب كجزء من منح تطبيقات الويب والتطبيقات المستندة إلى الأجهزة الجوّالة إذن الوصول إلى بيانات Fleet Engine. إذا لم يسبق لك ذلك ، يُرجى قراءة مقالة رموز JSON المميّزة للويب ضمن قسم الأمان في 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 في قاعدة الرموز البرمجية الخاصة بك. يقدّم هذا القسم بعض الإرشادات لإنشاء الرموز الخاصة بك. يُرجى الاطّلاع على رموز JSON المميّزة للويب ضمن قسم الأمان في Fleet Engine للحصول على قائمة بحقول وطلبات JWT. يُرجى الاطّلاع على أدوار حسابات الخدمة لمعرفة أدوار حسابات الخدمة التي يستخدمها Fleet Engine. يُرجى الاطّلاع على القسم التالي للحصول على قائمة بأمثلة على رموز JWT للرحلات عند الطلب أو المهام المُجدوَلة.

الإرشادات العامة

  • استخدام حسابات خدمة وأدوار مناسبة : يضمن حساب الخدمة والدور المرتبط به أنّ المستخدم الذي يطلب الرمز مسموح له بعرض المعلومات التي يمنحه الرمز إذن الوصول إليها. على وجه التحديد:
    • إذا كنت توقّع رمز JWT لتمريره إلى جهاز جوّال، استخدِم حساب الخدمة لدور حزمة تطوير البرامج (SDK) للسائق أو حزمة تطوير البرامج (SDK) للمستهلك. بخلاف ذلك، يمكن للجهاز الجوّال تغيير البيانات والوصول إليها بدون إذن.
    • إذا كنت توقّع رمز JWT لاستخدامه في طلبات مميّزة، استخدِم حساب الخدمة الذي لديه دور مشرف Fleet Engine الصحيح عند استخدام "بيانات الاعتماد التلقائية للتطبيق" (ADC) أو رموز JWT. بخلاف ذلك، ستفشل العملية.
  • مشاركة الرموز التي تم إنشاؤها فقط : يجب عدم مشاركة بيانات الاعتماد المستخدَمة لإنشاء الرموز أبدًا.
  • بالنسبة إلى طلبات gRPC، تعتمد آلية إرفاق الرمز على اللغة والإطار المستخدَمَين لإجراء الطلب. آلية تحديد رمز لطلب HTTP هي تضمين عنوان Authorization يتضمّن رمزًا مميّزًا لحامل الإذن تكون قيمته هي الرمز.
  • عرض وقت انتهاء الصلاحية : يجب أن يعرض الخادم وقت انتهاء صلاحية الرمز، وعادةً ما يكون ذلك بالثواني.
  • إذا كنت بحاجة إلى إنشاء JSON وتوقيعه مباشرةً كحامل رمز مميّز، بدلاً من استخدام رموز OAuth 2.0 المميّزة للوصول، يُرجى قراءة تعليمات تفويض حساب الخدمة بدون OAuth في مستندات مطوّري واجهة برمجة التطبيقات Identity.

بالنسبة إلى الرحلات عند الطلب

  • عند إنشاء حمولة 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 لسيناريو نموذجي في عمليات أسطول المركبات.

مثال على رمز لتتبُّع جميع المهام والمركبات في أسطول

المثال التالي هو رمز يتتبّع جميع المهام والمركبات في الأسطول من تطبيق مستند إلى الويب يستخدمه مشغّل. الأذونات المطلوبة لهذه العمليات أكبر من الأذونات المطلوبة لتطبيقات العملاء. يُرجى الاطّلاع على إعداد مكتبة تتبُّع أسطول المركبات في JavaScript لمعرفة عملية التنفيذ من جهة العميل التي ستستخدم هذا الرمز:

  • وقِّع الرمز باستخدام دور Cloud IAM ‏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": "*",
       }
    }

طريقة مصادقة بديلة لعمليات الخادم الخلفي

تنصحك 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": "*"
       }
    }

الخطوات التالية

  • تحقَّق من الإعداد حتى تتمكّن من إنشاء مركبة تجريبية والتأكّد من أنّ الرموز تعمل على النحو المطلوب.
  • للحصول على معلومات حول استخدام "بيانات الاعتماد التلقائية للتطبيق" (ADC) بدلاً من رموز JWT لعمليات الخادم الخلفي، يُرجى الاطّلاع على نظرة عامة على الأمان.