استارد / وبلاگ
وبلاگ

ورود با تلگرام (Log In With Telegram) در ۲۰۲۶: راهنمای OIDC جدید برای سایت‌ها

دکمه‌ی «ورود با تلگرام» دیگر همان ویجت iframe قدیمی نیست. تلگرام ورود را روی استاندارد OpenID Connect برده و ویجت قبلی را بایگانی کرده است. این راهنما درباره‌ی ورود کاربران به سایت خودت است؛ اگر دنبال احراز هویت سرور به سرور هستی، احراز هویت در Stard API با کلید API کار می‌کند و موضوع جداگانه‌ای است.

پاسخ کوتاه

ورود با تلگرام حالا یک ارائه‌دهنده‌ی استاندارد OpenID Connect است: در BotFather، در بخش Login Widget ربات، آدرس‌های مجاز را ثبت می‌کنی و Client ID و Client Secret می‌گیری. کاربر با کتابخانه‌ی telegram-login.js یا جریان Authorization Code با PKCE از oauth.telegram.org وارد می‌شود و تو یک id_token امضاشده (پیش‌فرض RS256) می‌گیری که باید روی سرور با کلیدهای JWKS بررسی شود. ویجت قدیمی داده را با HMAC و توکن ربات امضا می‌کرد.

آخرین به‌روزرسانی:

۰۱ورود با تلگرام در نسخه‌ی جدید چه فرقی کرده است؟

طبق مستندات رسمی تلگرام، ورود با تلگرام حالا بر پایه‌ی کتابخانه‌ی Telegram Login و جریان استاندارد OpenID Connect است و مستندات ویجت iframe قدیمی به صفحه‌ی جداگانه‌ای بایگانی شده است. پیاده‌سازی تلگرام از Authorization Code Flow با پشتیبانی PKCE پیروی می‌کند؛ پس هر کتابخانه یا سرویس سازگار با OIDC (مستندات، Keycloak و Authentik و Auth0 را مثال زده است) می‌تواند به آن وصل شود.

تلگرام چند مزیت را برای سایت‌ها برشمرده است: ورود با چند لمس، امکان دریافت شماره‌ی تلفن تأییدشده با رضایت کاربر (بدون هزینه‌ی کد پیامکی)، و یک کانال ارتباط مستقیم با کاربر داخل تلگرام که از اعلان پوش هم پشتیبانی می‌کند. برای اپ‌های موبایل هم SDK بومی iOS و Android منتشر شده است.

۰۲چطور ربات و آدرس‌های مجاز را در BotFather تنظیم کنیم؟

  1. یک ربات بساز یا انتخاب کن که نماینده‌ی سایتت باشد. تلگرام توصیه می‌کند عکس پروفایل ربات همان لوگوی سایت و نامش هم‌خوان با برند باشد، چون کاربر در پنجره‌ی تأیید همین را می‌بیند.
  2. مینی‌اپ @BotFather را باز کن، ربات را انتخاب کن و به بخش Login Widget برو.
  3. Allowed URLs را اضافه کن: هم origin صفحه‌ای که دکمه در آن است (مثل https://example.com) و هم آدرس بازگشت جریان OIDC (مثل https://example.com/auth/callback). تلگرام فقط به آدرس‌های ثبت‌شده ورود را پردازش یا کاربر را برمی‌گرداند.
  4. در همین بخش Client ID و Client Secret نمایش داده می‌شوند. Secret را فقط روی سرور نگه دار.

۰۳کتابخانه‌ی telegram-login.js چطور کار می‌کند؟

ساده‌ترین راه، کتابخانه‌ی جاوااسکریپت https://oauth.telegram.org/js/telegram-login.js است. سه متد دارد:

در options، client_id الزامی است؛ scope (آرایه‌ای از profile، phone و write)، lang و nonce اختیاری‌اند. nonce یک رشته‌ی تصادفی است که سرور تو می‌سازد و داخل id_token برمی‌گردد تا جلوی حمله‌ی تکرار (replay) گرفته شود.

<script src="https://oauth.telegram.org/js/telegram-login.js"></script>
<script>
Telegram.Login.init(
  { client_id: 123456789, scope: ['profile'], nonce: SERVER_NONCE },
  function (data) {
    if (data.error) return;
    fetch('/auth/telegram', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ id_token: data.id_token }),
    });
  }
);
</script>

تابع بازگشت id_token، شیء user (نسخه‌ی رمزگشایی‌شده‌ی همان توکن) یا error می‌گیرد. شیء user را برای نمایش استفاده کن، ولی تصمیم ورود را فقط بعد از بررسی id_token روی سرور بگیر.

دام COOP: این کتابخانه با یک پنجره‌ی popup حرف می‌زند. اگر سایتت هدر Cross-Origin-Opener-Policy: same-origin می‌فرستد، این ارتباط قطع و ورود ناموفق می‌شود. طبق مستندات، یا این هدر را بردار یا از same-origin-allow-popups استفاده کن.

۰۴جریان OIDC بدون کتابخانه چه مراحلی دارد؟

