كيفية إعداد تسجيل الدخول الاجتماعي باستخدام OAuth

هذا الدليل يوضح لك كيفية إعداد تسجيل الدخول الاجتماعي حتى يتمكن العملاء من تسجيل الدخول إلى أجهزة الكمبيوتر العميلة باستخدام حساباتهم على Google أو Facebook أو Apple أو X أو Discord. يستخدم HandyCafe تدفق تفويض الجهاز (RFC 8628)، الذي تم تصميمه للأجهزة التي لا تحتوي على متصفح كامل. يقوم العملاء بمسح رمز QR باستخدام هواتفهم للمصادقة.

ما ستحتاج إليه

• وصول إداري إلى خادم HandyCafe.
• حساب Google Cloud Console (لـ Google OAuth) أو وصول مكافئ إلى بوابة المطورين للمزودين الآخرين.
• تشغيل خادم HandyCafe والوصول إليه على شبكتك.
• جهاز كمبيوتر عميل واحد على الأقل متصل لاختبار تدفق تسجيل الدخول.

كيفية عمل تدفق جهاز OAuth في HandyCafe

قبل الغوص في الإعداد، إليك ملخص للتدفق:

1. يقوم العميل على جهاز كمبيوتر عميل غير مستخدم بالنقر على زر تسجيل الدخول الاجتماعي (مثل "تسجيل الدخول باستخدام Google").
2. يرسل العميل طلب بدء OAuth إلى الخادم.
3. يتصل الخادم بنقطة نهاية تفويض الجهاز الخاصة بالمزود ويتلقى رمز الجهاز ورمز المستخدم وعنوان URL للتحقق.
4. يعرض العميل رمز QR ورمز المستخدم على الشاشة غير المستخدمة.
5. يقوم العميل بمسح رمز QR باستخدام هاتفه ويصادق مع المزود.
6. يقوم الخادم بالاستطلاع من المزود حتى تكتمل المصادقة.
7. ينشئ الخادم طلب تسجيل دخول OAuth يظهر في صفحة الطلبات.
8. يقوم مسؤول أو كاشير بالموافقة على الطلب.
9. يتم إنشاء حساب عضو جديد (أو يتم ربط حساب موجود) ويتم تسجيل دخول العميل.

كيفية إعداد Google OAuth

Google هو المزود الأكثر استخدامًا. يغطي هذا القسم كل خطوة من إنشاء مشروع Google Cloud إلى اختبار أول تسجيل دخول.

الجزء أ: إنشاء بيانات اعتماد Google Cloud

1. افتح Google Cloud Console على https://console.cloud.google.com في متصفحك.
2. أنشئ مشروعًا جديدًا أو اختر مشروعًا موجودًا. قم بتسميته بشيء يمكن التعرف عليه مثل "HandyCafe OAuth".
3. انتقل إلى APIs & Services > شاشة موافقة OAuth.
4. اختر خارجي كنوع المستخدم (ما لم يكن لديك منظمة Google Workspace وتريد داخلي فقط).
5. املأ الحقول المطلوبة: اسم التطبيق ("اسم مقهاك")، بريد الدعم الإلكتروني للمستخدم، وبريد الاتصال بالمطور.
6. انقر على حفظ ومتابعة عبر أقسام النطاقات والمستخدمين التجريبيين. لا تحتاج إلى إضافة نطاقات خاصة. النطاقات الافتراضية للبريد الإلكتروني والملف الشخصي كافية.
7. انتقل إلى APIs & Services > بيانات الاعتماد.
8. انقر على إنشاء بيانات اعتماد > معرف عميل OAuth.
9. بالنسبة لنوع التطبيق، اختر التلفزيونات والأجهزة ذات الإدخال المحدود. هذا أمر حاسم. يستخدم HandyCafe تدفق تفويض الجهاز، الذي يتطلب هذا النوع المحدد من العميل.
10. أدخل اسمًا للعميل (مثل "HandyCafe Device Flow").
11. انقر على إنشاء.
12. انسخ معرف العميل وسر العميل من مربع الحوار التأكيدي. احفظهما بأمان. ستحتاج إلى كلا القيمتين في القسم التالي.

الجزء ب: تكوين خادم HandyCafe

13. افتح تطبيق خادم HandyCafe.
14. انتقل إلى الإعدادات باستخدام رمز الترس في الشريط الجانبي الأيسر.
15. اختر علامة التبويب OAuth.
16. قم بتمكين التبديل OAuth في أعلى الصفحة. هذا يمكّن تسجيل الدخول الاجتماعي عالميًا عبر جميع أجهزة الكمبيوتر العميلة.
17. حدد صف المزود Google في قائمة المزودين.
18. قم بتمكين التبديل الخاص بـ Google لتفعيل هذا المزود.
19. الصق معرف العميل الخاص بك من الخطوة 12 في حقل معرف العميل.
20. الصق سر العميل الخاص بك من الخطوة 12 في حقل سر العميل.
21. انقر على حفظ لتطبيق التكوين.

