111 lines
12 KiB
Markdown
111 lines
12 KiB
Markdown
# مشخصات درس‌نامه: ارائه‌دهندگان احراز هویت خارجی (Google، GitHub و الگوی ورود پیامکی)
|
||
- **شناسه در سیلابس:** `L10.6`
|
||
- **فصل:** فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
|
||
- **نوع محتوا:** 📘 درس‌نامه متنی
|
||
- **زمان تقریبی مطالعه:** ۱۸ دقیقه
|
||
- **پیش‌نیازهای مستقیم:** `L10.5` (ارسال ایمیل‌های تراکنشی با SMTP)
|
||
|
||
---
|
||
|
||
## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
|
||
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
|
||
- [ ] **درک کند (Understand):** سازوکار پروتکل استانداردهای احراز هویت اجتماعی (OAuth 2.0) را شرح دهد و بداند چرا ورود با یک کلیک، نرخ تبدیل و رضایت کاربران را به شدت افزایش می‌دهد.
|
||
- [ ] **تحلیل/ارزیابی کند (Evaluate):** مزایا و معایب ورود با حساب‌های بین‌المللی (Google و GitHub) را در مقایسه با الگوی غالب بومی ایران یعنی ورود با رمز یک‌بارمصرف پیامکی (SMS OTP) ارزیابی کند.
|
||
- [ ] **به‌کار ببندد (Apply):** ارائه‌دهندگان GitHub و Google را در کنسول Supabase پیکربندی کرده و دکمه‌های ورود با یک کلیک را در پنل ادمین پورتفولیو فعال نماید.
|
||
- [ ] **ایجاد کند (Create):** معماری و جریان گام‌به‌گام پیاده‌سازی ورود با شماره موبایل و کد یک‌بارمصرف پیامکی (OTP) با وب‌سرویس کاوه‌نگار/SMS.ir را طراحی و مستند کند.
|
||
|
||
---
|
||
|
||
## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)
|
||
|
||
### آنچه باید پوشش داده شود (In-Scope):
|
||
1. **پایان دوران فرم‌های ثبت‌نام طولانی با رمزهای عبور فراموش‌شدنی:**
|
||
* چرا هیچ کاربری حوصله انتخاب رمز ۱۲ رقمی با حروف بزرگ و کوچک و نماد را ندارد؟
|
||
2. **پروتکل OAuth 2.0 به زبان بسیار ساده:**
|
||
* استعاره کلید هتل و کارت اتاق: گوگل یا گیت‌هاب هویت کاربر را تایید می‌کنند و به پورتفولیوی شما یک کارت تردد موقت (Access Token) می‌دهند.
|
||
3. **مراحل فعال‌سازی ورود با GitHub و Google در Supabase:**
|
||
* ساخت OAuth App در تنظیمات توسعه‌دهندگان GitHub (Developer Settings).
|
||
* ساخت پروژه و دریافت Client ID و Client Secret در Google Cloud Console.
|
||
* تنظیم Callback URL سوپابیس (`https://<project-id>.supabase.co/auth/v1/callback`).
|
||
* فعال‌سازی تاگل ارائه‌دهنده در داشبورد Authentication سوپابیس.
|
||
4. **کدنویسی فرانت‌اند Next.js برای دکمه‌های ورود:**
|
||
* فراخوانی ساده `supabase.auth.signInWithOAuth({ provider: 'github' })`.
|
||
* هدایت خودکار کاربر پس از ورود موفق به پنل مدیریت (`/admin`).
|
||
5. **معماری الگوی ورود بومی ایرانی: لاگین پیامکی (SMS OTP Login):**
|
||
* بررسی چرخه ورود در اپ‌های محبوب مانند اسنپ و دیجی‌کالا:
|
||
- ۱. کاربر شماره موبایل خود را وارد می‌کند.
|
||
- ۲. سرور یک کد تصادفی ۵ رقمی تولید کرده و با زمان انقضای ۲ دقیقه (TTL) در جدول یا سشن ذخیره می‌کند.
|
||
- ۳. فراخوانی الگوی اعتبارسنجی وب‌سرویس کاوه‌نگار/SMS.ir برای تحویل در ۲ ثانیه.
|
||
- ۴. کاربر کد را وارد می‌کند؛ سرور مطابقت داده و سشن لاگین ایجاد می‌کند.
|
||
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
|
||
* کال‌اوت بنفش (`<details class="violet">`): تفاوت OAuth (احراز هویت و اجازه دسترسی) با OIDC (شناسایی هویت پروفایل کاربر).
|
||
* کال‌اوت سبز (`<details class="green">`): مدیریت خودکار کوکی‌ها و رفرش توکن‌ها توسط کتابخانه `@supabase/ssr`.
|
||
* کال‌اوت قرمز (`<details class="red">`): تله خطای رایج `redirect_uri_mismatch`؛ تطابق نداشتن آدرس لوکال‌هاست با دامنه ثبت شده در کنسول گوگل.
|
||
|
||
### آنچه نباید وارد آن شویم (Out-of-Scope):
|
||
- احراز هویت دو مرحله‌ای سخت‌افزاری (Hardware YubiKey).
|
||
- اتصال سیستم‌های سازمانی Active Directory و SAML SSO.
|
||
|
||
---
|
||
|
||
## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
|
||
|
||
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|
||
| :--- | :--- | :--- |
|
||
| OAuth 2.0 | پروتکل تفویض دسترسی آزاد | استاندارد امنیتی که به کاربران اجازه می‌دهد بدون اشتراک رمز عبور، با اکانت گوگل/گیت‌هاب وارد شوند |
|
||
| Social Login | ورود با شبکه‌های اجتماعی | قابلیت احراز هویت سریع با فشردن دکمه ورود از طریق حساب‌های کاربری موجود |
|
||
| Callback URL / Redirect URI | آدرس بازگشت مجاز | نشانی مشخصی از سایت شما که ارائه‌دهنده پس از تایید هویت، کاربر را به آن برمی‌گرداند |
|
||
| Client ID & Client Secret | شناسه و رمز کلاینت | شناسه عمومی و رمز فوق‌محرمانه برنامه شما نزد گوگل یا گیت‌هاب |
|
||
| OTP (One-Time Password) | رمز یک‌بارمصرف | کد موقت و معمولاً چندرقمی که تنها برای یک‌بار ورود و در بازه زمانی کوتاه معتبر است |
|
||
| TTL (Time To Live) | طول عمر اعتبار | مدت زمانی که یک کد موقت یا سشن پیش از باطل شدن خودکار معتبر باقی می‌ماند |
|
||
|
||
---
|
||
|
||
## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
|
||
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
|
||
|
||
1. **تصویر کاور درس:** `images/cover.png`
|
||
* **موضوع:** صفحه ورود شیک با دکمه‌های ورود با یک کلیک گوگل و گیت‌هاب و فیلد دریافت کد تایید پیامکی موبایل.
|
||
2. **چرخه ۴ مرحله‌ای تبادل هویت با OAuth 2.0:** `images/oauth2-flow-diagram.png`
|
||
* **موضوع:** فلوچارت: کاربر روی «ورود با گیت‌هاب» می‌زند $\rightarrow$ انتقال به گیت‌هاب $\rightarrow$ تایید کاربر $\rightarrow$ بازگشت توکن به سوپابیس $\rightarrow$ باز شدن پنل ادمین.
|
||
3. **تنظیمات کلیدهای گوگل و گیت‌هاب در داشبورد Supabase:** `images/supabase-auth-providers-setup.png`
|
||
* **موضوع:** اسکرین‌شات از پنل Supabase Authentication Providers با فیلدهای Client ID و Secret پر شده.
|
||
4. **فلوچارت ورود پیامکی بومی (SMS OTP):** `images/sms-otp-architecture.png`
|
||
* **موضوع:** اینفوگرافیک معماری: دریافت شماره $\rightarrow$ تولید کد ۵ رقمی $\rightarrow$ ارسال با وب‌سرویس پترن کاوه‌نگار $\rightarrow$ اعتبارسنجی ورودی کاربر $\rightarrow$ تولید سشن ورود.
|
||
|
||
---
|
||
|
||
## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)
|
||
|
||
1. **تیتر اصلی:** `# ارائه‌دهندگان احراز هویت خارجی (Google، GitHub و الگوی ورود پیامکی)`
|
||
2. **مقدمه:** چرا ورود با یک کلیک (Social Login) و ورود پیامکی، کاربران را از کابوس به خاطر سپردن ده‌ها رمز عبور نجات می‌دهد؟
|
||
3. **جدول کاور درس**
|
||
4. **استعاره کارت شناسایی بین‌المللی و پاسپورت معتبر:**
|
||
* وقتی گوگل هویت کاربر را تایید می‌کند، چرا شما دوباره از کاربر سوال بپرسید؟
|
||
5. **پروتکل OAuth 2.0 چگونه کار می‌کند؟**
|
||
* کالبدشکافی جریان ریدایرکت، رضایت کاربر، و تحویل توکن سشن.
|
||
6. **راه‌اندازی گام‌به‌گام ورود با GitHub در Supabase:**
|
||
* آموزش تصویری ساخت OAuth App در گیت‌هاب و وارد کردن کلیدها در کنسول سوپابیس.
|
||
7. **راه‌اندازی ورود با Google Cloud:**
|
||
* فعال‌سازی OAuth Consent Screen و ساخت Credentials در پنل گوگل.
|
||
8. **پیاده‌سازی دکمه‌های ورود در صفحه `/admin/login` پورتفولیو:**
|
||
* کد کامپوننت React با آیکون‌های رسمی Google و GitHub و انیمیشن لودینگ.
|
||
9. **الگوی ورود بومی ایران: احراز هویت پیامکی (SMS OTP):**
|
||
* چرا در کسب‌وکارهای ایرانی، شماره موبایل هویت اصلی کاربر است؟
|
||
* بررسی معماری ۴ گامی ساخت سیستم ورود پیامکی با کاوه‌نگار/SMS.ir.
|
||
10. **جعبه پرامپت طلایی: اتصال دکمه‌های ورود اجتماعی به ایجنت:**
|
||
* پرامپت دقیق:
|
||
> «من ارائه‌دهنده‌های Google و GitHub را در Supabase فعال کرده‌ام. لطفاً کامپوننت لاگین را به‌روزرسانی کن تا دکمه‌های شکیل ورود با گیت‌هاب و گوگل به آن اضافه شوند. هنگام کلیک، تابع `signInWithOAuth` فراخوانی شود و در صورت موفقیت کاربر مستقیماً به داشبورد `/admin` هدایت گردد.»
|
||
11. **باکس نکته Quera (`<details class="violet">`):** اهمیت هماهنگی دقیق Redirect URL در محیط Localhost و پس از دیپلوی روی دامنه نهایی.
|
||
12. **باکس هشدار Quera (`<details class="red">`):** تله فاش کردن `Client Secret` گوگل در کدهای فرانت‌اند؛ این کلید فقط و فقط باید در پنل پشتیبانی سوپابیس ثبت شود.
|
||
13. **باکس انرژی‌بخش Quera (`<details class="green">`):** آزمایش لاگین با گیت‌هاب شخصی خودتان و دیدن عکس پروفایل و ایمیلتان در داشبورد ادمین پورتفولیو.
|
||
14. **جمع‌بندی درس‌نامه:** تکمیل مکانیزم‌های ورود؛ ورود به جذاب‌ترین بخش تجاری: اتصال درگاه پرداخت زرین‌پال در درس بعدی.
|
||
|
||
---
|
||
|
||
## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
|
||
- [ ] اصول کارکرد پروتکل OAuth 2.0 به زبان قابل فهم برای افراد غیربرنامه‌نویس تبیین شود.
|
||
- [ ] مراحل دریافت کلیدهای GitHub و Google و تنظیم آن‌ها در Supabase به شکل عملی بیان گردد.
|
||
- [ ] معماری ورود بومی پیامکی (SMS OTP) به همراه گام‌های پیاده‌سازی تشریح شود.
|
||
- [ ] نمونه کدهای اتصال فرانت‌اند و کال‌اوت‌های هشداری امنیتی لحاظ گردند.
|