🔐 Авторизация через Telegram Mini Apps

Telegram Mini Apps открывают новые возможности для создания интегрированных веб-приложений прямо внутри мессенджера. Одна из ключевых фич — простая и безопасная авторизация пользователей.

🚀 Что такое Telegram Mini Apps?

Мини-приложения Telegram — это веб-приложения, которые запускаются внутри Telegram и имеют доступ к данным пользователя через специальное API. Главное преимущество — пользователю не нужно проходить дополнительную регистрацию.

🔑 Принцип работы авторизации

1. Получение initData

При запуске мини-приложения Telegram передает специальную строку initData, которая содержит:

Информацию о пользователе
Данные о чате (если запущено из чата)
Временную метку
Подпись для верификации

2. Структура initData

query_id=AAHdF6IQAAAAAN0XohAOqR8&user=%7B%22id%22%3A279058397...

После декодирования получаем:

user — данные пользователя (id, first_name, username и т.д.)
chat — информация о чате
auth_date — время авторизации
hash — HMAC-SHA256 подпись

⚙️ Реализация на сервере

Шаг 1: Валидация подписи

const crypto = require('crypto');

function validateTelegramData(initData, botToken) {
    const urlParams = new URLSearchParams(initData);
    const hash = urlParams.get('hash');
    urlParams.delete('hash');
    
    // Сортируем параметры
    const dataCheckString = Array.from(urlParams.entries())
        .sort(([a], [b]) => a.localeCompare(b))
        .map(([key, value]) => `${key}=${value}`)
        .join('\n');
    
    // Создаем секретный ключ
    const secretKey = crypto
        .createHmac('sha256', 'WebAppData')
        .update(botToken)
        .digest();
    
    // Проверяем подпись
    const calculatedHash = crypto
        .createHmac('sha256', secretKey)
        .update(dataCheckString)
        .digest('hex');
    
    return calculatedHash === hash;
}

Шаг 2: Извлечение данных пользователя

function parseUserData(initData) {
    const urlParams = new URLSearchParams(initData);
    const userStr = urlParams.get('user');
    
    if (!userStr) return null;
    
    return JSON.parse(decodeURIComponent(userStr));
}

🌐 Реализация на фронтенде

Получение initData

// Через Telegram Web App API
const initData = window.Telegram.WebApp.initData;

// Или из URL параметров
const urlParams = new URLSearchParams(window.location.search);
const tgWebAppData = urlParams.get('tgWebAppData');

Отправка на сервер

async function authenticateUser() {
    const response = await fetch('/api/auth', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            initData: window.Telegram.WebApp.initData
        })
    });
    
    const result = await response.json();
    return result.user;
}

🛡️ Безопасность

Важные моменты:

Всегда валидируйте подпись на сервере
Проверяйте auth_date — данные не должны быть старше 1 часа
Не доверяйте фронтенду — вся валидация только на сервере
Храните bot_token в секрете — никогда не передавайте на клиент

Проверка времени

function isDataFresh(authDate) {
    const now = Math.floor(Date.now() / 1000);
    const maxAge = 3600; // 1 час
    return (now - authDate) <= maxAge;
}

📱 Практический пример

Express.js сервер

app.post('/api/auth', (req, res) => {
    const { initData } = req.body;
    
    // Валидация
    if (!validateTelegramData(initData, process.env.BOT_TOKEN)) {
        return res.status(401).json({ error: 'Invalid data' });
    }
    
    // Получение пользователя
    const user = parseUserData(initData);
    
    // Генерация JWT токена
    const token = jwt.sign({ telegramId: user.id }, process.env.JWT_SECRET);
    
    res.json({ token, user });
});

React компонент

function App() {
    const [user, setUser] = useState(null);
    
    useEffect(() => {
        if (window.Telegram?.WebApp) {
            window.Telegram.WebApp.ready();
            authenticateUser().then(setUser);
        }
    }, []);
    
    return (
        <div>
            {user ? (
                <h1>Привет, {user.first_name}!</h1>
            ) : (
                <p>Загрузка...</p>
            )}
        </div>
    );
}

✅ Преимущества

Мгновенная авторизация — без форм и паролей
Высокая безопасность — криптографическая подпись
UX — пользователь уже авторизован в Telegram
Простота — минимум кода для интеграции

⚠️ Ограничения

Работает только внутри Telegram
Зависимость от Telegram API
Ограниченная кастомизация процесса авторизации

🎯 Заключение

Авторизация через Telegram Mini Apps — это современный и удобный способ аутентификации, который значительно упрощает onboarding пользователей. При правильной реализации обеспечивает высокий уровень безопасности и отличный пользовательский опыт.

💡 Совет: Начните с простой реализации и постепенно добавляйте дополнительные функции, такие как роли пользователей и расширенные данные профиля.

🔗 Полезные ссылки: