نحوه راه اندازی OAuth Social Login

این راهنما شما را در پیکربندی ورود به سیستم اجتماعی راهنمایی می‌کند تا مشتریان بتوانند با استفاده از حساب‌های 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 Cloud تا آزمایش اولین ورود را پوشش می دهد.

بخش A: ایجاد اعتبارنامه Google Cloud

1. Google Cloud Console را در https://console.cloud.google.com در مرورگر خود باز کنید.
2. یک پروژه جدید ایجاد کنید یا یک پروژه موجود را انتخاب کنید. آن را چیزی قابل تشخیص مانند "HandyCafe OAuth" نامگذاری کنید.
3. به **APIs & Services > OAuth consent screen ** بروید.
4. External را به عنوان نوع کاربر انتخاب کنید (مگر اینکه یک سازمان Google Workspace داشته باشید و فقط داخلی بخواهید).
5. فیلدهای الزامی را پر کنید: نام برنامه («نام کافه شما»)، ایمیل پشتیبانی کاربر، و ایمیل تماس با برنامه‌نویس.
6. روی ذخیره و ادامه از طریق بخش Scopes و Test Users کلیک کنید. شما نیازی به اضافه کردن دامنه های خاصی ندارید. دامنه پیش فرض ایمیل و نمایه کافی است.
7. به APIs & Services > Credentials بروید.
8. روی Create Credentials > OAuth Client ID کلیک کنید.
9. برای نوع برنامه، تلویزیون ها و دستگاه های ورودی محدود را انتخاب کنید. این مهم است. HandyCafe از جریان اعطای مجوز دستگاه استفاده می کند که به این نوع مشتری خاص نیاز دارد.
10. یک نام برای کلاینت وارد کنید (به عنوان مثال، "HandyCafe Device Flow").
11. روی Create کلیک کنید.
12. Client ID و Client Secret را از گفتگوی تایید کپی کنید. آنها را به طور ایمن ذخیره کنید. در بخش بعدی به هر دو مقدار نیاز خواهید داشت.

قسمت B: سرور HandyCafe را پیکربندی کنید

13. برنامه HandyCafe Server را باز کنید.
14. با استفاده از نماد چرخ دنده در نوار کناری سمت چپ به تنظیمات بروید.
15. تب OAuth را انتخاب کنید.
16. کلید OAuth را در بالای صفحه فعال کنید. این به صورت جهانی ورود اجتماعی را در تمام رایانه های شخصی مشتری فعال می کند.
17. ردیف ارائه دهنده Google را در لیست ارائه دهندگان پیدا کنید.
18. ضامن Google را برای فعال کردن این ارائه دهنده فعال کنید.
19. Client ID خود را از مرحله 12 در قسمت Client ID قرار دهید.
20. Client Secret خود را از مرحله 12 در قسمت Client Secret قرار دهید.
21. برای اعمال تنظیمات روی ذخیره کلیک کنید.

نتیجه مورد انتظار: برگه OAuth Google را فعال با اطلاعات کاربری شما پر شده نشان می دهد. تنظیمات به همه کلاینت های متصل منتقل می شوند.

قسمت C: جریان ورود را آزمایش کنید

22. به یک کامپیوتر مشتری متصل بروید. اکنون صفحه بیکار باید یک بخش ورود به سیستم اجتماعی را با دکمه ورود به سیستم Google نشان دهد.
23. روی دکمه ورود به سیستم Google در صفحه بیکار مشتری کلیک کنید.
24. کلاینت یک کد QR و یک کد کاربر (یک رشته الفبایی عددی کوتاه) را نمایش می دهد.
25. کد QR را با گوشی خود اسکن کنید. صفحه تأیید دستگاه Google را باز می کند.
26. با یک حساب کاربری گوگل وارد شوید و زمانی که از شما خواسته شد کد کاربری را وارد کنید.
27. مجوز برنامه.

نتیجه مورد انتظار: در سرور، یک صدای اعلان پخش می شود و یک ورودی جدید در صفحه درخواست ها ظاهر می شود. این درخواست نام حساب Google، آدرس ایمیل و رایانه شخصی مشتری را نشان می دهد که ورود به سیستم را آغاز کرده است.

چگونه یک درخواست ورود را تایید کنیم

هر ورود OAuth درخواستی ایجاد می کند که قبل از دسترسی مشتری باید توسط مدیر یا صندوقدار تأیید شود.

