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

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

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

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

  • استخدِم حسابات الخدمة والأدوار المناسبة. يضمن حساب الخدمة والدور المرتبط به أنّ المستخدم الذي يطلب الرمز المميّز مفوَّض بالاطّلاع على المعلومات التي يمنحه الرمز المميّز إذن الوصول إليها. على وجه التحديد:
    • في حال توقيع إرسال JWT إلى جهاز جوّال، استخدِم الخدمة حساب لدور Driver أو حزمة 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 من جهة العميل عملية تنفيذ قد تستخدم هذا الرمز:

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

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