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

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

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