{
  "title": "طراحی جریان احراز هویت",
  "slug": "team/backend/ADR/ADR-Backend-002",
  "url": "/docs/team/backend/ADR/ADR-Backend-002",
  "frontmatter": {
    "layout": "doc",
    "title": "طراحی جریان احراز هویت",
    "description": "مستند تصمیم‌گیری معماری (ADR) درباره طراحی جریان‌های احراز هویت در بک‌اند پلتفرم NONS",
    "version": "1.0.0",
    "status": "APPROVED",
    "author": "Antigravity",
    "owner": "Backend Team",
    "created_at": "2026-06-13",
    "updated_at": "2026-06-21",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "طراحی جریان احراز هویت",
      "content": "**Authentication Flow Design**\n\n> **ADR-Backend-002**\n\n---"
    },
    {
      "level": 2,
      "heading": "وضعیت",
      "content": "**Status**\n\n✅ **تایید شده (APPROVED)**\n\n---"
    },
    {
      "level": 2,
      "heading": "تاریخ",
      "content": "**Date**\n\n2026-06-13 (به‌روزرسانی شده در 2026-06-21)\n\n---"
    },
    {
      "level": 2,
      "heading": "زمینه",
      "content": "**Context**\n\nبه منظور ارائه تجربه کاربری روان و بهینه، پلتفرم NONS نیازمند یک فلو احراز هویت یکپارچه بدون پیچیدگی‌های ثبت‌نام سنتی است. در پی اتخاذ تصمیم بر پایه Ory Kratos و Traefik ForwardAuth (مطابق [ADR-Backend-001](file:///C:/Users/ASUS/Documents/GitHub/nons/dotdive/docs/team/backend/ADR/ADR-Backend-001.md))، سیستم باید به صورت ایمن فرآیند ورود با کدهای یکبار مصرف (OTP) و گوگل را بدون نیاز به لایه فرانت‌اند خارجی هماهنگ کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "تصمیم معماری",
      "content": "**Decision**\n\nطراحی جریان احراز هویت به صورت زیر تایید و پیاده‌سازی شده است:"
    },
    {
      "level": 3,
      "heading": "۱. رابط کاربری درون‌سرویسی (Embedded HTML UI Templates)",
      "content": "سرویس `auth-service` قالب‌های سبک HTML را از داخل پاد به صورت مستقیم سرو می‌کند (با استفاده از `go:embed`). صفحات ورود، ثبت‌نام و داشبورد بدون تکیه بر وب‌سرورهای دیگر یا فرانت‌اند خارجی (مانند Next.js) پیاده‌سازی می‌شوند.\n\n**تاریخچه تصمیمات (Decision History):** در طراحی اولیه مقرر شده بود صفحات احراز هویت در لایه Next.js رندر شوند و سرویس Go صرفا به عنوان Bridge عمل کند. برای رفع ناهماهنگی کوکی‌ها در ساب‌دامنه‌ها و همچنین تضمین استقلال عملیاتی کامل، این تصمیم لغو گردید و رندرسازی صفحات به عهده قالب‌های داخلی Go قرار گرفت."
    },
    {
      "level": 3,
      "heading": "۲. فلو ورود و ثبت‌نام یکپارچه (Unified Login/Signup Flow)",
      "content": "کاربر با یک فرم واحد مواجه می‌شود. با زدن ایمیل، سیستم ابتدا ورود را در Kratos بررسی کرده و بر اساس وجود یا عدم وجود هویت، به صورت خودکار به فلو لاگین یا فلو ثبت‌نام هدایت می‌کند."
    },
    {
      "level": 3,
      "heading": "۳. بررسی نشست‌ها در Gateway با ForwardAuth",
      "content": "درگاه Traefik برای هر درخواست محافظت‌شده، از متد ForwardAuth جهت استعلام وضعیت نشست در آدرس `/v1/auth/validate` استفاده می‌کند. سرویس احراز هویت کوکی نشست کاربر را به صورت مستقیم از طریق API Kratos ارزیابی کرده و در صورت اعتبار، هدرهای شناسه را برای میکروسرویس مقصد ارسال می‌کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "جزئیات جریان‌ها",
      "content": "**Flow Details**"
    },
    {
      "level": 3,
      "heading": "جریان ورود و ثبت‌نام یکپارچه",
      "content": "```\n[کاربر] ──(1) ارسال ایمیل (/v1/auth/entry)──> [Go Auth Service]\n                                                     │\n                                            (2) بررسی در Kratos\n                                                     │\n       ┌─────────────────────────────────────────────┴─────────────────────────────────────────────┐\n       ▼ [کاربر وجود دارد]                                                                         ▼ [کاربر جدید است]\n(3) شروع فلو Login در Kratos                                                                (3) شروع فلو Registration در Kratos\n(4) ارسال OTP به ایمیل                                                                      (4) ارسال OTP به ایمیل\n(5) هدایت به صفحه /v1/auth/login?flow=...                                                   (5) هدایت به صفحه /v1/auth/register?flow=...\n(6) ارسال کد OTP و تایید سشن                                                                (6) ارسال کد OTP و تایید سشن\n       │                                                                                           │\n       └─────────────────────────────────────────────┬─────────────────────────────────────────────┘\n                                                     ▼\n                                     هدایت به /v1/auth/dashboard\n                         (در اولین ورود، onboarded به صورت ادمین true می‌شود)\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "پیامدها",
      "content": "**Consequences**"
    },
    {
      "level": 3,
      "heading": "پیامدهای مثبت",
      "content": "**Positive Consequences**\n\n- **UX یکپارچه:** کاربران بدون سردرگمی بین فرم ثبت‌نام یا ورود، فرآیند احراز هویت را در یک بخش واحد طی می‌کنند.\n- **حذف مشکلات CORS و کوکی‌ها:** قرارگیری تمام نقاط پایانی احراز هویت و رندرسازی فرم‌ها در پورت مشترک Go Auth Service، هرگونه تداخل دامنه‌ای کوکی‌های نشست Kratos را از بین برده است.\n- **امنیت پیش‌فرض در درگاه:** اعتبارسنجی ForwardAuth مانع از رسیدن هرگونه ترافیک غیرمجاز به میکروسرویس‌های تجاری می‌شود."
    },
    {
      "level": 3,
      "heading": "پیامدهای منفی",
      "content": "**Negative Consequences**\n\n- **عدم انعطاف‌پذیری استایل فرانت‌اند:** به دلیل سرو مستقیم HTMLها از Go، تغییر در ظاهر صفحات نیازمند به‌روزرسانی قالب‌های Go و اجرای اسکریپت دیپلوی است."
    }
  ]
}