۰۱ورود با تلگرام در نسخهی جدید چه فرقی کرده است؟
طبق مستندات رسمی تلگرام، ورود با تلگرام حالا بر پایهی کتابخانهی Telegram Login و جریان استاندارد OpenID Connect است و مستندات ویجت iframe قدیمی به صفحهی جداگانهای بایگانی شده است. پیادهسازی تلگرام از Authorization Code Flow با پشتیبانی PKCE پیروی میکند؛ پس هر کتابخانه یا سرویس سازگار با OIDC (مستندات، Keycloak و Authentik و Auth0 را مثال زده است) میتواند به آن وصل شود.
تلگرام چند مزیت را برای سایتها برشمرده است: ورود با چند لمس، امکان دریافت شمارهی تلفن تأییدشده با رضایت کاربر (بدون هزینهی کد پیامکی)، و یک کانال ارتباط مستقیم با کاربر داخل تلگرام که از اعلان پوش هم پشتیبانی میکند. برای اپهای موبایل هم SDK بومی iOS و Android منتشر شده است.
۰۲چطور ربات و آدرسهای مجاز را در BotFather تنظیم کنیم؟
- یک ربات بساز یا انتخاب کن که نمایندهی سایتت باشد. تلگرام توصیه میکند عکس پروفایل ربات همان لوگوی سایت و نامش همخوان با برند باشد، چون کاربر در پنجرهی تأیید همین را میبیند.
- مینیاپ @BotFather را باز کن، ربات را انتخاب کن و به بخش Login Widget برو.
- Allowed URLs را اضافه کن: هم origin صفحهای که دکمه در آن است (مثل
https://example.com) و هم آدرس بازگشت جریان OIDC (مثلhttps://example.com/auth/callback). تلگرام فقط به آدرسهای ثبتشده ورود را پردازش یا کاربر را برمیگرداند. - در همین بخش Client ID و Client Secret نمایش داده میشوند. Secret را فقط روی سرور نگه دار.
۰۳کتابخانهی telegram-login.js چطور کار میکند؟
سادهترین راه، کتابخانهی جاوااسکریپت https://oauth.telegram.org/js/telegram-login.js است. سه متد دارد:
Telegram.Login.init(options, callback): راهاندازی و ثبت تابع بازگشتTelegram.Login.open([callback]): باز کردن پنجرهی ورود با همان تنظیماتTelegram.Login.auth(options, callback): باز کردن پنجره با تنظیمات صریح
در 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 اصلی اینها هستند:
- Authorization:
https://oauth.telegram.org/auth - Token:
https://oauth.telegram.org/token - JWKS:
https://oauth.telegram.org/.well-known/jwks.json
- کاربر را با
client_id،redirect_uri،response_type=code،scope(کهopenidدر آن الزامی است)، یکstateتصادفی وcode_challengeبا روش S256 به آدرس auth بفرست. - بعد از تأیید، کاربر با پارامتر
codeبه redirect_uri برمیگردد. state را با نسخهی ذخیرهشده مقایسه کن. - سرورت با 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 و hash | id_token (JWT) با claimهای استاندارد و تلگرامی |
| روش بررسی | HMAC-SHA-256 روی data-check-string با SHA256 توکن ربات بهعنوان کلید | امضای نامتقارن (پیشفرض RS256) با کلیدهای عمومی JWKS |
| راز لازم روی سرور | توکن خود ربات | Client Secret (فقط برای تبادل کد)؛ برای بررسی امضا کلید عمومی کافی است |
| شمارهی تلفن | ندارد | scope phone با رضایت کاربر |
| سازگاری | اختصاصی تلگرام | هر کتابخانهی OIDC |
در ویجت قدیمی، برای جلوگیری از دادهی کهنه باید auth_date را هم چک میکردی. مهمترین تفاوت امنیتی این است که در روش قدیمی، بررسی امضا به توکن کامل ربات وابسته بود؛ در OIDC بررسی امضا با کلید عمومی انجام میشود.
۰۷چکلیست پیادهسازی امن ورود با تلگرام چیست؟
- id_token را فقط روی سرور بررسی کن: امضا،
iss،aud،expو nonce. - در جریان دستی،
stateتصادفی و PKCE با S256 را حذف نکن. - Client Secret و توکن ربات را هرگز در کد سمت مرورگر نگذار.
- Allowed URLs را دقیق و فقط با HTTPS ثبت کن و آدرسهای آزمایشی قدیمی را پاک کن.
- هدر COOP را روی
same-origin-allow-popupsبگذار، نهsame-origin. - scope را حداقلی بخواه؛ phone را فقط وقتی واقعاً شماره لازم داری.
- کاربر را با شناسهی عددی ثابت (
idیاsub) بشناس، نه با یوزرنیم که قابل تغییر است. - اگر هنوز ویجت قدیمی داری، hash را با مقایسهی زمانثابت چک کن،
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 کار میکنند.