{
  "title": "فلو احراز هویت و مجوزها",
  "slug": "team/backend/diagram/authentication_authorization_flow",
  "url": "/docs/team/backend/diagram/authentication_authorization_flow",
  "frontmatter": {
    "layout": "doc",
    "title": "فلو احراز هویت",
    "description": "جریان احراز هویت و مجوزها",
    "version": "1.0.0",
    "status": "APPROVED",
    "author": "xoxxel",
    "owner": "Backend Team",
    "created_at": "2026-06-07",
    "updated_at": "2026-06-21",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "فلو احراز هویت و مجوزها",
      "content": "**Authentication & Authorization Flow**\n\nاین فلو نحوه احراز هویت کاربران و بررسی مجوزهای دسترسی به سرویس‌ها را در پلتفرم NONS نشان می‌دهد."
    },
    {
      "level": 2,
      "heading": "روش‌های احراز هویت",
      "content": "- **Primary:** Magic Code — ورود با ایمیل + کد یکبار مصرف (بدون رمز عبور)\n- **Secondary:** Google Login — ورود با حساب Google (تطبیق خودکار ایمیل)\n- روش‌های `password` و `discord` از معماری سیستم حذف شده‌اند."
    },
    {
      "level": 2,
      "heading": "مراحل احراز هویت و دسترسی",
      "content": "1. **درخواست ورود** — کاربر با وارد کردن ایمیل در صفحه ورودی که توسط `auth-service` رندر شده، فرآیند را آغاز می‌کند.\n2. **بررسی و هدایت پویا** — سرویس `auth-service` فلو ورود یا ثبت‌نام را در Kratos فعال ساخته و کاربر را به صفحه ورود کد تایید (OTP) هدایت می‌کند.\n3. **تأیید و ایجاد نشست** — کاربر کد تایید ارسالی را در فرم وارد کرده و Kratos پس از تایید صحت کد، کوکی نشست را در مرورگر کاربر ثبت می‌نماید.\n4. **درخواست به مسیر محافظت شده** — مرورگر کاربر درخواستی را به یک مسیر محافظت شده (مانند `/v1/protected`) در API Gateway ارسال می‌کند.\n5. **اعتبارسنجی نشست (ForwardAuth)** — درگاه Traefik Gateway درخواست را متوقف کرده و نشست کاربر را از طریق فراخوانی مسیر `/v1/auth/validate` در `auth-service` ارزیابی می‌کند.\n6. **بررسی در Kratos** — سرویس `auth-service` کوکی نشست کاربر را به صورت مستقیم از طریق API Kratos (`/sessions/whoami`) بررسی می‌نماید.\n7. **تزریق هدرها** — در صورت معتبر بودن نشست، هدرهای `X-User-Id` (شناسه هویت Kratos) و `X-Subject` (ایمیل) تزریق شده و درخواست به سرویس مقصد هدایت می‌شود.\n8. **بررسی مجوز (Authorization)** — سرویس تجاری مقصد برای اطمینان از مجوز عملیات کاربر، از IAM درخواست بررسی مجوز می‌کند: `POST /v1/iam/authorization/check`.\n9. **کنترل دسترسی** — IAM با بررسی Authorization Context کاربر (نقش‌ها، مجوزها، محدودیت‌ها و وضعیت)، پاسخ مجاز (Allow) یا غیرمجاز (Deny) را به سرویس بازمی‌گرداند."
    },
    {
      "level": 2,
      "heading": "سرویس‌های درگیر",
      "content": "- **Ory Kratos** — موتور مدیریت هویت، ذخیره‌سازی نشست‌ها و احراز هویت با Magic Code و Google OIDC.\n- **Auth Service** — سرویس Go جهت مدیریت و رندر صفحات ورود/ثبت‌نام یکپارچه و انجام اعتبارسنجی ForwardAuth.\n- **Token Service (Ory Hydra)** — سرور OAuth2/OIDC جهت صدور access/refresh/id token و افشای JWKS. تبدیل نشست Kratos به توکن از طریق `login-consent-app` انجام می‌شود.\n- **login-consent-app** — رابط سبک بین Hydra و Kratos جهت اجرای جریان Login & Consent OAuth2.\n- **IAM Service** — سرویس مدیریت کاربران، نقش‌ها، مجوزها و Policy Engine داخلی. تمام بررسی‌های مجوز از طریق `POST /v1/iam/authorization/check` انجام می‌شود.\n- ~~**Ory Keto** — موتور بررسی مجوزها — منسوخ شده است. Policy Engine داخلی IAM جایگزین آن شده.~~\n- **API Gateway (Traefik)** — مسیریابی ترافیک و هماهنگی با ForwardAuth جهت مسدودسازی یا تایید درخواست‌ها.\n\n---"
    },
    {
      "level": 2,
      "heading": "نمودار توالی احراز هویت و مجوزها",
      "content": "```mermaid\nsequenceDiagram\n    autonumber\n    actor User as User / Browser\n    participant Gateway as Traefik Gateway\n    participant Auth as Go Auth Service\n    participant Kratos as Ory Kratos\n    participant Service as Business Service\n    participant IAM as IAM Service\n\n    User->>Auth: ورود با ایمیل و دریافت کد OTP\n    Auth->>Kratos: بررسی نشست و ایجاد فلو مناسب\n    Kratos-->>User: ارسال کوکی ory_kratos_session\n    \n    User->>Gateway: ارسال درخواست محافظت‌شده (به همراه کوکی سشن)\n    Gateway->>Auth: ForwardAuth به /v1/auth/validate\n    Auth->>Kratos: استعلام وضعیت نشست /sessions/whoami\n    alt نشست معتبر است\n        Kratos-->>Auth: اطلاعات هویت (Identity)\n        Auth-->>Gateway: وضعیت 200 OK + هدرهای X-User-Id و X-Subject\n        Gateway->>Service: هدایت درخواست به همراه هدرهای هویت\n        Service->>IAM: POST /v1/iam/authorization/check\n        IAM-->>Service: 200 { allowed: true/false }\n        Service-->>User: پاسخ نهایی درخواست\n    else نشست معتبر نیست\n        Kratos-->>Auth: خطای فاقد صلاحیت (401 Unauthorized)\n        Auth-->>Gateway: وضعیت 401 Unauthorized\n        Gateway-->>User: عدم دسترسی و ریدایرکت به صفحه لاگین\n    end\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "جریان صدور و اعتبارسنجی توکن (Token Service)",
      "content": "جریان یکپارچه‌سازی نشست Kratos با توکن‌های OAuth2 از طریق `token-service` (ORY Hydra) و `login-consent-app` انجام می‌شود. پس از دریافت `authorization code`، کلاینت آن را با `/oauth2/token` تبادل کرده و `access_token` (JWT)، `refresh_token` و (در صورت نیاز) `id_token` دریافت می‌کند.\n\nمیکروسرویس‌ها توکن را **به‌صورت stateless و محلی** با استفاده از کلید عمومی منتشر شده در JWKS endpoint (`/.well-known/jwks.json`) اعتبارسنجی می‌کنند — بدون نیاز به تماس شبکه‌ای هر بار (کلیدها cache می‌شوند).\n\n```mermaid\nsequenceDiagram\n    autonumber\n    actor User as User / Browser\n    participant FE as Frontend (SPA/SSR)\n    participant Hydra as Token Service (Hydra)\n    participant LC as login-consent-app\n    participant Kratos as Auth Service (Kratos)\n    participant Svc as Business Service\n    participant IAM as IAM Service\n\n    User->>FE: درخواست ورود\n    FE->>Hydra: GET /oauth2/auth?client_id=...&response_type=code\n    Hydra-->>LC: ریدایرکت به login-consent-app\n    LC->>Kratos: GET /sessions/whoami\n    Kratos-->>LC: اطلاعات هویت (در صورت نشست معتبر)\n    LC->>Hydra: Accept Login\n    Hydra-->>FE: authorization code\n    FE->>Hydra: POST /oauth2/token (grant_type=authorization_code)\n    Hydra-->>FE: access_token (JWT) + refresh_token (+ id_token)\n\n    Note over FE,Svc: فراخوانی API با Bearer JWT\n    FE->>Svc: Authorization: Bearer <access_token>\n    Svc->>Hydra: GET /.well-known/jwks.json (cache شده)\n    Hydra-->>Svc: کلید عمومی\n    Svc->>Svc: اعتبارسنجی امضا + استخراج claims (sub, scope, exp)\n    Svc->>IAM: POST /v1/iam/authorization/check\n    IAM-->>Svc: 200 { allowed: true/false }\n    Svc-->>User: پاسخ نهایی درخواست\n```"
    }
  ]
}