پرش به مطلب اصلی

ورود با Telegram

XLADA می‌تواند مدیر را با حساب Telegram به پنل راه بدهد. در این حالت رمز عبوری برای ورود لازم نیست: پنل شما را به صفحه Telegram می‌فرستد و پس از تأیید، توکن JWT معمولی صادر می‌کند. این برای کار روزمره راحت است و از حدس‌زدن رمز عبور جلوگیری می‌کند.

ورود با Telegram فقط ورود مدیر پنل است. به کاربران اشتراک‌ها ربطی ندارد و جدا از بات اعلان‌ها تنظیم می‌شود.

چه چیزی لازم است​

تنظیم در پنل، در بخش Settings → Authentication → Telegram OAuth2 قرار دارد. به چهار مقدار نیاز خواهید داشت:

فیلدچیست
فعالکلید provider
Client IDشناسه اپلیکیشن Telegram
Client Secretراز اپلیکیشن Telegram
Frontend Domainدامنه پنل بدون https://، برای مثال panel.example.com
Allowed IDsفهرست شناسه‌های عددی Telegram مدیران

Client ID و Client Secret را Telegram برای بات شما صادر می‌کند — این‌ها داده‌های جداگانه‌ای هستند، نه توکن TELEGRAM_BOT_TOKEN. دامنه پنل باید FQDN واقعی باشد: پنل آدرس بازگشت را از آن می‌سازد و باید با آنچه برای بات ثبت شده یکسان باشد.

آدرس بازگشتی که باید برای بات مجاز شود:

https://panel.example.com/api/auth/oauth2/callback/telegram
نکته

آدرس بازگشت را کامل کپی کنید، همراه با /api/auth/oauth2/callback/telegram. اگر فقط دامنه را بنویسید، Telegram نمی‌تواند شما را به پنل برگرداند.

در Allowed IDs شناسه‌های عددی مدیران را بیفزایید. فهرست الزامی است: تا وقتی خالی باشد، نمی‌توان provider را فعال کرد و ورود برای هیچ‌کس انجام نمی‌شود. ID یک عدد است، نه نام کاربری.

هشدار

اگر دست‌کم یکی از فیلدها پر نشده باشد — Client ID، Client Secret یا Frontend Domain — پنل Telegram OAuth2 را فعال نمی‌کند. تنظیمات را ذخیره کنید و بی‌درنگ ورود را بررسی کنید تا بدون دسترسی نمانید.

ورود چگونه انجام می‌شود​

  1. روی ورود با Telegram کلیک می‌کنید و پنل صفحه احراز هویت Telegram را باز می‌کند.
  2. پنل state و بررسی PKCE را می‌فرستد (code_verifier، روش S256)؛ درخواست از حوزه‌های دسترسی openid، profile و telegram:bot_access استفاده می‌کند.
  3. Telegram کد را به آدرس بازگشت برمی‌گرداند — همان /api/auth/oauth2/callback/telegram.
  4. پنل state و provider را تطبیق می‌دهد، کد را با توکن مبادله می‌کند و از توکن ID شناسه عددی کاربر را می‌خواند.
  5. اگر ID در Allowed IDs باشد، پنل توکن سوپرادمین صادر می‌کند و ورود موفق را در ژورنال ثبت می‌کند.
توجه

پس از تأیید، نخستین مدیر (سوپرادمین) وارد پنل می‌شود. دیگر مدیران از طریق Telegram وارد نمی‌شوند — این عمدی است.

محدودیت‌ها​

  • provider فقط روی HTTPS کار می‌کند: پنل بدون پروکسی معکوس با TLS هم بالا نمی‌آید.
  • Frontend Domain بدون scheme و بدون مسیر تعیین می‌شود. برای دیباگ محلی localhost و 127.0.0.1 مجازند.
  • Allowed IDs تنها فیلتر دسترسی است. اگر فهرست خالی باشد یا ID اضافی در آن باشد، ممکن است شخص نادرست وارد شود.
  • provider را می‌توان همراه با رمز عبور و دیگر روش‌های ورود فعال کرد — با هم تعارض ندارند.

امنیت​

پنل ورود را با چند سازوکار محافظت می‌کند:

  • state در Valkey نگه‌داری می‌شود و مدت محدودی زنده است — بدون آن نمی‌توان پاسخ Telegram را جعل کرد؛
  • از PKCE استفاده می‌شود، بنابراین کد رهگیری‌شده به توکن تبدیل نمی‌شود؛
  • دسترسی را فهرست ID تعیین می‌کند، نه آدرس ایمیل یا نام؛
  • تلاش‌های ناموفق ورود با رویداد service.login_attempt_failed ثبت می‌شوند و به Telegram و Webhookها می‌رسند؛
  • رمز عبور در چنین اعلان‌هایی گنجانده نمی‌شود.
خطر

Client Secret یک راز تمام‌عیار است. در تنظیمات پنل نگه‌داری می‌شود و به‌صورت آشکار به بیرون داده نمی‌شود. آن را منتشر نکنید، در پیام‌رسان‌ها نفرستید و در مخزن نگه ندارید. در صورت افشا، راز را در Telegram و در تنظیمات عوض کنید.

اگر ورود با رمز عبور را غیرفعال کرده و دسترسی به Telegram را از دست داده‌اید، CLI اضطراری کمک می‌کند: می‌تواند ورود با رمز عبور را دوباره فعال کند.

گام‌های بعدی​