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

يتناول هذا المستند كيفية إصدار رموز JSON Web Tokens كجزء من تفعيل وصول تطبيقاتك المستندة إلى الويب والأجهزة الجوّالة إلى بيانات 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 في مستندات المطوّرين الخاصة بالهوية.

بالنسبة إلى الرحلات عند الطلب

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