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

يتناول هذا المستند كيفية إصدار الرموز المميّزة بتنسيق JSON كجزء من تفعيل وصول تطبيقات الويب والتطبيقات المستندة إلى الأجهزة الجوّالة إلى بيانات Fleet Engine. إذا لم يسبق لك قراءة مقالة رموز JSON المميّزة للويب ضمن قسم الأمان في Fleet Engine، ننصحك بذلك. باستخدام خدمة Fleet Engine، يمكنك إصدار ملفات JWT بإحدى الطريَقتَين التاليتَين:

  • استخدام مكتبة التفويض: تنصح Google باستخدام هذا النهج عندما تكون قاعدة بياناتك مكتوبة بلغة Java. تتعامل هذه المكتبة مع إصدار JWTs لأجل جميع سيناريوهات حالات الاستخدام التي قد تحتاجها مع الخدمة، كما أنها تبسّط عملية التنفيذ بشكلٍ كبير.
  • إنشاء رموز 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" الصحيح عند استخدام تنسيق ADC أو ملفات JWT. وبخلاف ذلك، ستفشل العملية.
  • شارِك الرموز المميّزة التي تم إنشاؤها فقط. لا تشارك أبدًا بيانات الاعتماد المستخدَمة لإنشاء الرموز المميَّزة.
  • بالنسبة إلى مكالمات 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 لسيناريو نموذجي في عمليات الأسطول.

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

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