{
  "title": "Auth Service",
  "slug": "team/backend/services/auth-service",
  "url": "/docs/team/backend/services/auth-service",
  "frontmatter": {
    "layout": "doc",
    "title": "Auth Service",
    "description": "سرویس احراز هویت و مدیریت نشست کاربری بر پایه Ory Kratos",
    "version": "1.0.0",
    "status": "APPROVED",
    "author": "Antigravity",
    "owner": "Backend Team",
    "created_at": "2026-06-21",
    "updated_at": "2026-06-21",
    "tags": "",
    "reviewers": ""
  },
  "sections": [
    {
      "level": 1,
      "heading": "Auth Service",
      "content": "**Auth Service Blueprint**\n\n> **مستند رسمی سیستم احراز هویت و مدیریت نشست کاربری**\n\n---"
    },
    {
      "level": 2,
      "heading": "فهرست محتوا",
      "content": "1. [هدف سرویس](#۱-هدف-سرویس)\n2. [مسئولیت‌ها](#۲-مسئولیت‌ها)\n3. [خارج از مسئولیت‌ها](#۳-خارج-از-مسئولیت‌ها)\n4. [معماری ران‌تایم و دیاگرام‌ها](#۴-معماری-ران‌تایم-و-دیاگرام‌ها)\n5. [جریان‌های احراز هویت](#۵-جریان‌های-احراز-هویت)\n6. [تنظیمات Kratos](#۶-تنظیمات-kratos)\n7. [قراردادهای API](#۷-قراردادهای-api)\n8. [راهنمای راه‌اندازی لوکال](#۸-راهنمای-راه‌اندازی-لوکال)\n\n---"
    },
    {
      "level": 2,
      "heading": "۱. هدف سرویس",
      "content": "**Service Objective**\n\nسرویس `auth-service` به عنوان واسط اختصاصی و مدیریت‌کننده نشست کاربری (Session Management) در پلتفرم NONS عمل می‌کند. این سرویس جریان یکپارچه ورود و ثبت‌نام کاربر را بر پایه **Ory Kratos** هدایت کرده، صفحات رابط کاربری (UI) مربوطه را به صورت محلی رندر و سرو می‌کند و به عنوان هماهنگ‌کننده نشست‌ها (Session Validator) برای درگاه **Traefik API Gateway** با استفاده از متد **ForwardAuth** ایفای نقش می‌نماید.\n\n---"
    },
    {
      "level": 2,
      "heading": "۲. مسئولیت‌ها",
      "content": "**Responsibilities**\n\n- ارائه و رندر صفحات رابط کاربری (UI) شامل فرم ایمیل، فرم ورود کد (OTP)، داشبورد و صفحه خطاها با استفاده از قالب‌های محلی Go (`templates/` و `static/`).\n- پیاده‌سازی و مدیریت فلو یکپارچه ثبت‌نام و ورود (Unified Auth Entry Flow) جهت شناسایی خودکار کاربران جدید و موجود.\n- ارتباط با APIهای عمومی و ادمین Ory Kratos به منظور احراز هویت نشست کاربری و به‌روزرسانی مشخصات هویت (traits).\n- ارائه نقطه پایانی `/v1/auth/validate` جهت اعتبارسنجی نشست‌های کاربری برای درگاه Traefik Gateway با استفاده از مکانیزم ForwardAuth.\n- پیاده‌سازی محدودکننده درخواست (Rate Limiter) بر روی نقطه ورود احراز هویت جهت مقابله با حملات Brute Force.\n- مدیریت و به‌روزرسانی فیلد `onboarded` در مشخصات کاربر (Traits) از طریق Kratos Admin API پس از اولین ورود موفق.\n- دریافت وب‌هوک‌های پس از ثبت‌نام از Ory Kratos در مسیر `/v1/auth/webhooks/kratos/register`.\n\n---"
    },
    {
      "level": 2,
      "heading": "۳. خارج از مسئولیت‌ها",
      "content": "**Non-Responsibilities**\n\n- **ذخیره‌سازی مستقیم اطلاعات هویتی:** هیچ پایگاه داده مستقلی برای ذخیره‌سازی اطلاعات هویت کاربران در این سرویس وجود ندارد و تمام داده‌ها منحصراً در لایه دیتابیس Ory Kratos ذخیره می‌شوند.\n- **ارسال مستقیم ایمیل‌های حاوی کد یکبار مصرف (OTP):** ارسال ایمیل کدهای OTP مستقیماً توسط ماژول Courier در Ory Kratos و با استفاده از سرور SMTP (مانند Mailhog در محیط لوکال) انجام می‌شود.\n- **مدیریت توکن‌های OAuth2/OIDC و Ory Hydra:** صدور، ابطال و اعتبارسنجی توکن‌های API بر عهده سرویس مستقل **`token-service`** (مبتنی بر Ory Hydra) است. این سرویس صرفاً نشست‌محور (Session-Cookie Based) را مدیریت کرده و توکن صادر نمی‌کند؛ تبدیل نشست Kratos به توکن از طریق `login-consent-app` بین Kratos و Hydra انجام می‌شود.\n- **مدیریت نقش‌ها و دسترسی‌ها (Authorization):** تعیین و بررسی مجوزها و نقش‌های کاربران خارج از این سرویس بوده و بر عهده سرویس IAM است.\n\n---"
    },
    {
      "level": 2,
      "heading": "۴. معماری ران‌تایم و دیاگرام‌ها",
      "content": "**Runtime Architecture & Diagrams**\n\nسرویس احراز هویت با ساختار زیر با API Gateway و موتور Kratos ارتباط برقرار می‌کند:\n\n```mermaid\ngraph TD\n    Client[مرورگر کاربر / User Browser] -->|1. Request /v1/auth/...| Gateway[Traefik Gateway]\n    Gateway -->|2. Route to /v1/auth| AuthService[Go Auth Service]\n    AuthService -->|3. REST API / session whoami| Kratos[Ory Kratos]\n    Kratos -->|4. Read/Write| KratosDB[(PostgreSQL)]\n\n    Client -->|5. Request /v1/protected| Gateway\n    Gateway -->|6. ForwardAuth /v1/auth/validate| AuthService\n    AuthService -->|7. Check session| Kratos\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۵. جریان‌های احراز هویت",
      "content": "**Authentication Flows**"
    },
    {
      "level": 3,
      "heading": "۵.۱. جریان ورود و ثبت‌نام یکپارچه (Unified Auth Flow)",
      "content": "پلتفرم NONS فاقد صفحات ورود و ثبت‌نام مجزا در رابط کاربری است. کاربر در ابتدا تنها آدرس ایمیل خود را وارد می‌کند و سیستم به صورت پویا مسیر مناسب را پیش می‌گیرد:\n\n```mermaid\nsequenceDiagram\n    autonumber\n    actor User as User / Browser\n    participant Auth as Go Auth Service\n    participant Kratos as Ory Kratos\n    participant Mail as Mailhog (SMTP)\n\n    User->>Auth: ورود ایمیل / Submit Email (/v1/auth/entry)\n    Auth->>Kratos: شروع فلو لاگین / Initialize Login Flow\n    Auth->>Kratos: ارسال ایمیل به Kratos Login\n    alt کاربر وجود دارد (User Exists)\n        Kratos-->>Auth: انتقال به مرحله ۲ (ارسال کد OTP)\n        Kratos->>Mail: ارسال ایمیل حاوی کد یکبار مصرف\n        Auth-->>User: ریدایرکت به صفحه ورود کد /v1/auth/login?flow=...\n    else کاربر وجود ندارد (User does not exist)\n        Kratos-->>Auth: عدم تغییر وضعیت (خطای ورود)\n        Auth->>Kratos: شروع فلو ثبت‌نام / Initialize Reg Flow\n        Auth->>Kratos: ارسال ایمیل به Kratos Reg\n        Kratos->>Mail: ارسال ایمیل حاوی کد یکبار مصرف\n        Auth-->>User: ریدایرکت به صفحه ورود کد /v1/auth/register?flow=...\n    end\n    User->>Auth: ارسال کد تایید / Submit Code\n    Auth->>Kratos: ارسال کد به Kratos\n    Kratos-->>Auth: تایید سشن و ارسال کوکی\n    Auth-->>User: ریدایرکت به داشبورد /v1/auth/dashboard\n    \n    Note over Auth, Kratos: در اولین ورود، onboarded تغییر می‌کند\n    Auth->>Kratos: به‌روزرسانی هویت به onboarded=true (Admin API)\n```\n\n---"
    },
    {
      "level": 2,
      "heading": "۶. تنظیمات Kratos",
      "content": "**Kratos Configuration**\n\nتنظیمات Kratos در فایل کانفیگ کلاستر [kratos-config.yaml](file:///C:/Users/ASUS/Documents/GitHub/nons/nons-api/services/auth-service/kratos-config.yaml) تعریف شده و شامل بخش‌های زیر است:"
    },
    {
      "level": 3,
      "heading": "۶.۱. ساختار هویت کاربر (Identity Schema)",
      "content": "مشخصات کاربر در فیلد `traits` به صورت زیر ساختاردهی شده است:\n- `email`: آدرس ایمیل کاربر (شناسه اصلی و یکتا جهت احراز هویت با متد `code`).\n- `onboarded`: وضعیت اونبوردینگ کاربر (نوع بولین، مقدار پیش‌فرض `false`).\n\n```json\n{\n  \"$id\": \"https://schemas.ory.sh/presets/kratos/identity.email.schema.json\",\n  \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n  \"title\": \"Person\",\n  \"type\": \"object\",\n  \"properties\": {\n    \"traits\": {\n      \"type\": \"object\",\n      \"properties\": {\n        \"email\": {\n          \"type\": \"string\",\n          \"format\": \"email\",\n          \"ory.sh/kratos\": {\n            \"credentials\": {\n              \"code\": {\n                \"identifier\": true,\n                \"via\": \"email\"\n              }\n            }\n          }\n        },\n        \"onboarded\": {\n          \"type\": \"boolean\",\n          \"default\": false\n        }\n      },\n      \"required\": [\"email\"]\n    }\n  }\n}\n```"
    },
    {
      "level": 3,
      "heading": "۶.۲. روش‌های احراز هویت فعال (Authentication Methods)",
      "content": "- **Passwordless Code (`code`):** با طول عمر ۱۰ دقیقه جهت ارسال کدهای یک‌بار مصرف ایمیلی فعال است.\n- **OIDC (`oidc`):** ورود از طریق حساب کاربری گوگل فعال است و نگاشت اطلاعات هویت با استفاده از فایل Jsonnet به آدرس `file:///etc/config/kratos/oidc.google.jsonnet` انجام می‌پذیرد.\n- سایر روش‌ها (شامل `password` و `totp`) غیرفعال هستند."
    },
    {
      "level": 3,
      "heading": "۶.۳. وب‌هوک ثبت‌نام (Registration Webhook Hook)",
      "content": "در تنظیمات فلو ثبت‌نام، پس از تأیید نهایی کد تایید، وب‌هوکی به آدرس زیر با هدر امنیتی صادر می‌شود:\n- **URL:** `http://auth-service:3001/v1/auth/webhooks/kratos/register`\n- **Body:** حاوی مشخصات کاربر `userId` و `traits` (به صورت فرمت‌دهی شده با Jsonnet).\n\n---"
    },
    {
      "level": 2,
      "heading": "۷. قراردادهای API",
      "content": "**API Contracts**\n\nتمامی مسیرهای ارائه‌شده توسط سرویس `auth-service` با پیش‌وند `/v1/auth` در دسترس هستند (تعریف شده در [main.go](file:///C:/Users/ASUS/Documents/GitHub/nons/nons-api/services/auth-service/main.go#L1171-L1181))."
    },
    {
      "level": 3,
      "heading": "`POST /v1/auth/entry`",
      "content": "- **توضیح:** نقطه ورود جریان احراز هویت یکپارچه. آدرس ایمیل کاربر را دریافت کرده و متناسب با وجود یا عدم وجود آن، فلو لاگین یا ثبت‌نام را در Kratos فعال می‌سازد.\n- **فرمت داده ورودی:** `application/x-www-form-urlencoded`\n- **پارامترهای بدنه:**\n  - `email` (اجباری): آدرس ایمیل کاربر.\n- **پاسخ:**\n  - `302 Found`: ریدایرکت به مسیر `/v1/auth/login?flow=<flow_id>` (برای کاربر موجود) یا `/v1/auth/register?flow=<flow_id>` (برای کاربر جدید)."
    },
    {
      "level": 3,
      "heading": "`GET /v1/auth/login`",
      "content": "- **توضیح:** نمایش فرم ورود کد OTP یا دکمه ورود با گوگل.\n- **پارامترهای Query:**\n  - `flow` (اجباری): شناسه جریان ورود صادر شده از Kratos."
    },
    {
      "level": 3,
      "heading": "`POST /v1/auth/login`",
      "content": "- **توضیح:** ارسال کد OTP وارد شده توسط کاربر برای تایید در فلو لاگین Kratos.\n- **پارامترهای بدنه:**\n  - `code` (اجباری): کد تایید ۶ رقمی دریافتی از ایمیل.\n  - `csrf_token` (اجباری): توکن ضد جعل صادر شده برای نشست جاری."
    },
    {
      "level": 3,
      "heading": "`GET /v1/auth/register`",
      "content": "- **توضیح:** نمایش فرم ثبت‌نام و تایید کد OTP برای کاربران جدید.\n- **پارامترهای Query:**\n  - `flow` (اجباری): شناسه جریان ثبت‌نام صادر شده از Kratos."
    },
    {
      "level": 3,
      "heading": "`POST /v1/auth/register`",
      "content": "- **توضیح:** ارسال کد OTP وارد شده توسط کاربر برای تایید در فلو ثبت‌نام Kratos."
    },
    {
      "level": 3,
      "heading": "`GET /v1/auth/validate`",
      "content": "- **توضیح:** نقطه پایانی ForwardAuth برای Traefik. نشست کاربر را با Kratos بررسی می‌کند.\n- **پاسخ‌ها:**\n  - `200 OK`: در صورت معتبر بودن نشست. هدرهای پاسخ شامل موارد زیر است:\n    - `X-User-Id`: شناسه یکتای کاربر در Kratos (UUID v4).\n    - `X-Subject`: آدرس ایمیل کاربر.\n  - `401 Unauthorized`: در صورت نامعتبر بودن یا انقضای نشست."
    },
    {
      "level": 3,
      "heading": "`GET /v1/auth/dashboard`",
      "content": "- **توضیح:** نمایش اطلاعات پروفایل کاربر پس از ورود موفق. در صورت غیرفعال بودن پرچم `onboarded` در هویت کاربر، این پرچم از طریق Kratos Admin API به صورت ناهمگام به `true` تغییر می‌یابد."
    },
    {
      "level": 3,
      "heading": "`GET /v1/auth/logout`",
      "content": "- **توضیح:** ابطال نشست Kratos و خروج کامل کاربر.\n- **پارامترهای Query:**\n  - `token` (اجباری): توکن خروج صادر شده توسط Kratos."
    },
    {
      "level": 3,
      "heading": "`GET /v1/auth/settings`",
      "content": "- **توضیح:** نمایش صفحه تنظیمات حساب کاربری (مانند تغییر مشخصات traits). در صورت عدم وجود پارامتر `flow` در درخواست، کاربر را برای راه‌اندازی فلو تنظیمات مرورگر به Kratos ریدایرکت می‌کند.\n- **پارامترهای Query:**\n  - `flow` (اختیاری): شناسه جریان تنظیمات Kratos."
    },
    {
      "level": 3,
      "heading": "`POST /v1/auth/settings`",
      "content": "- **توضیح:** ثبت فرم اطلاعات حساب و مشخصات جدید کاربر در Kratos.\n- **پارامترهای بدنه:**\n  - `csrf_token` (اجباری): توکن ضد جعل صادر شده برای نشست جاری.\n  - سایر فیلدهای traits (مانند `traits.name`)."
    },
    {
      "level": 3,
      "heading": "`GET /v1/auth/verification`",
      "content": "- **توضیح:** نمایش صفحه تاییدیه و احراز هویت ایمیل کاربر. در صورت عدم وجود پارامتر `flow` در درخواست، کاربر را برای راه‌اندازی فلو تایید مرورگر به Kratos ریدایرکت می‌کند.\n- **پارامترهای Query:**\n  - `flow` (اختیاری): شناسه جریان تایید Kratos."
    },
    {
      "level": 3,
      "heading": "`POST /v1/auth/verification`",
      "content": "- **توضیح:** ارسال ایمیل مجدد یا تایید کد تایید در فلو وریفیکیشن Kratos.\n- **پارامترهای بدنه:**\n  - `email` (اجباری): آدرس ایمیل کاربر.\n  - `csrf_token` (اجباری): توکن ضد جعل صادر شده برای نشست جاری."
    },
    {
      "level": 3,
      "heading": "`GET /v1/auth/error`",
      "content": "- **توضیح:** صفحه رندر خطاهای هویتی صادر شده توسط Kratos.\n- **پارامترهای Query:**\n  - `id` (اجباری): شناسه خطای ثبت شده در Kratos."
    },
    {
      "level": 3,
      "heading": "`POST /v1/auth/webhooks/kratos/register`",
      "content": "- **توضیح:** وب‌هوک ثبت‌نام پس از ثبت هویت موفق جدید در Kratos.\n- **فرمت داده ورودی:** `application/json`\n- **پارامترهای بدنه:**\n  - `userId` (اجباری): شناسه کاربر جدید.\n  - `traits` (اجباری): مشخصات کاربر جدید شامل ایمیل و نام.\n\n---"
    },
    {
      "level": 2,
      "heading": "۷.۵. رویدادهای صادر شده (Published Events)",
      "content": "سرویس `auth-service` پس از انجام موفقیت‌آمیز کنش‌های احراز هویت، رویدادهای زیر را روی NATS منتشر می‌کند:\n\n- **ثبت‌نام موفق کاربر (`nons.auth.user.registered`):**\n  - **زمان صدور:** پس از دریافت و پردازش وب‌هوک ثبت‌نام Kratos.\n  - **Payload:**\n    ```json\n    {\n      \"id\": \"string (UUID)\",\n      \"email\": \"string\",\n      \"name\": \"string\",\n      \"method\": \"string\",\n      \"registeredAt\": \"string (ISO 8601)\"\n    }\n    ```\n\n- **ورود موفق کاربر (`nons.auth.user.logged_in`):**\n  - **زمان صدور:** پس از تایید نهایی کد OTP در ورود کلاینت.\n  - **Payload:**\n    ```json\n    {\n      \"id\": \"string (UUID)\",\n      \"email\": \"string\",\n      \"method\": \"string\",\n      \"loggedInAt\": \"string (ISO 8601)\"\n    }\n    ```\n\n- **خروج موفق کاربر (`nons.auth.user.logged_out`):**\n  - **زمان صدور:** پس از ابطال موفق سشن در Kratos.\n  - **Payload:**\n    ```json\n    {\n      \"id\": \"string (UUID)\",\n      \"loggedOutAt\": \"string (ISO 8601)\"\n    }\n    ```\n\n---"
    },
    {
      "level": 2,
      "heading": "۸. راهنمای راه‌اندازی لوکال",
      "content": "**Local Setup Guide**"
    },
    {
      "level": 3,
      "heading": "پیش‌نیازها",
      "content": "- نصب Go نسخه ۱.۲۶ یا بالاتر.\n- کلاستر کوبرنتیز محلی فعال (مانند k3d) به همراه Traefik و Kratos مستقر شده."
    },
    {
      "level": 3,
      "heading": "گام‌های اجرا",
      "content": "۱. انتقال به دایرکتوری سرویس احراز هویت:\n```bash\ncd nons-api/services/auth-service\n```\n\n۲. تنظیم متغیرهای محیطی مورد نیاز:\n```bash"
    },
    {
      "level": 1,
      "heading": "آدرس دسترسی عمومی به Kratos",
      "content": "$env:KRATOS_PUBLIC=\"http://kratos:4433\""
    },
    {
      "level": 1,
      "heading": "آدرس دسترسی ادمین به Kratos",
      "content": "$env:KRATOS_ADMIN=\"http://kratos:4434\""
    },
    {
      "level": 1,
      "heading": "پورت اجرای وب‌سرویس",
      "content": "$env:PORT=\"3001\"\n```\n\n۳. اجرای محلی سرویس:\n```bash\ngo run main.go\n```\n\n۴. استقرار داکر ایمیج و اعمال تغییرات در کلاستر k3d محلی:\n```powershell\npowershell -File redeploy.ps1\n```\n\n۵. اعمال تغییرات کلیدها و متغیرها در کلاستر:\n```powershell\npowershell -File update-secrets.ps1\n```\n\n۶. فوروارد کردن پورت Mailhog جهت دریافت کدهای تایید در محیط محلی:\n```bash\nkubectl port-forward -n nons-platform svc/mailhog-ui 8025:8025\n```\nسپس می‌توانید مرورگر خود را روی `http://localhost:8025` باز کرده و کدهای ارسالی را دریافت نمایید."
    }
  ]
}