المصادقة والترخيص

يشرح هذا القسم مفاهيم المصادقة والترخيص في ما يتعلق بالدمج مع Fleet Engine.

يمكنك ضبط الإمكانات التي يوفّرها Last Mile Fleet Solution من خلال وحدة التحكّم في Google Cloud. تتطلب حزم تطوير البرامج (SDK) الخاصة بإصدار Fleet Engine استخدام رموز JSON المميّزة للويب (JWT) التي تم توقيعها من خلال حساب خدمة مناسب.

نظرة عامة

يجب أن تستخدم الواجهات الخلفية للعملاء إجراءات المصادقة والتفويض ضد Fleet Engine باستخدام آليات بيانات الاعتماد التلقائية للتطبيق العادية.

يتلقى Fleet Engine أيضًا المكالمات التي تنشأ من بيئات منخفضة الثقة مثل الهواتف الذكية والمتصفحات. لحماية المفاتيح السرية لحساب الخدمة المناسبة للبيئات الموثوق بها فقط، من المتوقّع أن تنشئ خلفيات العملاء رموز JSON مميّزة للويب (JWT) موقَّعة مع مطالبات إضافية خاصة بـ Fleet Engine والتي يمكن إصدارها بعد ذلك لبيئات غير موثوق بها، مثل الهواتف الجوّالة.

مبادئ تصميم المصادقة

يتضمن مسار المصادقة في Fleet Engine مبادئ التصميم التالية.

  • تحدد أدوار إدارة الهوية وإمكانية الوصول مجموعة من الأذونات على الموارد المسموح بها لمدير المشروعات. على سبيل المثال، يُسمح لأدوار المشرف بتنفيذ كل شيء باستخدام "بيانات الاعتماد التلقائية للتطبيق"، في حين يُسمح لدور "برنامج التشغيل غير الموثوق به"* بتعديل موقع المركبة فقط، ويقتصر على استخدام مفاتيح JWT للمصادقة والتفويض.

  • بالنسبة إلى البيئات غير الموثوق بها، يدّعي JWT أن الكيانات التي قد يعمل عليها المتصل. قد تكون هذه مهام محددة أو مركبات توصيل.

  • يجب أن يتصل الرمز الذي يعمل في بيئة منخفضة الثقة أولاً بالرمز البرمجي الذي يتم تشغيله في بيئة موثوق بها لإصدار JWT.

  • تُجري Fleet Engine عمليات فحص الأمان التالية على طلبات البيانات من واجهة برمجة التطبيقات لأحد الموارد:

    1. يمتلك الشخص الرئيسي للمكالمة الأذونات المناسبة (من خلال تعيين الدور) للإجراء على المورد.

    2. بالنسبة إلى الأدوار غير الإدارية، توفّر مطالبات JWT التي تم تمريرها في الطلب الإذن اللازم للمورد.

مسار المصادقة

يوضّح مخطط التسلسل التالي تفاصيل مسار المصادقة.

  1. ينشئ مشرف مجموعة الأجهزة حسابات الخدمة.

  2. يعيّن مشرف مجموعة الأجهزة أدوارًا محددة لإدارة الهوية وإمكانية الوصول إلى حسابات الخدمة.

  3. يهيئ مشرف مجموعة الأجهزة الخلفية باستخدام حسابات الخدمة وبيانات الاعتماد التلقائية للتطبيق.

  4. يطلب تطبيق العميل JWT من الواجهة الخلفية للعميل. قد يكون مقدِّم الطلب هو تطبيق Driver أو تطبيق المستهلك أو تطبيق المراقبة.

  5. توقّع الواجهة الخلفية للعميل JWT لحساب الخدمة المعني، وتصدره. يتلقى تطبيق العميل JWT.

  6. يستخدم تطبيق العميل JWT للاتصال بـ Fleet Engine لقراءة البيانات أو تعديلها، استنادًا إلى أدوار "إدارة الهوية وإمكانية الوصول" المخصّصة له أثناء مرحلة الإعداد.

الرسم التخطيطي لتسلسل المصادقة

إعداد مشروع على السحابة الإلكترونية

لإعداد مشروعك على السحابة الإلكترونية، عليك أولاً إنشاء مشروعك، ثم إنشاء حسابات خدمة.

لإنشاء مشروعك على Google Cloud، اتّبِع الخطوات التالية:

  1. أنشِئ مشروعًا على Google Cloud باستخدام Google Cloud Console.
  2. باستخدام لوحة بيانات الخدمات وواجهات برمجة التطبيقات، يمكنك تفعيل واجهة برمجة تطبيقات الرحلات المحلية والتسليمات.

حسابات الخدمة وأدوار إدارة الهوية وإمكانية الوصول

