Telegram-authorization on the site: how it works – Login Widget, OIDC, bot-flow and Mini App

{
  "id": 123456789,
  "first_name": "Иван",
  "last_name": "Иванов",
  "username": "ivan_ivanov",
  "photo_url": "https://t.me/i/userpic/...",
  "auth_date": 1749300000,
  "hash": "abc123def456..."
}

<!-- Режим редиректа: данные придут на callback_url как GET-параметры -->
<script
  async
  src="https://telegram.org/js/telegram-widget.js?22"
  data-telegram-login="YourBotUsername"
  data-size="large"
  data-auth-url="https://your-site.ru/auth/telegram/callback"
  data-request-access="write">
</script>

<!-- Режим колбэка: данные придут в JavaScript-функцию -->
<script
  async
  src="https://telegram.org/js/telegram-widget.js?22"
  data-telegram-login="YourBotUsername"
  data-size="large"
  data-onauth="onTelegramAuth(user)"
  data-request-access="write">
</script>
<script>
function onTelegramAuth(user) {
  // НЕ доверяйте этим данным без проверки на бэкенде!
  fetch('/auth/telegram', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(user)
  });
}
</script>

const crypto = require('crypto');

function verifyTelegramAuth(data, botToken) {
  const { hash, ...rest } = data;

  // Формируем строку для проверки
  const dataCheckString = Object.keys(rest)
    .sort()
    .map(key => `${key}=${rest[key]}`)
    .join('\n');

  // Ключ для Login Widget: SHA256 от токена бота
  const secretKey = crypto
    .createHash('sha256')
    .update(botToken)
    .digest();

  // Вычисляем HMAC
  const computedHash = crypto
    .createHmac('sha256', secretKey)
    .update(dataCheckString)
    .digest('hex');

  // Проверяем подпись
  if (computedHash !== hash) {
    throw new Error('Недействительная подпись Telegram');
  }

  // Проверяем свежесть: не старше 24 часов
  const authDate = parseInt(rest.auth_date, 10);
  const now = Math.floor(Date.now() / 1000);
  if (now - authDate > 86400) {
    throw new Error('Данные авторизации устарели');
  }

  return true;
}

// Использование в Express
app.post('/auth/telegram', async (req, res) => {
  try {
    verifyTelegramAuth(req.body, process.env.BOT_TOKEN);

    // Подпись верна — ищем или создаём пользователя
    const user = await upsertUser({
      telegramId: req.body.id,
      firstName: req.body.first_name,
      lastName: req.body.last_name,
      username: req.body.username,
    });

    // Выдаём сессию или JWT
    req.session.userId = user.id;
    res.json({ ok: true });

  } catch (err) {
    res.status(401).json({ error: err.message });
  }
});

import hashlib
import hmac
import time

def verify_telegram_auth(data: dict, bot_token: str) -> bool:
    received_hash = data.get('hash')
    if not received_hash:
        raise ValueError('Отсутствует hash')

    # Строим строку для проверки
    data_check = {k: v for k, v in data.items() if k != 'hash'}
    data_check_string = '\n'.join(
        f'{k}={v}' for k, v in sorted(data_check.items())
    )

    # SHA256 от токена бота как ключ
    secret_key = hashlib.sha256(bot_token.encode()).digest()

    # HMAC-SHA256
    computed_hash = hmac.new(
        secret_key,
        data_check_string.encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(computed_hash, received_hash):
        raise ValueError('Недействительная подпись')

    # Проверка времени
    auth_date = int(data.get('auth_date', 0))
    if time.time() - auth_date > 86400:
        raise ValueError('Данные авторизации устарели')

    return True

User → Your website → oauth.telegram.org/auth?client id=
Telegram confirms identity
Redirect to your callback with code
Your backend exchanges code for tokens through POST /token
Get JWT with user data
Check the signature of JWT through JWKS

# Example configuration for Python-social-auth / authlib
TELEGRAM OIDC CONFIG =
'issuer': 'https://oauth.telegram.org','
'authorization endpoint': 'https://oauth.telegram.org/auth','
'token endpoint': 'https://oauth.telegram.org/token','
'jwks uri': 'https://oauth.telegram.org/.well-known/jwks.json','
}

#Scope: openid profile

