چگونه ورود با OAuth را تنظیم کنیم
این راهنما شما را در تنظیم ورود اجتماعی راهنمایی میکند تا مشتریان بتوانند با استفاده از حسابهای گوگل، فیسبوک، اپل، X یا دیسکورد خود به کامپیوترهای مشتری وارد شوند. HandyCafe از جریان Device Authorization Grant (RFC 8628) استفاده میکند که برای دستگاههای بدون مرورگر کامل طراحی شده است. مشتریان با اسکن یک کد QR با تلفن خود احراز هویت میکنند.
آنچه نیاز خواهید داشت
- دسترسی ادمین به سرور HandyCafe.
- یک حساب Google Cloud Console (برای Google OAuth) یا دسترسی به پورتال توسعهدهنده معادل برای سایر ارائهدهندگان.
- سرور HandyCafe که در شبکه شما در حال اجرا و قابل دسترسی باشد.
- حداقل یک کامپیوتر مشتری متصل برای تست جریان ورود.
نحوه کارکرد جریان OAuth دستگاه در HandyCafe
قبل از ورود به تنظیمات، خلاصهای از جریان را در اینجا آوردهایم:
- مشتری در یک کامپیوتر مشتری بیکار روی دکمه ورود اجتماعی کلیک میکند (مثلاً "ورود با گوگل").
- کلاینت درخواست شروع OAuth را به سرور ارسال میکند.
- سرور با نقطه پایان مجوز دستگاه ارائهدهنده تماس میگیرد و یک کد دستگاه، یک کد کاربر و یک URL تأیید دریافت میکند.
- کلاینت یک کد QR و کد کاربر را روی صفحه بیکار نمایش میدهد.
- مشتری کد QR را با تلفن خود اسکن کرده و با ارائهدهنده احراز هویت میکند.
- سرور تا تکمیل احراز هویت، ارائهدهنده را نظارت میکند.
- سرور یک درخواست ورود OAuth ایجاد میکند که در صفحه درخواستها ظاهر میشود.
- یک ادمین یا صندوقدار درخواست را تأیید میکند.
- یک حساب کاربری جدید ایجاد میشود (یا یک حساب موجود متصل میشود) و مشتری وارد میشود.
چگونه Google OAuth را تنظیم کنیم
گوگل رایجترین ارائهدهنده است. این بخش هر مرحله از ایجاد پروژه Google Cloud تا تست اولین ورود را پوشش میدهد.
بخش A: ایجاد اعتبارنامههای Google Cloud
- کنسول Google Cloud را در مرورگر خود در https://console.cloud.google.com باز کنید.
- یک پروژه جدید ایجاد کنید یا یک پروژه موجود را انتخاب کنید. نامی قابل شناسایی مانند "HandyCafe OAuth" به آن بدهید.
- به APIs & Services > OAuth consent screen بروید.
- External را به عنوان نوع کاربر انتخاب کنید (مگر اینکه یک سازمان Google Workspace داشته باشید و بخواهید فقط داخلی باشد).
- فیلدهای مورد نیاز را پر کنید: نام برنامه ("نام کافه شما")، ایمیل پشتیبانی کاربر، و ایمیل تماس توسعهدهنده.
- روی Save and Continue در بخشهای Scopes و Test Users کلیک کنید. نیازی به افزودن محدودههای خاص نیست. محدودههای پیشفرض ایمیل و پروفایل کافی هستند.
- به APIs & Services > Credentials بروید.
- روی Create Credentials > OAuth client ID کلیک کنید.
- برای نوع برنامه، TVs and Limited Input devices را انتخاب کنید. این مهم است. HandyCafe از جریان مجوز دستگاه استفاده میکند که به این نوع کلاینت خاص نیاز دارد.
- نامی برای کلاینت وارد کنید (مثلاً "HandyCafe Device Flow").
- روی Create کلیک کنید.
- Client ID و Client Secret را از دیالوگ تأیید کپی کنید. آنها را بهطور ایمن ذخیره کنید. به هر دو مقدار در بخش بعدی نیاز خواهید داشت.
بخش B: تنظیم سرور HandyCafe
- برنامه سرور HandyCafe را باز کنید.
- با استفاده از آیکون چرخدنده در نوار کناری سمت چپ به Settings بروید.
- برگه OAuth را انتخاب کنید.
- سوئیچ OAuth را در بالای صفحه فعال کنید. این بهطور کلی ورود اجتماعی را در تمام کامپیوترهای مشتری فعال میکند.
- ردیف ارائهدهنده Google را در لیست ارائهدهندگان پیدا کنید.
- سوئیچ گوگل را برای فعالسازی این ارائهدهنده فعال کنید.
- Client ID خود را از مرحله 12 در فیلد Client ID وارد کنید.
- Client Secret خود را از مرحله 12 در فیلد Client Secret وارد کنید.
- روی Save کلیک کنید تا تنظیمات اعمال شود.
نتیجه مورد انتظار: برگه OAuth نشان میدهد که گوگل با اعتبارنامههای شما فعال شده است. تنظیمات به تمام کلاینتهای متصل ارسال میشود.
بخش C: تست جریان ورود
- به یک کامپیوتر مشتری متصل بروید. صفحه بیکار اکنون باید بخشی برای ورود اجتماعی با دکمه ورود گوگل نشان دهد.
- روی دکمه ورود Google در صفحه بیکار کلاینت کلیک کنید.
- کلاینت یک کد QR و یک کد کاربر (یک رشته کوتاه الفبایی) نمایش میدهد.
- کد QR را با تلفن خود اسکن کنید. صفحه تأیید دستگاه گوگل باز میشود.
- با یک حساب گوگل وارد شوید و کد کاربر را زمانی که خواسته شد وارد کنید.
- برنامه را تأیید کنید.
نتیجه مورد انتظار: در سرور، صدای اعلان پخش میشود و یک ورودی جدید در صفحه درخواستها ظاهر میشود. درخواست نام حساب گوگل، آدرس ایمیل و کامپیوتر مشتری که ورود را آغاز کرده است را نشان میدهد.
چگونه یک درخواست ورود را تأیید کنیم
هر ورود OAuth یک درخواست ایجاد میکند که باید توسط یک ادمین یا صندوقدار تأیید شود تا مشتری به دسترسی پیدا کند.
- وقتی یک درخواست ورود میرسد، صدای اعلان در سرور پخش میشود و یک نشان روی آیکون صفحه درخواستها در نوار کناری ظاهر میشود.
- به صفحه Requests بروید.
- درخواست در حال انتظار نشان میدهد:
- نام ارائهدهنده (مثلاً گوگل).
- نام نمایشی از ارائهدهنده (مثلاً "جان اسمیت").
- آدرس ایمیل (مثلاً "john@example.com").
- کامپیوتر مشتری که درخواست را آغاز کرده است (نام میزبان یا نام نمایشی).
- زمانسنجی.
- جزئیات درخواست را بررسی کنید. تأیید کنید که شخص در کامپیوتر مشتری با اطلاعات حساب مطابقت دارد.
- روی Approve کلیک کنید تا درخواست پذیرفته شود.
نتیجه مورد انتظار: اگر هیچ حساب کاربری موجودی به این هویت OAuth متصل نباشد، بهطور خودکار یک حساب کاربری جدید ایجاد میشود. نام نمایشی و ایمیل از ارائهدهنده استفاده میشود. مشتری وارد میشود و کامپیوتر مشتری از صفحه بیکار به صفحه آنلاین منتقل میشود. اگر یک حساب کاربری قبلاً به این هویت OAuth متصل شده باشد، عضو موجود بهطور مستقیم وارد میشود.
نکته: اگر درخواست ورود مشکوک است (مثلاً کامپیوتر بدون نظارت است یا درخواست به نظر خودکار میآید)، بهجای آن روی Reject کلیک کنید. مشتری پیام "دسترسی رد شد" را میبیند و میتواند دوباره تلاش کند.
چگونه Facebook OAuth را تنظیم کنیم
- پورتال توسعهدهنده فیسبوک را در https://developers.facebook.com باز کنید.
- یک برنامه جدید ایجاد کنید. نوع برنامه Consumer را انتخاب کنید.
- به صفحه Settings > Basic برنامه بروید. App ID و App Secret را یادداشت کنید.
- به Add Product بروید و Facebook Login for Devices را اضافه کنید.
- در تنظیمات Facebook Login for Devices، در صورت نیاز به پورتال، URIهای بازگشت خود را اضافه کنید.
- سرور HandyCafe را باز کنید و به Settings > OAuth بروید.
- ردیف ارائهدهنده Facebook را پیدا کنید.
- سوئیچ فیسبوک را فعال کنید.
- App ID را در فیلد Client ID وارد کنید.
- App Secret را در فیلد Client Secret وارد کنید.
- روی Save کلیک کنید.
نتیجه مورد انتظار: فیسبوک به عنوان یک ارائهدهنده فعال ظاهر میشود. صفحههای بیکار کلاینت یک دکمه ورود فیسبوک را در کنار هر ارائهدهنده فعال دیگر نشان میدهند.
چگونه Discord OAuth را تنظیم کنیم
- پورتال توسعهدهنده دیسکورد را در https://discord.com/developers/applications باز کنید.
- یک برنامه جدید ایجاد کنید. آن را به نام کافه خود نامگذاری کنید.
- به بخش OAuth2 در نوار کناری سمت چپ بروید.
- Client ID را کپی کنید و یک Client Secret تولید کنید. راز را بهطور ایمن ذخیره کنید زیرا دیسکورد فقط یک بار آن را نشان میدهد.
- سرور HandyCafe را باز کنید و به Settings > OAuth بروید.
- ردیف ارائهدهنده Discord را پیدا کنید (بهطور پیشفرض غیرفعال است).
- سوئیچ دیسکورد را فعال کنید.
- Client ID را در فیلد Client ID وارد کنید.
- Client Secret را در فیلد Client Secret وارد کنید.
- روی Save کلیک کنید.
نتیجه مورد انتظار: دیسکورد اکنون به عنوان یک گزینه ورود در صفحههای بیکار کلاینت در دسترس است.
چگونه ورود بدون اعتبار را مجاز کنیم
بهطور پیشفرض، HandyCafe به مشتریانی که از طریق OAuth احراز هویت میکنند اجازه میدهد حتی اگر موجودی کیف پول یا اعتبار زمانی نداشته باشند وارد شوند. میتوانید این رفتار را تغییر دهید.
- به Settings > OAuth بروید.
- سوئیچ Allow Login Without Credit را پیدا کنید.
- اگر فعال باشد (پیشفرض)، مشتریانی که از طریق OAuth احراز هویت میکنند میتوانند بدون توجه به موجودی خود وارد شوند. یک صندوقدار میتواند یک جلسه پسپرداخت برای آنها شروع کند.
- اگر غیرفعال باشد، مشتریان باید یا موجودی کیف پول یا اعتبار زمانی داشته باشند تا وارد شوند. مشتریانی که موجودی صفر دارند پیامی خواهند دید که به آنها میگوید به صندوقدار مراجعه کنند تا موجودی خود را افزایش دهند.
- پس از تغییر سوئیچ، روی Save کلیک کنید.
نتیجه مورد انتظار: رفتار بلافاصله برای درخواستهای ورود جدید اعمال میشود. جلسات موجود تحت تأثیر قرار نمیگیرند.
چگونه یک هویت OAuth را به یک عضو موجود متصل کنیم
اگر مشتری قبلاً یک حساب کاربری عضو داشته باشد (که بهطور دستی توسط یک صندوقدار ایجاد شده است) و سپس برای اولین بار از طریق OAuth وارد شود، فرآیند تأیید میتواند هویت OAuth را به حساب موجود آنها متصل کند.
- وقتی درخواست ورود OAuth در صفحه درخواستها میرسد، بررسی کنید که آیا ایمیل با یک عضو موجود مطابقت دارد.
- اگر سیستم یک تطابق را تشخیص دهد، دیالوگ تأیید پیشنهاد میدهد که هویت OAuth را به عضو موجود متصل کند بهجای ایجاد یک حساب جدید.
- درخواست را با گزینه لینک انتخابشده تأیید کنید.
نتیجه مورد انتظار: حساب کاربری موجود یک لینک OAuth دریافت میکند. ورودهای آینده از این ارائهدهنده مرحله تأیید را دور میزنند و عضو را مستقیماً وارد میکنند (پس از اولین تأیید).
اشتباهات رایج برای اجتناب
- استفاده از نوع کلاینت OAuth اشتباه در Google Cloud Console. شما باید "TVs and Limited Input devices" را هنگام ایجاد شناسه کلاینت OAuth انتخاب کنید. اگر "Web application" یا "Desktop app" را انتخاب کنید، جریان مجوز دستگاه کار نخواهد کرد و کلاینت نمیتواند کد دستگاه دریافت کند.
- فراموش کردن فعالسازی سوئیچ جهانی OAuth. فعالسازی ارائهدهندگان فردی کافی نیست. سوئیچ اصلی OAuth در بالای صفحه تنظیمات OAuth نیز باید روشن باشد.
- عدم تأیید درخواستهای ورود. ورودهای OAuth نیاز به تأیید صریح از سرور دارند. اگر هیچکس صفحه درخواستها را نظارت نکند، مشتریان بهطور نامحدود در صفحه بیکار منتظر خواهند ماند. در نظر بگیرید که یک صندوقدار را برای نظارت بر درخواستها در ساعات شلوغ اختصاص دهید.
- اجازه دادن به انقضای کدهای دستگاه. کدهای دستگاه عمر محدودی دارند (معمولاً 5-10 دقیقه). اگر مشتری برای اسکن کد QR و احراز هویت بیش از حد طول بکشد، کد منقضی میشود و آنها باید دوباره شروع کنند. به مشتریان توصیه کنید که بهسرعت اسکن کنند.
- چسباندن اعتبارنامهها با فضای اضافی. هنگام کپی کردن Client ID یا Client Secret از کنسول ارائهدهنده، اطمینان حاصل کنید که هیچ فضای پیشرو یا پسرو وجود ندارد. فضای اضافی باعث شکست احراز هویت خواهد شد.
- فراموش کردن انتشار برنامه Google OAuth. برنامههای گوگل در حالت "Testing" فقط به تعداد محدودی از کاربران آزمایشی اجازه میدهند. برای اینکه هر مشتری بتواند وارد شود، باید برنامه را از طریق صفحه صفحه تأیید OAuth منتشر کنید و هر مرحله تأیید مورد نیاز را تکمیل کنید.
- مخلوط کردن Client ID و Client Secret. اینها دو مقدار مختلف هستند. Client ID عمومی است. Client Secret باید محرمانه نگه داشته شود. جابجایی آنها باعث شکست احراز هویت خواهد شد.
- عدم تنظیم نام کافه. نام کافه از تنظیمات HandyCafe شما در صفحه بیکار کلاینت در طول جریان OAuth نمایش داده میشود. یک نام خالی یا پیشفرض غیرحرفهای به نظر میرسد. نام کافه خود را در Settings > General قبل از فعالسازی OAuth تنظیم کنید.