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

للرحلات حسب الطلب

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