1. هنگامی که یک درخواست ورود به سیستم می رسد، یک صدای اعلان روی سرور پخش می شود و یک نشان روی نماد صفحه درخواست ها در نوار کناری ظاهر می شود.
2. به صفحه درخواست ها بروید.
3. درخواست معلق نشان می دهد:
   • نام ارائه دهنده (به عنوان مثال، Google).
   • نام نمایشی از ارائه دهنده (به عنوان مثال، "جان اسمیت").
   • آدرس ایمیل (به عنوان مثال، "john@example.com").
   • کامپیوتر مشتری که درخواست را آغاز کرده است (نام میزبان یا نام نمایشی).
   • مهر زمانی
4. جزئیات درخواست را بررسی کنید. بررسی کنید که شخص در رایانه شخصی مشتری با اطلاعات حساب مطابقت داشته باشد.
5. برای پذیرش درخواست روی تأیید کلیک کنید.

نتیجه مورد انتظار: اگر هیچ حساب عضو موجود به این هویت OAuth مرتبط نباشد، یک حساب عضو جدید به طور خودکار ایجاد می شود. نام نمایشی و ایمیل ارائه دهنده استفاده می شود. مشتری وارد سیستم شده و کامپیوتر مشتری از صفحه بیکار به صفحه آنلاین منتقل می شود. اگر یک حساب عضو قبلاً به این هویت OAuth مرتبط شده بود، عضو موجود مستقیماً وارد سیستم می‌شود.

نکته: اگر درخواست ورود مشکوک است (به عنوان مثال، رایانه شخصی بدون مراقبت است یا درخواست خودکار به نظر می رسد)، به جای آن روی **رد ** کلیک کنید. مشتری پیام «دسترسی ممنوع است» را می بیند و می تواند دوباره امتحان کند.

نحوه راه اندازی Facebook OAuth

1. پورتال توسعه دهنده فیس بوک را در https://developers.facebook.com . باز کنید
2. یک برنامه جدید ایجاد کنید. نوع برنامه مصرف کننده را انتخاب کنید.
3. به صفحه Settings > Basic برنامه بروید. به App ID و App Secret توجه کنید.
4. به Add Product بروید و Facebook Login for Devices را اضافه کنید.
5. در تنظیمات فیسبوک Login for Devices، در صورت نیاز پورتال، URI های تغییر مسیر خود را اضافه کنید.
6. سرور HandyCafe را باز کنید و به مسیر Settings > OAuth بروید.
7. ردیف ارائه دهنده فیس بوک را پیدا کنید.
8. تعویض فیس بوک را فعال کنید.
9. App ID را در قسمت Client ID قرار دهید.
10. App Secret را در قسمت Client Secret قرار دهید.
11. روی ذخیره کلیک کنید.

نتیجه مورد انتظار: فیس بوک به عنوان یک ارائه دهنده فعال ظاهر می شود. صفحه نمایش بیکار Client یک دکمه ورود به فیس بوک را در کنار سایر ارائه دهندگان فعال نشان می دهد.

چگونه Discord OAuth را راه اندازی کنیم

1. پورتال توسعه دهنده Discord را در https://discord.com/developers/applications . باز کنید
2. یک برنامه جدید ایجاد کنید. نام آن را به نام کافه خود بگذارید.
3. به بخش OAuth2 در نوار کناری سمت چپ بروید.
4. Client ID را کپی کنید و یک Client Secret ایجاد کنید. راز را ایمن ذخیره کنید زیرا Discord فقط یک بار آن را نشان می دهد.
5. سرور HandyCafe را باز کنید و به مسیر Settings > OAuth بروید.
6. ردیف ارائه دهنده Discord را پیدا کنید (به طور پیش فرض غیرفعال است). 7-تغییر Discord را فعال کنید.
7. Client ID را در قسمت Client ID قرار دهید.
8. Client Secret را در قسمت Client Secret قرار دهید.
9. روی ذخیره کلیک کنید.

نتیجه مورد انتظار: Discord اکنون به عنوان یک گزینه ورود به سیستم در صفحات بیکار مشتری در دسترس است.

چگونه اجازه ورود بدون اعتبار را بدهیم

به طور پیش‌فرض، HandyCafe به مشتریانی که توسط OAuth احراز هویت شده‌اند اجازه می‌دهد حتی اگر موجودی کیف پول یا اعتبار زمانی ندارند، وارد شوند. شما می توانید این رفتار را تغییر دهید.

