Розробка авторизації через Telegram Login у мобільному додатку

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

Ми часто стикаємося з запитами на інтеграцію Telegram Login. Помилка верифікації hash при інтеграції вхід через Telegram — типовий головний біль мобільних розробників. Клієнт передає дані від Telegram, сервер їх відхиляє. Або вибір методу авторизації: WebView проти Deep Link — призводить до архітектурних рішень, які потім важко переробити. Розберемося, які підводні камені чекають і як їх уникнути. Наш досвід 15+ проєктів за 5 років на ринку показує, що правильний вибір на старті економить до 2 тижнів розробки та до 40% бюджету.

Чому 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 годин) — потрібно обробляти окремо.
• Прив'язка до домену для мобільного додатка — потрібно реєструвати проміжний домен, що збільшує час впровадження на 1-2 дні.
• Потрібно дотримуватися правил коректної верифікації 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 (вартість від $800)

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