{
  "title": "استراتژی توکن‌ها و کلایم‌ها",
  "slug": "team/backend/ADR/ADR-Backend-003",
  "url": "/docs/team/backend/ADR/ADR-Backend-003",
  "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-07-14",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "استراتژی توکن‌ها و کلایم‌ها",
      "content": "**Token Strategy & Claims**\n\n> **ADR-Backend-003**\n\n> **بروزرسانی ۱۴۰۵/۰۴/۲۳ (بایگانی در ADR-Backend-006 / بخش Archive A2):** تصمیم «جایگزینی توکن JWT با کوکی نشست» (Session Cookie Only) طبق ADR-Backend-006 و Blueprint v3.3 اصلاح شد. استراتژی اکنون **ترکیبی (Hybrid)** است: نشست مرورگر از طریق کوکی Kratos، و توکن‌های API استاندارد (OAuth2/OIDC JWT) از طریق **Ory Hydra** صادر می‌شوند.\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، سرویس‌ها جهت تایید هویت کاربران نیازمند ساختاری پایدار هستند. در معماری‌های مبتنی بر توکن‌های JWT صادر شده توسط OAuth2 Provider (مانند Ory Hydra)، میکروسرویس‌ها به صورت محلی امضا را بررسی می‌کنند. با این حال، به دلیل تعلیق استقرار Ory Hydra (مطابق [ADR-Backend-001](file:///C:/Users/ASUS/Documents/GitHub/nons/dotdive/docs/team/backend/ADR/ADR-Backend-001.md))، پلتفرم نیازمند تعریف دقیق مکانیزم جایگزین در فاز فعلی جهت دریافت، بررسی و انتقال مشخصات کاربران است.\n\n---"
    },
    {
      "level": 2,
      "heading": "تصمیم معماری",
      "content": "**Decision**\n\nاستراتژی اعتبارسنجی هویت به صورت زیر تعیین گردید:"
    },
    {
      "level": 3,
      "heading": "۱. استراتژی ترکیبی (Hybrid): کوکی نشست مرورگر + توکن JWT API",
      "content": "احراز هویت در پلتفرم NONS به دو لایه تقسیم می‌شود:\n\n- **نشست مرورگر (Browser Session):** از طریق کوکی نشست صادر شده توسط Ory Kratos (`ory_kratos_session`) — مرورگر این کوکی را در درخواست‌های خود به API Gateway ارسال می‌کند و Traefik ForwardAuth آن را با Kratos تایید می‌کند.\n- **توکن‌های API (API Tokens):** توکن‌های استاندارد OAuth2/OIDC با الگوریتم RS256 توسط **Ory Hydra** (`token-service`) صادر می‌شوند؛ میکروسرویس‌ها آن‌ها را با کلیدهای عمومی JWKS به‌صورت محلی تایید می‌کنند.\n\n> **بروزرسانی ۱۴۰۵/۰۴/۲۳ (بایگانی در ADR-Backend-006 / بخش Archive A2):** تصمیم قبلی مبنی بر «جایگزینی کامل JWT با کوکی نشست» (Session Cookie Only) اصلاح شد. با پذیرش Hydra به عنوان token-service (ADR-Backend-006 / Blueprint v3.3)، توکن‌های JWT استاندارد دوباره بخشی از استراتژی رسمی هستند؛ کوکی نشست Kratos برای مرورگر باقی می‌ماند و JWTهای Hydra برای دسترسی API."
    },
    {
      "level": 3,
      "heading": "۲. اعتبارسنجی متمرکز و ارسال هدرها (Upstream Headers Injection)",
      "content": "API Gateway (درگاه Traefik) به صورت متمرکز از طریق ForwardAuth درخواست‌ها را به `auth-service` ارسال کرده و کوکی را تایید می‌کند. پس از تایید نشست در Kratos، اطلاعات هویت استخراج شده و به صورت هدرهای مشخص به میکروسرویس مقصد ارسال می‌گردند:\n- `X-User-Id`: حاوی **شناسه یکتای هویت Kratos (UUID v4)**.\n- `X-Subject`: حاوی **آدرس ایمیل کاربر**.\n\nتمامی میکروسرویس‌های تجاری موظف هستند شناسه کاربر را از هدر `X-User-Id` بخوانند و هیچ وابستگی به ساختارهای توکن دیگر نداشته باشند.\n\n---"
    },
    {
      "level": 2,
      "heading": "فیلدهای شناسه کاربری (Subject Claims)",
      "content": "**User Identity Fields**\n\nدر سراسر اکوسیستم NONS، تنها شناسه **Kratos UUID v4** به عنوان مبنای شناسایی کاربری پذیرفته می‌شود. ایمیل یا هرگونهTrait متغیر دیگر به عنوان شناسه اصلی کاربر در دیتابیس‌های میکروسرویس‌ها ذخیره نخواهد شد تا امکان تغییر ایمیل کاربر در آینده بدون آسیب به اتصالات داده‌ای پلتفرم فراهم گردد.\n\n---"
    },
    {
      "level": 2,
      "heading": "پیامدها",
      "content": "**Consequences**"
    },
    {
      "level": 3,
      "heading": "پیامدهای مثبت",
      "content": "**Positive Consequences**\n\n- **امنیت بالا در ابطال نشست (Instant Revocation):** ابطال سشن در Kratos به صورت آنی تمام دسترسی‌های کاربر را در درگاه قطع می‌کند و مشکل تأخیر همگام‌سازی توکن‌های JWT سنتی را ندارد.\n- **سادگی فوق‌العاده میکروسرویس‌ها:** میکروسرویس‌ها نیازی به پیکربندی کلیدهای JWKS یا بسته‌های اعتبارسنجی رمزنگاری ندارند و صرفا هدرهای ارسالی درگاه را می‌خوانند."
    },
    {
      "level": 3,
      "heading": "پیامدهای منفی",
      "content": "**Negative Consequences**\n\n- **سربار عملیاتی Hydra:** مدیریت چرخش کلید JWKS (CronJob ۹۰ روزه)، NetworkPolicy برای Admin API و نگهداری `login-consent-app` — طبق ADR-Backend-006 / Blueprint v3.3 پوشش داده شده است."
    }
  ]
}