نحوه ارتباط gold-bank با سامانه هویت متمرکز (IAM)

ورود مشترک بدون پرش مرورگر به /auth/bootstrap کامل نمی‌شود. اگر این متن جایی گفته مرورگر هرگز به IAM نمی‌رود، آن جمله کهنه است. قاعدهٔ فعلی برای هر اپ: iam/docs/onboarding-new-system.md.

این سند مسیر داده را توضیح می‌دهد: چه کسی، چه زمانی، چه چیزی را به کجا می‌فرستد و اگر آن طرف جواب نداد چه اتفاقی می‌افتد.

برای پیکربندی و فعال‌سازی: iam-sso.md · مرجع تصویری اندپوینت‌های IAM: http://<آدرس IAM>/docs

۱. خلاصه در یک تصویر

 پنل ادمین (Vue)            apps/api (NestJS)                     Central IAM
 ───────────────            ─────────────────                     ───────────
  فرم ورودِ همیشگی
  (موبایل + رمز)
       │  POST /api/admin/auth/login
       ├──────────────────────────────▶
       │                      AuthService.verifyPassword
       │                              │  POST /api/v1/auth/login
       │                              │  + client_id/secret + client_ip
       │                              ├────────────────────────────────▶
       │                              │◀────────────────────────────────┤
       │                              │   SUCCESS (sub، sid) │ 401 │ خطا
       │                              │
       │                      AdminSession: ثبت jti + sid + sub
       │◀─────────────────────────────┤  همان پاسخ همیشگی (api_token, roles)

سه نکته که کل طراحی را توضیح می‌دهد:

مرورگر ادمین هرگز به IAM نمی‌رود. نه ریدایرکت، نه دکمه SSO، نه صفحه جدید.
قالب پاسخ ورود تغییر نکرده است (api_token, roles, …)، پس پنل تفاوتی نمی‌بیند.
نگاشت کاربر با mobile انجام می‌شود. هیچ ستونی به AdminUser اضافه نشده؛ شناسه‌های IAM روی جدول جدید AdminSession می‌نشینند.

اپ کاربر (bnk.montzar.ir) هم متصل است، ولی از مسیر دیگری: ورودش فقط با کد یکبارمصرف است و رمزی ندارد که به IAM فرستاده شود. کد را همین سامانه تولید، ارسال و بررسی می‌کند و سپس نتیجه را به IAM اعلام می‌کند (/api/v1/auth/login/delegated-otp) تا نشست مرکزی، لاگ امنیتی و خروج سراسری شامل آن ورود هم بشود. توکن اپ هم مثل توکن پنل jti می‌گیرد و در جدول AppSession ثبت می‌شود، پس قابل ابطال است.

۲. کانال‌های ارتباطی (همه چیزی که رد و بدل می‌شود)

#	جهت	مسیر	چه زمانی	چه چیزی می‌رود	اگر خطا بدهد
۱	ما → IAM	`POST /api/v1/auth/login`	هر ورود ادمین	موبایل، رمز، `client_id`، `client_secret`، `client_ip`	طبق `IAM_LOGIN_DELEGATION` (پیش‌فرض: `bcrypt` محلی)
۱.۵	ما → IAM	`POST /api/v1/auth/login/delegated-otp`	ورود اپ کاربر (`/auth/verify-otp`) — این ورود رمز ندارد	موبایل، اعتبارنامه کلاینت، `client_ip`، شماره ماسک‌شده	کاربر آنجا نیست یا سرویس down ⇒ ورود محلی ادامه؛ قفل/غیرفعال/2FA ⇒ ورود رد می‌شود
۲	ما → IAM	`GET /.well-known/jwks.json`	تأیید توکن خروج سراسری (کش ۲۴ ساعته، `kid` ناشناس ⇒ یک‌بار refetch)	—	اعلان خروج پذیرفته نمی‌شود (۲۰۰ + لاگ)
۳	IAM → ما	`POST /api/iam/backchannel-logout`	خروج سراسری یا ابطال نشست توسط ادمینِ IAM	`logout_token` امضاشده (RS256)	همیشه ۲۰۰؛ دلیل رد فقط در لاگ

