إصدار رموز 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 لعمليات الخادم الخلفي، يُرجى الاطّلاع على نظرة عامة على الأمان.