// Выдача сессии после успешной авторизации (Express + express-session)
app.get('/auth/telegram/callback', async (req, res) => {
  const { code } = req.query;

  // Обмениваем code на токены
  const tokens = await exchangeCodeForTokens(code);

  // Проверяем JWT через JWKS
  const userInfo = await verifyJWT(tokens.id_token);

  // Создаём или обновляем пользователя
  const user = await upsertUser({
    telegramId: userInfo.sub,
    firstName: userInfo.given_name,
    username: userInfo.preferred_username,
  });

  // Сохраняем в сессии
  req.session.userId = user.id;
  req.session.save(() => {
    res.redirect('/dashboard');
  });
});

User on the site → clicks “Login via Telegram”
The site generates a one-time token (UUID), saves in Redis
Shows the "Open Bot" button with the link t.me/YourBot?start=<token >>
User opens bot, sends /start <token >>
The bot makes a request to the site API: “Token X belongs to the user telegram id Y”
The site links the token with telegram id, creates a session
Authorization page polls API every 2 seconds, sees session – redirect

const { v4: uuidv4 } = require('uuid');
const redis = require('./redis'); // ваш Redis-клиент

app.get('/auth/telegram/init', async (req, res) => {
  const token = uuidv4();
  
  // Сохраняем токен на 5 минут, пока пользователь не авторизовался
  await redis.setex(`tg_auth:${token}`, 300, JSON.stringify({ status: 'pending' }));

  res.json({
    token,
    botUrl: `https://t.me/${process.env.BOT_USERNAME}?start=${token}`,
  });
});

// Опрос статуса авторизации (фронтенд спрашивает каждые 2 сек)
app.get('/auth/telegram/status/:token', async (req, res) => {
  const data = await redis.get(`tg_auth:${req.params.token}`);
  if (!data) return res.json({ status: 'expired' });
  res.json(JSON.parse(data));
});

const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot(process.env.BOT_TOKEN, { polling: true });

bot.onText(/\/start (.+)/, async (msg, match) => {
  const token = match[1];
  const telegramId = msg.from.id;

  // Проверяем, что токен существует и ещё pending
  const data = await redis.get(`tg_auth:${token}`);
  if (!data || JSON.parse(data).status !== 'pending') {
    bot.sendMessage(telegramId, '❌ Ссылка недействительна или устарела.');
    return;
  }

  // Создаём или находим пользователя
  const user = await upsertUser({
    telegramId,
    firstName: msg.from.first_name,
    lastName: msg.from.last_name,
    username: msg.from.username,
  });

  // Привязываем токен к пользователю
  await redis.setex(
    `tg_auth:${token}`,
    60, // Ещё 60 секунд, чтобы сайт успел прочитать
    JSON.stringify({ status: 'authorized', userId: user.id })
  );

  bot.sendMessage(telegramId, '✅ Вы успешно вошли на сайт!');
});

async function initTelegramAuth() {
  // Получаем токен и ссылку на бота
  const { token, botUrl } = await fetch('/auth/telegram/init').then(r => r.json());

  // Показываем кнопку
  document.getElementById('tg-link').href = botUrl;
  document.getElementById('tg-link').style.display = 'block';

  // Опрашиваем статус каждые 2 секунды
  const interval = setInterval(async () => {
    const status = await fetch(`/auth/telegram/status/${token}`).then(r => r.json());

    if (status.status === 'authorized') {
      clearInterval(interval);
      // Финализируем сессию и редиректим
      await fetch('/auth/telegram/finalize', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ token }),
      });
      window.location.href = '/dashboard';
    }

    if (status.status === 'expired') {
      clearInterval(interval);
      alert('Ссылка устарела. Попробуйте снова.');
    }
  }, 2000);
}

const crypto = require('crypto');

function verifyInitData(initDataString, botToken) {
  const params = new URLSearchParams(initDataString);
  const hash = params.get('hash');
  params.delete('hash');

  // Сортируем параметры и формируем строку
  const dataCheckString = [...params.entries()]
    .sort(([a], [b]) => a.localeCompare(b))
    .map(([k, v]) => `${k}=${v}`)
    .join('\n');

  // Ключ: HMAC-SHA256("WebAppData", bot_token) — НЕ SHA256!
  const secretKey = crypto
    .createHmac('sha256', 'WebAppData')
    .update(botToken)
    .digest();

  const computedHash = crypto
    .createHmac('sha256', secretKey)
    .update(dataCheckString)
    .digest('hex');

  if (computedHash !== hash) {
    throw new Error('Недействительная подпись initData');
  }

  // Проверка времени: обычно допускают 1 час, не 24
  const authDate = parseInt(params.get('auth_date'), 10);
  if (Date.now() / 1000 - authDate > 3600) {
    throw new Error('initData устарела');
  }

  // Возвращаем данные пользователя
  return JSON.parse(params.get('user'));
}