فقط همین سه کانال. جریان مرورگری OAuth در این سامانه استفاده نمی‌شود، چون قرار است رابط کاربری ورود دست‌نخورده بماند.

۳. جریان ۱ — ورود ادمین

POST /api/admin/auth/login  { phone, password }
  │
  ├─ AdminUser با این موبایل هست و فعال است؟  (نه ⇒ ۴۰۱ مبهم، مثل قبل)
  │
  ├─ AuthService.verifyPassword
  │     ├─ IAM خاموش ⇒ یک bcrypt.compare  (دقیقاً رفتار قبلی، بدون هیچ درخواست شبکه)
  │     ├─ IAM تأیید کرد ⇒ { ok: true, identity: { sub, sessionId } }
  │     ├─ IAM رد کرد (کاربر آنجا نیست/رمز فرق دارد)
  │     │     ├─ fallback  ⇒ bcrypt محلی
  │     │     └─ exclusive ⇒ ۴۰۱
  │     ├─ حساب در IAM قفل است ⇒ **رد قطعی** (قفل IAM دور زده نمی‌شود)
  │     ├─ IAM در دسترس نیست / ۴۲۹
  │     │     ├─ fallback  ⇒ bcrypt محلی
  │     │     └─ exclusive ⇒ ۴۰۱ با پیام روشن
  │     └─ حساب دو مرحله‌ای است ⇒ پیام روشن (این فرم مرحله کد ندارد)
  │
  ├─ jti تازه (فقط وقتی ردیابی نشست روشن است)
  ├─ امضای همان JWT همیشگی  { sub, mobile, jti? }
  ├─ AdminSession: { jti, adminUserId, iamSessionId, iamSub, ip, userAgent }
  │
  └─ پاسخ: همان قالب قبلی

چرا client_ip حیاتی است: محدودیت نرخ IAM روی IP اعمال می‌شود. بدون IP کاربر نهایی، همه ورودها از IP همین سرور دیده می‌شوند و بعد از چند تلاش ناموفق، کل پنل ادمین ۴۲۹ می‌گیرد. اگر API پشت پراکسی است، trust proxy را تنظیم کنید وگرنه @Ip() همیشه IP پراکسی را می‌دهد و همان مشکل برمی‌گردد.

۴. جریان ۲ — اعتبارسنجی هر درخواست (نشست قابل ابطال)

هر درخواست با Bearer توکن
  │
  ├─ JwtStrategy: امضا و انقضا (مثل قبل)
  ├─ توکن از نوع اپ مشتری نباشد (typ)
  │
  ├─ AdminSessionService.isActive(jti)
  │     ├─ ردیابی خاموش ⇒ true، بدون هیچ کوئری  (هزینه دقیقاً مثل قبل)
  │     ├─ توکن بدون jti (صادرشده پیش از فعال‌سازی) ⇒ true تا انقضا
  │     ├─ ردیف AdminSession باطل شده یا وجود ندارد ⇒ ۴۰۱
  │     └─ سالم ⇒ ادامه
  │
  └─ AdminUser + مجوزها از دیتابیس (مثل قبل، تا تغییر دسترسی فوری اثر کند)

AUTH_SESSION_TRACKING: خالی = همراه IAM_ENABLED · true = روشن بدون IAM · false = خاموش (ابطال مرکزی دیگر به اینجا نمی‌رسد).

۵. جریان ۳ — خروج سراسری (تنها مسیر ورودی از IAM)

IAM: خروج کاربر یا «بستن همه نشست‌ها» توسط ادمین
  │  logout_token امضاشده با RS256 (application/x-www-form-urlencoded)
  ▼
POST /api/iam/backchannel-logout        ← بدون احراز هویت، عمداً
  │
  ├─ IamLogoutService.verify
  │     ├─ alg باید RS256 باشد (alg=none رد می‌شود)
  │     ├─ امضا با کلید عمومی JWKS
  │     ├─ iss برابر issuer پیکربندی‌شده
  │     ├─ aud شامل client_id ما
  │     ├─ events شامل رخداد back-channel logout (تا ID Token جای آن نرود)
  │     ├─ nonce نباید وجود داشته باشد
  │     └─ exp/iat با تحمل ۶۰ ثانیه انحراف ساعت
  │
  └─ AdminSessionService
        ├─ sid دارد ⇒ همان نشست باطل می‌شود
        └─ فقط sub دارد ⇒ همه نشست‌های آن هویت
            ⇒ درخواست بعدی با آن توکن ۴۰۱ می‌گیرد

