Разработка авторизации через Telegram Login в мобильном приложении

Разработка авторизации через Telegram Login

Мы часто сталкиваемся с запросами на интеграцию Telegram Login. Ошибка верификации hash при интеграции Telegram Login — типичная головная боль мобильных разработчиков. Клиент передаёт данные от Telegram, сервер их отвергает. Или выбор метода авторизации: WebView против Deep Link — приводит к архитектурным решениям, которые потом тяжело переделать. Разберёмся, какие подводные камни ждут и как их избежать. Наш опыт показывает, что правильный выбор на старте экономит до двух недель разработки.

Почему Telegram Login сложнее обычного OAuth?

В отличие от стандартных провайдеров (Google, Apple), Telegram не возвращает access token и не поддерживает refresh. Вся авторизация основана на одноразовом наборе данных, который нужно верифицировать на сервере. Это похоже на signed request в Facebook, но с другим алгоритмом. Отсутствие токена означает, что каждое открытие сессии требует повторной авторизации, если не хранить данные локально.

Проблемы, которые мы решаем

Telegram Login — нестандартный OAuth. У Telegram нет OIDC-совместимого провайдера, нет привычного Authorization Code Flow. Вместо этого — собственный виджет/протокол с криптографической верификацией через HMAC-SHA256. Это требует аккуратной реализации на стороне сервера и нескольких вариантов на клиенте в зависимости от задачи.

Ключевые сложности:

• Отсутствие OIDC: Telegram использует кастомный протокол с HMAC-SHA256, что сильно отличается от Google или Apple.
• Edge-case: пользователь без Telegram, без username, с устаревшими данными (auth_date старше 24 часов) — нужно обрабатывать отдельно.
• Привязка к домену для мобильного приложения — нужно регистрировать промежуточный домен, что увеличивает время внедрения.
• Требуется соблюдение правил корректной верификации Telegram API.

Два варианта Telegram Login для мобильных приложений

Telegram Login Widget — JavaScript-виджет для веба, который открывается в WebView внутри приложения. Пользователь нажимает «Войти через Telegram», появляется popup или QR, пользователь подтверждает в Telegram-приложении. Callback приходит в WebView с данными пользователя. Простейший вариант, минимум кода.

Telegram Bot + Deep Link — более нативный подход для мобильных. Бот генерирует одноразовую ссылку tg://resolve?domain=YOUR_BOT&start=AUTH_TOKEN. Приложение открывает эту ссылку — система открывает Telegram с чатом бота. Пользователь нажимает Start, бот получает сообщение /start AUTH_TOKEN через Webhook, верифицирует токен, вызывает ваш API. Приложение ждёт callback через WebSocket или polling.

Второй вариант сложнее архитектурно, но даёт полностью нативный UX: Telegram открывается как обычное приложение через Universal Link, не WebView. Deep Link снижает количество неудачных авторизаций на 40% по сравнению с WebView, что напрямую влияет на конверсию.

Когда стоит выбрать Deep Link, а когда WebView?

Если приложение премиум-класса и нативный опыт важен — выбирайте Deep Link через бота. Если время выхода на рынок критично, а UX можно упростить — подойдёт WebView. Наш опыт показывает, что 70% клиентов начинают с WebView для MVP, а потом мигрируют на Deep Link, когда появляется бюджет. WebView вариант в 2 раза быстрее в реализации, но Deep Link даёт больше гибкости в будущем.

WebView vs Deep Link: сравнительная таблица

Как провести верификацию данных Telegram: пошаговая инструкция

1. Получите данные авторизации от клиента (id, first_name, username, auth_date, hash).
2. Удалите хэш из набора данных.
3. Отсортируйте оставшиеся пары ключ-значение по ключу.
4. Сформируйте строку вида key=value, разделённые символом новой строки.
5. Вычислите SHA256 от bot_token (используйте его как ключ HMAC).
6. Вычислите HMAC-SHA256 от строки с использованием этого ключа.
7. Сравните полученный хэш с переданным hash.
8. Проверьте, что auth_date не старше 24 часов (86400 секунд).

# Python (серверная сторона) import hashlib import hmac import time def verify_telegram_auth(bot_token: str, auth_data: dict) -> bool: check_hash = auth_data.pop('hash') # Строка для верификации: отсортированные пары key=value через \n data_check_string = '\n'.join( f'{k}={v}' for k, v in sorted(auth_data.items()) ) # Секрет — SHA256 от bot token (не сам токен) secret_key = hashlib.sha256(bot_token.encode()).digest() # HMAC-SHA256 calculated_hash = hmac.new( secret_key, data_check_string.encode(), hashlib.sha256 ).hexdigest() # Проверяем хэш и свежесть данных (не старше 24 часов) return (calculated_hash == check_hash and time.time() - int(auth_data['auth_date']) < 86400) 

Реализация WebView варианта

На мобильном клиенте проще всего: загружаем HTML-страницу с Telegram Login Widget в WKWebView (iOS) / WebView (Android). Страница сообщает результат через window.postMessage или URL redirect на custom scheme.

// iOS — обработка redirect из WebView func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) { if let url = navigationAction.request.url, url.scheme == "myapp", url.host == "telegram-callback" { // Парсим query params — данные от Telegram let components = URLComponents(url: url, resolvingAgainstBaseURL: false) let params = components?.queryItems?.reduce([String:String]()) { ... } handleTelegramAuth(params) decisionHandler(.cancel) return } decisionHandler(.allow) } 

Этапы разработки интеграции Telegram Login

Что входит в реализацию Telegram Login

• Аудит текущей архитектуры и выбор метода.
• Настройка бота (BotFather) и Webhook.
• Разработка серверного эндпоинта верификации с HMAC-SHA256.
• Реализация клиентского кода (WebView или Deep Link).
• Интеграционные тесты с реальными аккаунтами Telegram.
• Документация по схеме авторизации.
• Поддержка после деплоя (2 недели включено).