حساب الخدمة هو نوع خاص من الحسابات يستخدمه أحد التطبيقات بدلاً من الأشخاص. وعادة ما يُستخدم حساب الخدمة لإنشاء JWTs التي تمنح مجموعات مختلفة من الأذونات اعتمادًا على الدور. للحد من احتمالية إساءة الاستخدام، يمكنك إنشاء حسابات خدمة متعددة، ولكل منها حد أدنى من مجموعة الأدوار المطلوبة ().

يستخدم Last Mile Fleet Solution الأدوار التالية:

Roleالوصف
مستخدم برنامج التشغيل الموثوق به في نظام تسليم Fleet Engine

roles/fleetengine.deliveryTrustedDriver		 لمنح الإذن لإنشاء وتعديل مركبات التسليم والمهام، بما في ذلك تعديل الموقع الجغرافي لمركبة التسليم وحالة المهمة أو نتائجها ويتم عادةً استخدام الرموز المميزة التي يتم إنشاؤها من خلال حساب خدمة يتولى هذا الدور من الأجهزة الجوّالة لسائق التسليم أو من الخوادم الخلفية.
مستخدم غير موثوق لسائقي الخدمة غير الموثوق بهم في خدمة تسليم المحرّكات

roles/fleetengine.deliveryUntrustedDriver		 يمنح الإذن بتعديل الموقع الجغرافي لمركبة التسليم. ويتم عادةً استخدام الرموز المميّزة التي يتم إنشاؤها من خلال حساب خدمة يتولى هذا الدور من الأجهزة الجوّالة لسائقي التوصيل.
مستخدم مستهلك خدمة Fleet Engine

roles/fleetengine.deliveryConsumer		 يمنح الإذن للبحث عن المهام باستخدام رقم تعريف التتبّع، ولقراءة معلومات المهمة بدون تعديلها. ويتم عادةً استخدام الرموز المميّزة التي يتم إنشاؤها من خلال حساب خدمة بهذا الدور من متصفّح الويب الخاص بمستهلك خدمة التسليم.
مشرف تسليم Fleet Engine

roles/fleetengine.deliveryAdmin		 يمنح الإذن بالقراءة والكتابة لموارد التسليم. ولا يحتاج المشرفون الذين لديهم هذا الدور إلى استخدام JWT، بل يمكنهم بدلاً من ذلك استخدام بيانات الاعتماد التلقائية للتطبيق. يتم تجاهل مطالبات JWT المخصّصة. ويجب أن يقتصر هذا الدور على البيئات الموثوق بها (الواجهة الخلفية للعميل).
المستخدم الفائق في إرسال Fleet Engine **(تم إيقافه)**

roles/fleetengine.deliverySuperUser		 يمنح الإذن لجميع مركبات التسليم وواجهات برمجة تطبيقات المهام. ويتم عادةً استخدام الرموز المميّزة التي يتم إنشاؤها من خلال حساب خدمة يتولى هذا الدور من خوادم الخلفية.
قارئ مجموعة أجهزة إرسال البيانات من Fleet Engine

roles/fleetengine.deliveryFleetReader		 يمنح الإذن بقراءة مهام ومركبات التسليم والبحث عن المهام باستخدام رقم تعريف تتبُّع. ويتم عادةً استخدام الرموز المميّزة التي يتم إنشاؤها بواسطة حساب خدمة بهذا الدور من خلال متصفّح الويب الخاص بمشغّل أسطول التسليم.

يمكن للمؤسسات التي تزوّد سائقي التوصيل بأجهزة تتم إدارتها بواسطة قسم تكنولوجيا المعلومات للشركات الاستفادة من المرونة التي يوفرها دور مستخدم السائق الموثوق به في Fleet Engine واختيار دمج بعض أو كل تفاعلات Fleet Engine في تطبيق الأجهزة الجوّالة.

على المؤسسات التي تدعم سياسات "إحضار الجهاز الخاص بك" اختيار أمان دور "مستخدم Fleet Engine غير الموثوق به" والاعتماد فقط على تطبيق الأجهزة الجوّالة لإرسال تعديلات الموقع الجغرافي للمركبة إلى Fleet Engine. ينبغي أن تنشأ جميع التفاعلات الأخرى من خوادم الواجهة الخلفية للعميل.

تم إنشاء حِزم تطوير البرامج (SDK) الخاصة بكل من السائق والمستهلك استنادًا إلى هذه الأدوار العادية. ومع ذلك، يمكنك إنشاء أدوار مخصَّصة تسمح بتجميع مجموعة عشوائية من الأذونات معًا. ستعرض حزمتا تطوير البرامج (SDK) لبرنامج التشغيل والمستهلك رسائل خطأ عند عدم توفّر إذن مطلوب. نتيجةً لذلك، ننصح بشدة باستخدام مجموعة الأدوار العادية الموضّحة أعلاه بدلاً من الأدوار المخصَّصة.