// Фронтенд: отправляем initData на бэкенд при старте
const tg = window.Telegram.WebApp;
tg.ready();

async function authenticate() {
  const response = await fetch('/auth/miniapp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ initData: tg.initData }),
  });
  const { token } = await response.json();
  // Сохраняем JWT для последующих запросов
  localStorage.setItem('auth_token', token);
}

// Бэкенд
app.post('/auth/miniapp', async (req, res) => {
  const { initData } = req.body;

  try {
    const user = verifyInitData(initData, process.env.BOT_TOKEN);

    const dbUser = await upsertUser({ telegramId: user.id, ...user });

    // Выдаём JWT (короткий TTL — initData можно переиспользовать)
    const token = jwt.sign({ userId: dbUser.id }, process.env.JWT_SECRET, {
      expiresIn: '7d',
    });

    res.json({ token });
  } catch (err) {
    res.status(401).json({ error: err.message });
  }
});

Correct configuration of express-session
app.use(session)({)
secret: process.env.SESSION SECRET, // long random string
resave: false,
saveUninitialized: false,
cookie:
httpOnly: true, // JS does not have access to cookies
secure: true // HTTPS only
sameSite: 'lax', // CSRF protection
maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
}
store: redisStore // Stored in Redis, not in memory
);

LocalStorage Vulnerable to XSS
localStorage.setItem('token', jwt);

// Better for the web: httpOnly cookie
res.cookie('access token', jwt, {)
httpOnly: true,
secure: true,
sameSite: 'strict',
maxAge: 15 * 60 * 1000, // 15 minutes
};

// Правильное сравнение хешей (защита от timing attack)
const timingSafeEqual = (a, b) => {
  const bufA = Buffer.from(a, 'hex');
  const bufB = Buffer.from(b, 'hex');
  if (bufA.length !== bufB.length) return false;
  return crypto.timingSafeEqual(bufA, bufB);
};

- User table diagram
Create table users (
id SERIAL PRIMARY KEY,
telegram id BIGINT UNIQUE NOT NULL - the main key from Telegram
username VARCHAR(64) - may change
first name VARCHAR(128)
created at TIMESTAMPTZ DEFAULT NOW(),
- Your business fields.
plan Varchar(32) DEFAULT 'free',
email VARCHAR(255)
);

Implement authorization via Telegram Login Widget on Express.js.
Requirements:
Check HMAC-SHA256 with bot token from .env
Check auth date (not older than 24 hours)
- Comparison of hashes through crypto.timingSafeEqual
- After successful verification, session via express-session + Redis
Upsert of the user in PostgreSQL by telegram id
Endpoint GET /auth/telegram/callback for redirect widget mode
Endpoint POST /auth/telegram for JavaScript colback
Do not use any npm packets to verify Telegram – only built-in crypto.

Make authorization through Telegram

Preparation:
Created bot via @BotFather, received token
● In BotFather, the site domain (setdomain) is specified - for Login Widget
BOT TOKEN is stored in environment variables, not code
● The site works on HTTPS.

Backend:
HMAC signature verification (SHA256 for widget, HMAC for initData)
● Checked auth date (not older than 24h for widget, 1h for initData)
● Comparison of hashes using timingSafeEqual, not via ===
Implemented upsert by telegram id (not by username!)
Session or JWT is issued only after successful verification
Cookies: httpOnly, secure, sameSite

Sessions:
Sessions are stored in Redis or PostgreSQL, not in Node.js memory
Installed TTL for sessions
Exit implemented (session deletion/JWT disability)

Safety:
● No trust initDataUnsafe.user without HMAC verification
● All API endpoints require authentication
● Attempts of unsuccessful authorization are logged

Testing:
Verified authorization in real Telegram (not in the test client)
● Script with outdated data (auth date > 24h)
● Screenplay with the substitution of hash