سند discovery در https://oauth.telegram.org/.well-known/openid-configuration است و سه endpoint اصلی این‌ها هستند:

  1. کاربر را با client_id، redirect_uri، response_type=code، scope (که openid در آن الزامی است)، یک state تصادفی و code_challenge با روش S256 به آدرس auth بفرست.
  2. بعد از تأیید، کاربر با پارامتر code به redirect_uri برمی‌گردد. state را با نسخه‌ی ذخیره‌شده مقایسه کن.
  3. سرورت با POST به آدرس token و احراز هویت Basic (Client ID و Secret) کد را همراه code_verifier با access_token و id_token عوض می‌کند.

scopeها: openid شناسه‌ی یکتای کاربر (sub) را می‌دهد؛ profile فیلدهای id، name، preferred_username و picture را؛ phone شماره‌ی تأییدشده را با رضایت کاربر (phone_number)؛ و telegram:bot_access اجازه می‌دهد ربات تو بعد از ورود به کاربر پیام بدهد. تلگرام endpoint جداگانه‌ی UserInfo ندارد و همه‌ی اطلاعات داخل خود id_token است؛ اگر کتابخانه‌ات پیش‌فرض سراغ UserInfo می‌رود، آن را خاموش کن.

۰۵id_token را روی سرور چطور بررسی کنیم؟

id_token یک JWT امضاشده است و پیش‌فرض با RS256 امضا می‌شود. سه کار لازم است: کلید عمومی را از JWKS بگیر، امضا را بررسی کن، و claimها را چک کن: iss باید https://oauth.telegram.org باشد، aud با شناسه‌ی ربات تو یکی باشد و توکن منقضی نشده باشد (exp). اگر nonce فرستاده‌ای، آن را هم مقایسه کن. نمونه با PyJWT:

import jwt

jwks = jwt.PyJWKClient('https://oauth.telegram.org/.well-known/jwks.json')
key = jwks.get_signing_key_from_jwt(id_token).key
claims = jwt.decode(id_token, key, algorithms=['RS256'],
                    audience=str(CLIENT_ID), issuer='https://oauth.telegram.org')
if claims.get('nonce') != expected_nonce:
    raise ValueError('bad nonce')
user_id = claims['id']  # with the profile scope

در بخش Login Widget › Advanced در BotFather می‌شود الگوریتم را به ES256، EdDSA یا ES256K تغییر داد؛ ولی طبق مستندات، EdDSA و ES256K فقط با scope openid کار می‌کنند و profile و phone را رد می‌کنند.

۰۶ویجت جدید با ویجت قدیمی (HMAC) چه فرقی دارد؟

موضوعویجت قدیمیورود جدید (OIDC)
اتصال دامنهدستور /setdomain در BotFatherفهرست Allowed URLs در بخش Login Widget
داده‌ی برگشتیid، first_name، last_name، username، photo_url، auth_date و hashid_token (JWT) با claimهای استاندارد و تلگرامی
روش بررسیHMAC-SHA-256 روی data-check-string با SHA256 توکن ربات به‌عنوان کلیدامضای نامتقارن (پیش‌فرض RS256) با کلیدهای عمومی JWKS
راز لازم روی سرورتوکن خود رباتClient Secret (فقط برای تبادل کد)؛ برای بررسی امضا کلید عمومی کافی است
شماره‌ی تلفننداردscope phone با رضایت کاربر
سازگاریاختصاصی تلگرامهر کتابخانه‌ی OIDC

در ویجت قدیمی، برای جلوگیری از داده‌ی کهنه باید auth_date را هم چک می‌کردی. مهم‌ترین تفاوت امنیتی این است که در روش قدیمی، بررسی امضا به توکن کامل ربات وابسته بود؛ در OIDC بررسی امضا با کلید عمومی انجام می‌شود.

۰۷چک‌لیست پیاده‌سازی امن ورود با تلگرام چیست؟

برای نکته‌های امنیتی بیشتر در خرید و فروش داخل تلگرام، صفحه‌ی امنیت استارد و تغییرات Bot API در ۲۰۲۶ را هم ببین.

منابع رسمی: Telegram Login (OIDC) · Telegram Login Widget (legacy) · OIDC discovery

۰۸سوالات متداول

آیا ویجت قدیمی ورود با تلگرام هنوز کار می‌کند؟

مستندات آن به صفحه‌ی legacy بایگانی شده است. برای پروژه‌ی جدید از جریان OIDC و کتابخانه‌ی telegram-login.js استفاده کن و پروژه‌های قدیمی را برای مهاجرت برنامه‌ریزی کن.

Client ID و Client Secret را از کجا بگیرم؟

در مینی‌اپ BotFather، ربات را انتخاب کن و به بخش Login Widget برو؛ همان‌جا آدرس‌های مجاز را هم ثبت می‌کنی.

چرا پنجره‌ی ورود باز می‌شود ولی ورود کامل نمی‌شود؟

رایج‌ترین دلیل هدر Cross-Origin-Opener-Policy: same-origin است که ارتباط با popup را قطع می‌کند؛ آن را به same-origin-allow-popups تغییر بده و Allowed URLs را هم چک کن.

شماره‌ی تلفن کاربر را می‌شود گرفت؟

بله، با scope phone و فقط با رضایت کاربر؛ شماره‌ی تأییدشده در claim phone_number داخل id_token می‌آید.

id_token با چه الگوریتمی امضا می‌شود؟

پیش‌فرض RS256. در BotFather می‌شود ES256، EdDSA یا ES256K را انتخاب کرد، ولی دو گزینه‌ی آخر فقط با scope openid کار می‌کنند.

امن معامله کن

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

ورود به ربات استارد