إنشاء حساب الخدمة

يمكنك إنشاء حساب خدمة باستخدام علامة التبويب IAM & Admin > Service Accounts في Google Cloud Console. من القائمة المنسدلة "الدور"، حدد Fleet Engine وعيّن أحد الأدوار لحساب الخدمة. من الممارسات الجيدة الإشارة إلى الحساب المرتبط بكل دور. على سبيل المثال، امنح حساب الخدمة اسمًا ذا معنى.

للتيسير عليك، إذا كنت بحاجة إلى إنشاء رموز JWT للعملاء غير الموثوق بهم، ستتيح لهم إضافة مستخدمين إلى دور منشئ الرموز المميزة لحساب الخدمة إنشاء الرموز المميزة باستخدام أدوات سطر أوامر gcloud.

gcloud projects add-iam-policy-binding project-id \
       --member=user:my-user@example.com \
       --role=roles/iam.serviceAccountTokenCreator

حيث my-user@example.com هو البريد الإلكتروني المستخدم للمصادقة باستخدام gcloud (gcloud auth list --format='value(account)').

مكتبة مصادقة Fleet Engine

يستخدم Fleet Engine رموز JWT لحظر الوصول إلى واجهات برمجة تطبيقات Fleet Engine في بيئات غير موثوق بها. تعمل مكتبة مصادقة Fleet Engine المتوفّرة على GitHub على تبسيط إنشاء رموز JWT من Fleet Engine وتوقيعها بأمان.

توفر المكتبة الفوائد التالية:

  • تبسيط عملية إنشاء الرموز المميّزة لـ Fleet Engine
  • يتم توفير آليات توقيع الرمز المميّز بخلاف استخدام ملفات بيانات الاعتماد (مثل انتحال هوية حساب خدمة.)

إنشاء رمز JSON المميّز للويب (JWT) للتفويض

في حال عدم استخدام Fleet Engine Auth Library، يجب إنشاء ملفات JWT مباشرةً داخل قاعدة الرموز لديك. وهذا يتطلب منك أن يكون لديك فهم عميق لـ JWT وكيفية ارتباطها بـ Fleet Engine. ولهذا السبب، ننصح بشدة بالاستفادة من مكتبة مصادقة Fleet Engine.

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

يحتوي قسم عنوان JWT على الحقول التالية:

الحقلالوصف
alg الخوارزمية المطلوب استخدامها. `RS256`.
typ تمثّل هذه السمة نوع الرمز المميّز. "JWT".
kid رقم تعريف المفتاح الخاص لحساب الخدمة. يمكنك العثور على هذه القيمة في الحقل "private_key_id" في ملف JSON لحساب الخدمة. تأكَّد من استخدام مفتاح من حساب خدمة يتضمّن مستوى الأذونات الصحيح.

يحتوي قسم مطالبات JWT على الحقول التالية:

الحقلالوصف
iss عنوان البريد الإلكتروني لحساب الخدمة.
sub عنوان البريد الإلكتروني لحساب الخدمة.
aud SERVICE_NAME لحساب الخدمة الخاص بك، في هذه الحالة https://fleetengine.googleapis.com/
iat الطابع الزمني الذي انقضى منه الرمز المميّز بالثواني 1 كانون الثاني (يناير) 1970 عند الساعة 00:00:00 حسب التوقيت العالمي المنسّق (UTC) اسمح لمدة 10 دقائق للحصول على انحراف. وإذا كان الطابع الزمني بعيدًا جدًا في الماضي أو في المستقبل، قد يُبلغ الخادم عن خطأ.
exp الطابع الزمني لوقت انتهاء صلاحية الرمز المميّز، والذي يتم تحديده بالثواني المنقضي منذ 1 كانون الثاني (يناير) 1970 الساعة 00:00:00 حسب التوقيت العالمي المنسَّق (UTC). يتعذّر تقديم الطلب إذا كان الطابع الزمني يقع بعد أكثر من ساعة واحدة في المستقبل.
authorization استنادًا إلى حالة الاستخدام، قد يحتوي على "deliveryvehicleid" أو `trackingid` أو `taskid` أو `taskids`.

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

مطالبات JWT