1. به تنظیمات > OAuth بروید.
2. کلید Allow Login Without Credit را پیدا کنید.
3. اگر فعال باشد (پیش‌فرض)، مشتریانی که از طریق OAuth احراز هویت می‌کنند، می‌توانند بدون در نظر گرفتن موجودی خود وارد شوند. صندوقدار می تواند یک جلسه پس پرداخت را برای آنها شروع کند.
4. در صورت غیرفعال شدن، مشتریان باید دارای موجودی کیف پول یا اعتبار زمانی برای ورود به سیستم باشند. مشتریانی که موجودی صفر دارند، پیامی خواهند دید که به آنها می‌گوید برای شارژ به صندوق‌دار مراجعه کنند.
5. پس از تغییر کلید روی ذخیره کلیک کنید.

نتیجه مورد انتظار: این رفتار بلافاصله برای درخواست های ورود جدید اعمال می شود. جلسات موجود تحت تأثیر قرار نمی گیرند.

چگونه یک هویت OAuth را به یک عضو موجود پیوند دهیم

اگر مشتری قبلاً یک حساب عضو داشته باشد (که به صورت دستی توسط صندوقدار ایجاد شده است) و سپس برای اولین بار از طریق OAuth وارد سیستم شود، فرآیند تأیید می تواند هویت OAuth را به حساب موجود وی پیوند دهد.

1. هنگامی که درخواست ورود OAuth به صفحه درخواست ها می رسد، بررسی کنید که آیا ایمیل با یک عضو موجود مطابقت دارد یا خیر.
2. اگر سیستم مطابقت را تشخیص دهد، گفتگوی تأیید به جای ایجاد یک حساب جدید، پیوند هویت OAuth را به عضو موجود پیشنهاد می‌کند.
3. با انتخاب گزینه لینک درخواست را تایید کنید.

نتیجه مورد انتظار: حساب عضو موجود پیوند OAuth دریافت می کند. ورودهای آینده از این ارائه‌دهنده مرحله تأیید را دور می‌زنند و عضو را مستقیماً (پس از اولین تأیید) وارد می‌کنند.

اشتباهات رایجی که باید از آنها اجتناب کرد

• استفاده از نوع مشتری OAuth اشتباه در Google Cloud Console. هنگام ایجاد شناسه مشتری OAuth باید "TVs and Limited Input devices" را انتخاب کنید. اگر «برنامه وب» یا «برنامه دسک‌تاپ» را انتخاب کنید، جریان مجوز دستگاه کار نمی‌کند و کلاینت نمی‌تواند کد دستگاه را دریافت کند.
• فراموش کردن فعال کردن کلید جهانی OAuth. فعال کردن ارائه دهندگان جداگانه کافی نیست. کلید اصلی OAuth در بالای صفحه تنظیمات OAuth نیز باید روشن باشد.
• تأیید نشدن درخواست های ورود به سیستم. ورود به سیستم OAuth نیاز به تایید صریح از طرف سرور دارد. اگر کسی صفحه درخواست ها را نظارت نکند، مشتریان به طور نامحدود در صفحه بیکار منتظر خواهند ماند. تعیین یک صندوقدار برای نظارت بر درخواست ها در ساعات شلوغی را در نظر بگیرید.
• به کدهای دستگاه اجازه انقضا داده شود. عمر کدهای دستگاه محدود است (معمولاً 10-5 دقیقه). اگر مشتری برای اسکن کد QR و احراز هویت خیلی طول بکشد، کد منقضی می‌شود و باید دوباره شروع به کار کند. به مشتریان توصیه کنید که به سرعت اسکن کنند.
• چسباندن اعتبارنامه ها با فضای خالی اضافی. هنگام کپی کردن Client ID یا Client Secret از کنسول ارائه دهنده، مطمئن شوید که فضای اصلی یا انتهایی وجود ندارد. فضای خالی اضافی باعث خرابی احراز هویت می شود.
• فراموش کردن انتشار برنامه Google OAuth. برنامه های Google در حالت "تست" فقط به تعداد محدودی از کاربران آزمایشی اجازه می دهند. برای اینکه به هر مشتری اجازه ورود به سیستم داده شود، باید برنامه را از طریق صفحه رضایت OAuth منتشر کنید و مراحل تأیید مورد نیاز را تکمیل کنید.
• ** مخلوط کردن Client ID و Client Secret. ** اینها دو مقدار متفاوت هستند. شناسه مشتری عمومی است. راز مشتری باید محرمانه نگه داشته شود. تعویض آنها باعث خرابی احراز هویت می شود.
• پیکربندی نام کافه. نام کافه از تنظیمات HandyCafe شما در طول جریان OAuth روی صفحه بیکار مشتری نمایش داده می شود. یک نام خالی یا پیش فرض غیرحرفه ای به نظر می رسد. قبل از فعال کردن OAuth، نام کافه خود را در تنظیمات > عمومی تنظیم کنید.