النتيجة المتوقعة: تعرض علامة تبويب OAuth أن Google ممكّن مع ملء بيانات الاعتماد الخاصة بك. يتم دفع الإعدادات إلى جميع العملاء المتصلين.

الجزء ج: اختبار تدفق تسجيل الدخول

22. اذهب إلى جهاز كمبيوتر عميل متصل. يجب أن تعرض الشاشة غير المستخدمة الآن قسم تسجيل الدخول الاجتماعي مع زر تسجيل الدخول إلى Google.
23. انقر على زر تسجيل الدخول إلى Google على الشاشة غير المستخدمة للعميل.
24. يعرض العميل رمز QR ورمز مستخدم (سلسلة أبجدية رقمية قصيرة).
25. امسح رمز QR باستخدام هاتفك. يفتح صفحة التحقق من الجهاز الخاصة بـ Google.
26. سجل الدخول باستخدام حساب Google وأدخل رمز المستخدم عند الطلب.
27. وافق على التطبيق.

النتيجة المتوقعة: على الخادم، يتم تشغيل صوت إشعار وتظهر إدخال جديد في صفحة الطلبات. يعرض الطلب اسم حساب Google وعنوان البريد الإلكتروني وجهاز الكمبيوتر العميل الذي بدأ تسجيل الدخول.

كيفية الموافقة على طلب تسجيل الدخول

كل تسجيل دخول باستخدام OAuth يولد طلبًا يجب أن يوافق عليه مسؤول أو كاشير قبل أن يحصل العميل على الوصول.

1. عندما يصل طلب تسجيل الدخول، يتم تشغيل صوت إشعار على الخادم وتظهر شارة على أيقونة صفحة الطلبات في الشريط الجانبي.
2. انتقل إلى صفحة الطلبات.
3. يعرض الطلب المعلق:
   • اسم المزود (مثل Google).
   • الاسم المعروض من المزود (مثل "John Smith").
   • عنوان البريد الإلكتروني (مثل "john@example.com").
   • جهاز الكمبيوتر العميل الذي بدأ الطلب (اسم المضيف أو الاسم المعروض).
   • الطابع الزمني.
4. راجع تفاصيل الطلب. تحقق من أن الشخص الموجود على جهاز الكمبيوتر العميل يطابق معلومات الحساب.
5. انقر على الموافقة لقبول الطلب.

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

نصيحة: إذا كان طلب تسجيل الدخول مشبوهًا (مثل أن يكون الكمبيوتر غير مراقب أو يبدو الطلب آليًا)، انقر على رفض بدلاً من ذلك. سيرى العميل رسالة "تم رفض الوصول" ويمكنه المحاولة مرة أخرى.

كيفية إعداد Facebook OAuth

1. افتح بوابة مطوري Facebook على https://developers.facebook.com .
2. أنشئ تطبيقًا جديدًا. اختر نوع التطبيق المستهلك.
3. انتقل إلى صفحة الإعدادات > الأساسية للتطبيق. لاحظ معرف التطبيق وسر التطبيق.
4. انتقل إلى إضافة منتج وأضف تسجيل الدخول إلى Facebook للأجهزة.
5. في إعدادات تسجيل الدخول إلى Facebook للأجهزة، أضف عناوين URI لإعادة التوجيه إذا تطلبت البوابة ذلك.
6. افتح خادم HandyCafe وانتقل إلى الإعدادات > OAuth.
7. حدد صف المزود Facebook.
8. قم بتمكين التبديل الخاص بـ Facebook.
9. الصق معرف التطبيق في حقل معرف العميل.
10. الصق سر التطبيق في حقل سر العميل.
11. انقر على حفظ.

النتيجة المتوقعة: يظهر Facebook كمزود ممكّن. تعرض الشاشات غير المستخدمة للعملاء زر تسجيل الدخول إلى Facebook بجانب أي مزودين آخرين ممكّنين.

كيفية إعداد Discord OAuth

1. افتح بوابة مطوري Discord على https://discord.com/developers/applications .
2. أنشئ تطبيقًا جديدًا. قم بتسميته باسم مقهاك.
3. انتقل إلى قسم OAuth2 في الشريط الجانبي الأيسر.
4. انسخ معرف العميل وقم بإنشاء سر العميل. احفظ السر بأمان حيث يعرضه Discord مرة واحدة فقط.
5. افتح خادم HandyCafe وانتقل إلى الإعدادات > OAuth.
6. حدد صف المزود Discord (يكون معطلاً افتراضيًا).
7. قم بتمكين التبديل الخاص بـ Discord.
8. الصق معرف العميل في حقل معرف العميل.
9. الصق سر العميل في حقل سر العميل.
10. انقر على حفظ.

النتيجة المتوقعة: أصبح Discord متاحًا الآن كخيار تسجيل دخول على الشاشات غير المستخدمة للعملاء.

كيفية السماح بتسجيل الدخول بدون رصيد