يستخدم Last Mile Fleet Solution مطالبات خاصة. يضمن استخدام المطالبات الخاصة وصول العملاء المعتمدين فقط إلى بياناتهم الخاصة. على سبيل المثال، عندما تصدر الخلفية رمز JSON المميّز للويب لجهاز الجوّال الخاص بسائق التسليم، يجب أن يحتوي هذا الرمز المميّز على المطالبة deliveryvehicleid بقيمة معرّف مركبة التسليم الخاصة بالسائق. بعد ذلك، واستنادًا إلى دور السائق، تتيح الرموز المميّزة الوصول فقط لمعرّف المركبة الذي يتم تسليمه، وليس لأي معرّف عشوائي آخر للمركبة.

يستخدم Last Mile Fleet Solution المطالبات الخاصة التالية:

  • deliveryvehicleid: يُستخدم عند طلب واجهات برمجة التطبيقات (API) لكل مركبة.
  • taskid: يُستخدم عند طلب واجهات برمجة التطبيقات لكل مهمة.
  • taskids: يُستخدم عند الاتصال بالرقم BatchCreateTasksAPI. يجب أن يكون هذا الادعاء على شكل مصفوفة، ويجب أن يحتوي الصفيف على جميع معرفات المهام اللازمة لإكمال الطلب. لا تضمِّن مطالبات delivervehicleid أو trackingid أو taskid.
  • trackingid: تُستخدم عند الاتصال بـ GetTaskTrackingInfoAPI. ويجب أن تتطابق المطالبة مع معرّف التتبّع في الطلب. لا تضمِّن مطالبات delivervehicleid أو taskid أو taskids.

يجب أن يشتمل الرمز المميّز أيضًا على المطالبة المناسبة عند استدعاء واجهات برمجة التطبيقات من خادم الخلفية، ولكن يمكنك استخدام القيمة الخاصة لعلامة النجمة ("*") للمطالبات deliveryvehicleid وtaskid وtrackingid. يمكن أيضًا استخدام علامة النجمة ("*") في المطالبة taskids، ولكن يجب أن تكون العنصر الوحيد في المصفوفة.

إذا أردت إنشاء ملف JSON وتوقيعه مباشرةً بصفته حامل الرمز المميّز، بدلاً من استخدام رموز الدخول عبر OAuth 2.0، يُرجى الاطّلاع على تعليمات تفويض حساب الخدمة بدون بروتوكول OAuth في مستندات "مطوّر الهوية".

تعتمد آلية إرفاق الرمز المميّز بطلب gRPC على اللغة وإطار العمل المستخدَمَين لإجراء الاستدعاء. إنّ آلية تحديد رمز مميّز لطلب HTTP هي تضمين عنوان تفويض مع رمز الحامل المميّز الذي تمثل قيمته الرمز المميّز، كما هو موضّح في ملاحظات التفويض لحالات الاستخدام الخاصة بتتبُّع الشحن أو أداء الأسطول.

يعرض المثال التالي رمزًا مميزًا لعملية لكل مهمة من خادم الخلفية:

    {
      "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": "*"
       }
    }

يعرض المثال التالي رمزًا مميزًا لعملاء المستخدمين:

    {
      "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"
       }
    }

يوضح المثال التالي رمزًا مميزًا لتطبيق برنامج التشغيل:

    {
      "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"
       }
    }
  • بالنسبة إلى الحقل kid في العنوان، حدِّد رقم تعريف المفتاح الخاص لحساب الخدمة. يمكنك العثور على هذه القيمة في الحقل private_key_id من ملف JSON لحساب الخدمة.
  • في الحقلين iss وsub، حدِّد عنوان البريد الإلكتروني لحساب الخدمة. يمكنك العثور على هذه القيمة في الحقل client_email ضمن ملف JSON لحساب الخدمة.
  • بالنسبة إلى الحقل aud، حدِّد https://SERVICE_NAME/.
  • في الحقل iat، حدِّد الطابع الزمني لوقت إنشاء الرمز المميّز، بالثواني المنقضية منذ 1 كانون الثاني (يناير) 1970. اسمح لمدة 10 دقائق للحصول على الانحراف. إذا كان الطابع الزمني بعيدًا جدًا في الماضي أو في المستقبل، قد يُبلغ الخادم عن خطأ.
  • في الحقل exp، حدِّد الطابع الزمني لوقت انتهاء صلاحية الرمز المميّز، بالثواني منذ 00:00:00 حسب التوقيت العالمي المنسَّق (UTC) في 1 كانون الثاني (يناير) 1970. والقيمة المقترَحة هي iat + 3600.

عند توقيع الرمز المميّز لتمريره إلى جهاز جوّال أو مستخدم نهائي، تأكَّد من استخدام ملف بيانات الاعتماد لدور "برنامج تشغيل التسليم" أو دور "المستهلك". بخلاف ذلك، سيتمكن الجهاز الجوّال أو المستخدم النهائي من تغيير أو عرض المعلومات التي لا ينبغي له الوصول إليها.