پاسخ همیشه ۲۰۰ است (حتی برای توکن نامعتبر) تا IdP بی‌نهایت تلاش مجدد نکند؛ دلیل رد شدن در لاگ سرویس می‌آید.

آدرسی که باید در IAM برای این کلاینت ثبت شود:

backchannel_logout_uri = https://<آدرس این API>/api/iam/backchannel-logout

ابطال محلی هم به همین مسیر وصل است: غیرفعال کردن حساب یا تغییر رمز یک ادمین (AdminUsersService.update) نشست‌های او را می‌بندد.

۶. نگاشت هویت‌ها

در IAM	در gold-bank	قاعده
موبایل	`AdminUser.mobile`	تنها معیار نگاشت کاربر — هیچ ستون جدیدی روی این جدول نیست
`sub`	`AdminSession.iamSub`	برای خروج سراسریِ «همه نشست‌های این هویت»
`sid`	`AdminSession.iamSessionId`	برای ابطال دقیقاً همان نشست
نقش‌ها	`UserType` / `Permission` محلی	از IAM خوانده نمی‌شود؛ دسترسی‌ها مال همین سامانه است

چرا شناسه‌های IAM روی جدول جدید نشستند و نه روی AdminUser: تا فعال کردن این قابلیت هیچ تغییری در جدول‌های موجود لازم نداشته باشد و برگرداندنش هم به همان سادگی باشد. اگر روزی فیلد دیگری از IAM لازم شد، همین الگو ادامه یابد.

۷. رفتار در خطا (خلاصه تصمیم‌ها)

وضعیت	`fallback` (پیش‌فرض)	`exclusive`
IAM خاموش/ناقص	یک bcrypt، بدون شبکه — رفتار کاملاً قبلی	همان
IAM در دسترس نیست	bcrypt محلی؛ ورود ادمین‌ها قطع نمی‌شود	۴۰۱ «سرویس هویت در دسترس نیست»
کاربر در IAM نیست	bcrypt محلی (مناسب مهاجرت تدریجی)	۴۰۱
رمز در IAM غلط است	bcrypt محلی	۴۰۱
حساب در IAM قفل است	۴۰۱ — قفل IAM دور زده نمی‌شود	۴۰۱
حساب دو مرحله‌ای است	۴۰۱ با پیام روشن (این فرم مرحله کد ندارد)	همان
ثبت `AdminSession` ناموفق	ورود انجام می‌شود (فقط هشدار لاگ) — بدترین حالت: نشستی که زودتر قابل ابطال نیست	همان
توکن خروج نامعتبر	۲۰۰ + هشدار لاگ؛ هیچ نشستی بسته نمی‌شود	همان

۸. بررسی سریع اتصال

cd apps/api
npx jest src/modules/iam src/modules/auth src/modules/sessions   # ۶۱ تست
npx prisma migrate deploy                                        # جدول AdminSession

مشکلات پرتکرار:

نشانه	علت
بعد از چند ورود همه ۴۲۹ می‌گیرند	`client_ip` نمی‌رسد؛ `trust proxy` تنظیم نشده
خروج سراسری بی‌اثر است	`backchannel_logout_uri` ثبت نشده، یا `AUTH_SESSION_TRACKING=false`
همه ادمین‌ها ۴۰۱ می‌گیرند	جدول `AdminSession` پاک شده — ردیف نبود یعنی «باطل»
`unsupported logout token algorithm` در لاگ	توکن با RS256 امضا نشده (تلاش جعل یا پیکربندی اشتباه IdP)
حساب دو مرحله‌ای وارد نمی‌شود	این پنل مرحله «ورود کد» ندارد — بخش ۷ سند `iam-sso.md`

12 KiB Raw Blame History Unescape Escape