بشكل افتراضي، يسمح HandyCafe للعملاء الذين تم التحقق من هويتهم عبر OAuth بتسجيل الدخول حتى لو لم يكن لديهم رصيد محفظة أو رصيد زمني. يمكنك تغيير هذا السلوك.

1. انتقل إلى الإعدادات > OAuth.
2. حدد التبديل السماح بتسجيل الدخول بدون رصيد.
3. إذا كان ممكّنًا (افتراضيًا)، يمكن للعملاء الذين يصادقون عبر OAuth تسجيل الدخول بغض النظر عن رصيدهم. يمكن للكاشير بدء جلسة مدفوعة لاحقًا لهم.
4. إذا كان معطلاً، يجب أن يكون لدى العملاء إما رصيد محفظة أو رصيد زمني لتسجيل الدخول. سيرى العملاء الذين لديهم رصيد صفري رسالة تخبرهم بزيارة الكاشير لإعادة الشحن.
5. انقر على حفظ بعد تغيير التبديل.

النتيجة المتوقعة: يدخل السلوك حيز التنفيذ فورًا للطلبات الجديدة. لا تتأثر الجلسات الحالية.

كيفية ربط هوية OAuth بعضو موجود

إذا كان لدى العميل حساب عضو بالفعل (تم إنشاؤه يدويًا بواسطة كاشير) ثم قام بتسجيل الدخول عبر OAuth لأول مرة، يمكن لعملية الموافقة ربط هوية OAuth بحسابهم الموجود.

1. عندما يصل طلب تسجيل الدخول عبر OAuth إلى صفحة الطلبات، تحقق مما إذا كان البريد الإلكتروني يطابق عضوًا موجودًا.
2. إذا اكتشف النظام تطابقًا، ستعرض مربع الحوار الموافقة خيار ربط هوية OAuth بالعضو الموجود بدلاً من إنشاء حساب جديد.
3. وافق على الطلب مع تحديد خيار الربط.

النتيجة المتوقعة: يكتسب حساب العضو الموجود رابط OAuth. ستتجاوز عمليات تسجيل الدخول المستقبلية من هذا المزود خطوة الموافقة وتسجيل العضو مباشرة (بعد الموافقة الأولى).

الأخطاء الشائعة التي يجب تجنبها

• استخدام نوع عميل OAuth خاطئ في Google Cloud Console. يجب عليك اختيار "التلفزيونات والأجهزة ذات الإدخال المحدود" عند إنشاء معرف عميل OAuth. إذا اخترت "تطبيق ويب" أو "تطبيق سطح المكتب"، لن يعمل تدفق تفويض الجهاز وسيفشل العميل في الحصول على رمز الجهاز.
• نسيان تمكين التبديل العام لـ OAuth. تمكين المزودين الفرديين ليس كافيًا. يجب أن يكون التبديل الرئيسي لـ OAuth في أعلى صفحة إعدادات OAuth قيد التشغيل أيضًا.
• عدم الموافقة على طلبات تسجيل الدخول. تتطلب تسجيلات الدخول عبر OAuth موافقة صريحة من الخادم. إذا لم يراقب أحد صفحة الطلبات، سينتظر العملاء إلى ما لا نهاية على الشاشة غير المستخدمة. فكر في تعيين كاشير لمراقبة الطلبات خلال ساعات الذروة.
• ترك رموز الجهاز تنتهي صلاحيتها. تمتلك رموز الجهاز عمرًا محدودًا (عادةً 5-10 دقائق). إذا استغرق العميل وقتًا طويلاً لمسح رمز QR والمصادقة، تنتهي صلاحية الرمز ويجب عليهم البدء من جديد. انصح العملاء بالمسح بسرعة.
• لصق بيانات الاعتماد مع مسافات إضافية. عند نسخ معرف العميل أو سر العميل من وحدة تحكم المزود، تأكد من عدم وجود مسافات زائدة في البداية أو النهاية. ستسبب المسافات الزائدة فشل المصادقة.
• نسيان نشر تطبيق Google OAuth. التطبيقات في وضع "الاختبار" في Google تسمح فقط لعدد محدود من المستخدمين التجريبيين. للسماح لأي عميل بتسجيل الدخول، يجب عليك نشر التطبيق عبر صفحة شاشة موافقة OAuth وإكمال أي خطوات تحقق مطلوبة.
• خلط بين معرف العميل وسر العميل. هذه قيمتان مختلفتان. معرف العميل هو للعرض العام. يجب الحفاظ على سر العميل سريًا. تبديلهما سيسبب فشل المصادقة.
• عدم تكوين اسم المقهى. يتم عرض اسم المقهى من إعدادات HandyCafe الخاصة بك على الشاشة غير المستخدمة للعميل أثناء تدفق OAuth. الاسم الفارغ أو الافتراضي يبدو غير احترافي. قم بتعيين اسم مقهاك في الإعدادات > العامة قبل تمكين OAuth.