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

للرحلات عند الطلب

  • عند إنشاء الحمولة في JWT، أضِف مطالبة إضافية في القسم "تفويض" مع ضبط المفتاح vehicleid أو tripid على قيمة معرّف المركبة أو معرّف الرحلة التي يتم إجراء المكالمة من أجلها.

بالنسبة إلى المهام المُجدوَلة

  • عندما يستدعي خادمك واجهات برمجة تطبيقات أخرى، يجب أن تحتوي الرموز المميّزة أيضًا على المطالبة المناسبة. لإجراء ذلك، يمكنك اتّباع الخطوات التالية:
    • اضبط قيمة كل مفتاح على *.
    • امنح المستخدم إذن الوصول إلى كل من taskids وdeliveryvehicleids. لإجراء ذلك، أضِف مطالبة إضافية في قسم التفويض باستخدام المفتاحَين taskid وdeliveryvehicleid.
    • عند استخدام علامة النجمة (*) في مطالبة taskids، يجب أن يكون * هو العنصر الوحيد في الصفيف.

أمثلة على رمز JSON المميّز على الويب للرحلات عند الطلب

يقدّم هذا القسم أمثلة على 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 لتنفيذ الإجراء من جهة العميل الذي سيستخدم هذا الرمز المميّز:

  • وقِّع الرمز المميّز باستخدام دور 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 لمصادقة عمليات الخادم في الخلفية. إذا تعذّر عليك استخدام ميزة "الوصول المباشر إلى البيانات" وكنت بحاجة إلى استخدام ملفات 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 لعمليات الخادم في الخلفية، يُرجى الاطّلاع على نظرة عامة على الأمان.