{
  "title": "انتخاب پلتفرم احراز هویت و هویت کاربری",
  "slug": "team/backend/ADR/ADR-Backend-001",
  "url": "/docs/team/backend/ADR/ADR-Backend-001",
  "frontmatter": {
    "layout": "doc",
    "title": "انتخاب پلتفرم احراز هویت و هویت کاربری",
    "description": "مستند تصمیم‌گیری معماری (ADR) درباره انتخاب پلتفرم احراز هویت و هویت کاربری در پلتفرم NONS",
    "version": "1.0.0",
    "status": "APPROVED",
    "author": "Backend Team",
    "owner": "Backend Team",
    "created_at": "2026-06-13",
    "updated_at": "2026-07-14",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "انتخاب پلتفرم احراز هویت و هویت کاربری",
      "content": "**Authentication & Identity Platform Selection**\n\n> **ADR-Backend-001**\n\n> **بروزرسانی ۱۴۰۵/۰۴/۲۳ (بایگانی در ADR-Backend-006 / بخش Archive A1):** تصمیم تعلیق Hydra (Deferred) طبق ADR-Backend-006 و Blueprint v3.3 لغو شد. **Ory Hydra اکنون به عنوان `token-service` (سرور OAuth2/OIDC رسمی) پذیرفته شده است.** بخش‌های مربوط به تعلیق Hydra و session-cookie-only با معماری جدید جایگزین شده‌اند — رجوع به `nons-api/services/token-service/blueprint.md` و `ADR-Backend-006.md`.\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 به یک سامانه احراز هویت نیاز دارد که:\n- مستقل از سرویس‌های خارجی باشد.\n- قابلیت استقرار کامل در زیرساخت اختصاصی را داشته باشد.\n- از امنیت و پایداری بالایی برخوردار باشد.\n- با معماری Microservice و سیستم مسیریابی Gateway سازگار باشد.\n- وابستگی به Vendor خاص ایجاد نکند.\n- برای استفاده در محیط Production قابل اعتماد و اثبات‌شده باشد.\n\nدر فازهای نخست، گزینه‌های متعددی چون SuperTokens بررسی شدند، اما به دلیل وابستگی به سرورهای خارجی رد گردیدند. همچنین استقرار همزمان زوج Ory Kratos (برای هویت) و Ory Hydra (برای توکن‌های OAuth2/OIDC) مورد تصمیم‌گیری قرار گرفت. پیچیدگی‌های عملیاتی اولیهٔ Hydra (امضاهای دیجیتال، توزیع JWKS، چرخش توکن) با الگوهای استاندارد Ory (login-consent-app + چرخش کلید) قابل مدیریت تشخیص داده شد و در نهایت Hydra به عنوان `token-service` رسمی پذیرفته شد (رجوع به Blueprint v3.2).\n\n---"
    },
    {
      "level": 2,
      "heading": "تصمیم معماری",
      "content": "**Decision**\n\nپلتفرم NONS از موتور **Ory Kratos** به همراه یک **سرویس اختصاصی احراز هویت (Go Auth Service)** بر پایه معماری **نشست‌محور (Session-Cookie Based)** و اعتبارسنجی درگاه با استفاده از **Traefik ForwardAuth** استفاده می‌کند.\n\nاجزای اصلی لایه احراز هویت فعلی عبارتند از:"
    },
    {
      "level": 3,
      "heading": "اوری کراتوس",
      "content": "**Ory Kratos**\n\nمسئول:\n- مدیریت مشخصات وTraits کاربران (ایمیل، نام و وضعیت اونبوردینگ).\n- ثبت‌نام و ایجاد هویت‌های جدید (Auto Sign-Up).\n- احراز هویت بدون رمز عبور (Magic Code/OTP).\n- ورود با گوگل (Google OIDC).\n- مدیریت نشست‌های کاربری (Browser Sessions)."
    },
    {
      "level": 3,
      "heading": "سرویس احراز هویت",
      "content": "**Auth Service**\n\nسرویس سبک نوشته شده با Go که:\n- صفحات ورود، ثبت‌نام و داشبورد را در داخل خود رندر و به کاربر ارائه می‌دهد (بدون وابستگی به فرانت‌اند خارجی).\n- فلوهای ورود و ثبت‌نام یکپارچه را به موتور Kratos پروکسی می‌کند.\n- نقطه پایانی `/v1/auth/validate` را جهت اعتبارسنجی نشست‌های کاربری برای درگاه Traefik Gateway فراهم می‌سازد."
    },
    {
      "level": 3,
      "heading": "وضعیت Ory Hydra (به‌روزرسانی ۱۴۰۵/۰۴/۲۳)",
      "content": "تصمیم قبلی مبنی بر «تعلیق (Deferred) استقرار Ory Hydra» **لغو شد**. طبق ADR-Backend-006 و Blueprint v3.3، **Ory Hydra اکنون به عنوان `token-service` (سرور رسمی OAuth2/OIDC) پذیرفته شده است** و مسئول صدور/ابطال توکن‌های API است. احراز هویت مرورگر همچنان بر عهدهٔ Kratos + Traefik ForwardAuth باقی می‌ماند؛ صدور توکن‌های استاندارد API بر عهدهٔ Hydra است. واسط بین این دو از طریق `login-consent-app` (سرویس مستقل Go) انجام می‌شود.\n\n---"
    },
    {
      "level": 2,
      "heading": "اصول معماری",
      "content": "**Architecture Principles**"
    },
    {
      "level": 3,
      "heading": "اولویت استقرار محلی و معماری کلاستر (D13, D15)",
      "content": "**Self Hosted First & Cluster Architecture**\n\nتمام اجزای احراز هویت در کلاستر Kubernetes (K3s در پروداکشن و K3d در محیط توسعه) مستقر می‌شوند (D13) و فرآیند مدیریت آن‌ها با Helm انجام می‌گیرد (D15). هیچ وابستگی به سرویس‌های هویت خارجی (مانند Auth0) وجود ندارد."
    },
    {
      "level": 3,
      "heading": "امنیت در درگاه Gateway",
      "content": "**Gateway Security**\n\nدرگاه Gateway (Traefik) با استفاده از مکانیزم ForwardAuth هر درخواست ورودی به مسیرهای محافظت‌شده را به صورت محلی به `auth-service` هدایت کرده تا از وجود نشست معتبر اطمینان حاصل کند.\n\n---"
    },
    {
      "level": 2,
      "heading": "گزینه‌های بررسی شده",
      "content": "**Alternatives Considered**"
    },
    {
      "level": 3,
      "heading": "سوپرتوکنز",
      "content": "**SuperTokens**\n\n- **نتیجه:** رد شد (Rejected) - به دلیل وابستگی عملیاتی بالا به سرورهای ابری خارجی."
    },
    {
      "level": 3,
      "heading": "کی‌کلاک",
      "content": "**Keycloak**\n\n- **نتیجه:** انتخاب نشد (Not Selected) - به دلیل حجم زیاد قابلیت‌های غیرضروری و منابع سنگین مورد نیاز در کلاستر.\n\n---"
    },
    {
      "level": 2,
      "heading": "پیامدها",
      "content": "**Consequences**"
    },
    {
      "level": 3,
      "heading": "پیامدهای مثبت",
      "content": "**Positive Consequences**\n\n- اعتبارسنجی محلی توکن‌های API توسط میکروسرویس‌ها با JWKS (بدون تماس همزمان با auth-service).\n- ساده‌سازی مکانیزم اعتبارسنجی هویت با اتکا به نشست‌های استاندارد Kratos.\n- بهبود تجربه توسعه با مدیریت متمرکز صفحات ورود و ثبت‌نام در قالب‌های سبک Go."
    },
    {
      "level": 3,
      "heading": "پیامدهای منفی",
      "content": "**Negative Consequences**\n\n- نیاز به مدیریت عملیاتی Hydra (چرخش کلید JWKS، NetworkPolicy برای Admin API، نگهداری login-consent-app) — از طریق Helm و CronJob در Blueprint v3.2 پوشش داده شد.\n\n---"
    },
    {
      "level": 2,
      "heading": "تصمیم نهایی",
      "content": "**Final Decision**\n\nمعماری احراز هویت NONS بر پایه **Ory Kratos (هویت/نشست) + Hydra (token-service / OAuth2-OIDC) + Auth Service (Go) + Traefik ForwardAuth** مستقر و نهایی گردیده است. واسط بین Kratos و Hydra از طریق `login-consent-app` (سرویس مستقل Go) انجام می‌شود. این معماری استقلال کامل، صدور توکن‌های استاندارد و اعتبارسنجی محلی را تضمین می‌کند (رجوع به Blueprint v3.3 و ADR-Backend-006)."
    }
  ]
}