Telegram-авторизация на сайте: как это работает — Login Widget, OIDC, бот-флоу и 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

Пользователь → ваш сайт → oauth.telegram.org/auth?client_id=...
  → Telegram подтверждает личность
  → Редирект на ваш callback с code
  → Ваш бэкенд обменивает code на токены через POST /token
  → Получаете JWT с данными пользователя
  → Проверяете подпись JWT через JWKS

# Пример конфигурации для 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');
  });
});

Пользователь на сайте → нажимает «Войти через Telegram»
  → Сайт генерирует одноразовый токен (UUID), сохраняет в Redis
  → Показывает кнопку «Открыть бота» со ссылкой t.me/YourBot?start=<token>
  → Пользователь открывает бота, отправляет /start <token>
  → Бот делает запрос к API сайта: «токен X принадлежит пользователю telegram_id Y»
  → Сайт связывает токен с telegram_id, создаёт сессию
  → Страница авторизации опрашивает API каждые 2 секунды, видит сессию — редиректит

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 });
  }
});

// Правильная конфигурация express-session
app.use(session({
  secret: process.env.SESSION_SECRET, // длинная случайная строка
  resave: false,
  saveUninitialized: false,
  cookie: {
    httpOnly: true,   // JS не имеет доступа к куке
    secure: true,     // Только HTTPS
    sameSite: 'lax',  // Защита от CSRF
    maxAge: 30 * 24 * 60 * 60 * 1000, // 30 дней
  },
  store: redisStore,  // Храним в Redis, не в памяти
}));

// Плохо: localStorage уязвим к XSS
localStorage.setItem('token', jwt);

// Лучше для веба: httpOnly cookie
res.cookie('access_token', jwt, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
  maxAge: 15 * 60 * 1000, // 15 минут
});

// Правильное сравнение хешей (защита от 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);
};

-- Схема таблицы пользователей
CREATE TABLE users (
  id          SERIAL PRIMARY KEY,
  telegram_id BIGINT UNIQUE NOT NULL,  -- главный ключ из Telegram
  username    VARCHAR(64),             -- может меняться
  first_name  VARCHAR(128),
  created_at  TIMESTAMPTZ DEFAULT NOW(),
  -- ваши бизнес-поля
  plan        VARCHAR(32) DEFAULT 'free',
  email       VARCHAR(255)
);

Реализуй авторизацию через Telegram Login Widget на Express.js.
Требования:
- Проверка HMAC-SHA256 с bot_token из .env
- Проверка auth_date (не старше 24ч)
- Сравнение хешей через crypto.timingSafeEqual
- После успешной проверки: сессия через express-session + Redis
- Upsert пользователя в PostgreSQL по telegram_id
- Эндпоинт GET /auth/telegram/callback для redirect-режима виджета
- Эндпоинт POST /auth/telegram для JavaScript-колбэка
Не используй любые npm-пакеты для проверки Telegram — только встроенный crypto.

Сделай авторизацию через Telegram

Подготовка:
☐ Создан бот через @BotFather, получен токен
☐ В BotFather указан домен сайта (setdomain) — для Login Widget
☐ BOT_TOKEN хранится в переменных среды, не в коде
☐ Сайт работает по HTTPS

Бэкенд:
☐ Реализована HMAC-проверка подписи (SHA256 для виджета, HMAC для initData)
☐ Проверяется auth_date (не старше 24ч для виджета, 1ч для initData)
☐ Сравнение хешей через timingSafeEqual, не через ===
☐ Реализован upsert пользователя по telegram_id (не по username!)
☐ Сессия или JWT выдаётся только после успешной проверки
☐ Cookie: httpOnly, secure, sameSite

Сессии:
☐ Сессии хранятся в Redis или PostgreSQL, не в памяти Node.js
☐ Установлен TTL для сессий
☐ Реализован выход (удаление сессии/инвалидация JWT)

Безопасность:
☐ Нет доверия initDataUnsafe.user без HMAC-проверки
☐ Все API-эндпоинты требуют аутентификации
☐ Логируются попытки неудачной авторизации

Тестирование:
☐ Проверена авторизация в реальном Telegram (не в тестовом клиенте)
☐ Проверен сценарий с устаревшими данными (auth_date > 24ч)
☐ Проверен сценарий с подменой hash