Разработка авторизации через 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 недели включено).

Для получения консультации и оценки вашего проекта свяжитесь с нами — это бесплатно и займёт один день. Мы поможем выбрать оптимальный метод и реализуем интеграцию Telegram Login с гарантией качества.

Что ломает аутентификацию в мобайле

Мы видели приложение банка, где PIN‑логин выдавал JWT, а токен ложился в SharedPreferences plain‑текстом. Не гипотетика — реальные финтех‑проекты, которые потом переписывали модуль авторизации заново. SharedPreferences на Android читается любым приложением с root‑доступом без дополнительных разрешений. На iOS аналог — UserDefaults вместо Keychain. Ошибка стоит дорого: средний ущерб от такой утечки превышает 3 млн рублей с учётом штрафов и репутационных потерь.

Аутентификация в мобайле принципиально сложнее веба: нет HttpOnly cookie, нет сессионного механизма браузера, зато есть платформенное хранилище и биометрия. Мы разработали модули авторизации для 30+ проектов (финтех, маркетплейсы, соцсети) и гарантируем соответствие правилам App Store и Google Play.

Как защитить токены при OAuth 2.0 аутентификации?

iOS Keychain — зашифрованное хранилище на уровне ОС. Данные защищены Secure Enclave на устройствах с Face ID/Touch ID. Правильный сценарий: JWT refresh token хранится с атрибутом kSecAttrAccessibleWhenUnlockedThisDeviceOnly — токен доступен только при разблокированном устройстве и не переносится при восстановлении из iCloud‑бэкапа.

// Сохранение в Keychain через Security framework
let query: [String: Any] = [
    kSecClass as String: kSecClassGenericPassword,
    kSecAttrService as String: "com.yourapp.auth",
    kSecAttrAccount as String: "refresh_token",
    kSecValueData as String: tokenData,
    kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly
]
SecItemAdd(query as CFDictionary, nil)

Android Keystore System — аппаратный (или программный на старых устройствах) модуль хранения криптографических ключей. Ключи нельзя экспортировать — операции шифрования/расшифровки внутри Keystore. Паттерн: генерируем ключ в Keystore, шифруем им refresh token, храним зашифрованный blob в EncryptedSharedPreferences (Jetpack Security).

EncryptedSharedPreferences — обёртка над SharedPreferences с шифрованием через Keystore. Добавляется за 5 минут и устраняет класс уязвимостей, который встречается в половине Android‑приложений.

Биометрическая аутентификация

iOS LocalAuthentication. LAContext.evaluatePolicy(.deviceOwnerAuthenticationWithBiometrics) — стандартный вызов для Face ID/Touch ID. Интегрируется с Keychain через kSecAccessControl с флагом .biometryCurrentSet: ключ становится недоступным после смены биометрических данных.

Типичный сценарий: при первом входе — логин по паролю, refresh token → Keychain с biometric protection. При последующих запусках — биометрия разблокирует доступ к токену, токен обменивается на новый access token. Использование биометрии с Keychain снижает риск компрометации токенов на 99% по сравнению с хранением в UserDefaults.

Android BiometricPrompt. Единый API для отпечатка пальца, лица и радужки. BiometricManager.canAuthenticate(BIOMETRIC_STRONG) проверяет доступность Class 3 биометрии (требование для финансовых приложений). BIOMETRIC_STRONG + Keystore‑ключ с setUserAuthenticationRequired(true) — ключ используется только после успешной биометрии в текущей сессии.

Почему OAuth 2.0 аутентификация с PKCE — стандарт

OAuth 2.0 Authorization Code Flow с PKCE (Proof Key for Code Exchange) — обязательный паттерн для мобильных приложений. Implicit Flow официально устарел в RFC 8252. PKCE вносит code_verifier (случайная строка) и code_challenge (SHA‑256 от verifier). Сервер авторизации проверяет соответствие при обмене code на token. Это защищает от перехвата authorization code через кастомную URL‑схему. Сравнение: PKCE повышает безопасность OAuth более чем в 1000 раз по сравнению с Implicit Flow, поскольку без proof key код можно украсть до обмена.

Согласно спецификации OAuth, использование PKCE обязательно для публичных клиентов, включая мобильные приложения.

iOS: ASWebAuthenticationSession — системный браузер для OAuth. Куки сессии не доступны приложению, нет возможности фишинга через embedded WebView. Apple отклоняет приложения, которые используют WKWebView для OAuth (Guideline 5.1.1).

Android: AppAuth‑Android — стандартная библиотека для OAuth/OIDC с поддержкой PKCE. Custom Tabs (Chrome) вместо WebView — тот же принцип безопасности.

Шаги реализации OAuth 2.0 аутентификации с PKCE на iOS

1. Генерируем code_verifier (минимум 43 символа из набора unreserved).
2. Вычисляем code_challenge = SHA256(code_verifier), кодируем base64url.
3. Открываем ASWebAuthenticationSession с URL авторизации, включающим code_challenge и code_challenge_method=S256.
4. После редиректа получаем authorization code.
5. Отправляем серверу POST‑запрос с code, code_verifier, client_id.
6. Сервер проверяет соответствие code_challenge и code_verifier, выдаёт токен.

Sign in with Apple и Google Sign-In

Sign in with Apple обязателен, если приложение предлагает любой другой способ входа через третью сторону (Google, Facebook). Apple требует его уже несколько лет, нарушение — rejection по Guideline 4.8.

Особенность: Apple может скрыть реальный email пользователя, предоставив relay‑адрес ([email protected]). Бэкенд должен корректно обрабатывать это — не использовать email как первичный идентификатор.

ASAuthorizationAppleIDProvider на iOS, SignInWithAppleButton в SwiftUI. JWT identity token от Apple содержит sub — стабильный идентификатор пользователя, не меняется при скрытии email.

Google Sign-In. На Android — через Credential Manager API (заменил прежний GoogleSignIn API). На iOS — GoogleSignIn SDK, открывающий Safari или Google App для авторизации.

2FA и одноразовые пароли

TOTP (Time‑based One‑Time Password, RFC 6238) — стандарт для 2FA. base32‑кодированный секрет генерируется на сервере, пользователь сканирует QR в Google Authenticator или Authy.

На мобайле встроенный Authenticator через Password AutoFill (iOS 15+) работает из Keychain: одноразовый код заполняется автоматически без отдельного приложения. Для этого поле OTP должно иметь textContentType = .oneTimeCode.

SMS OTP — наименее безопасный вариант (SIM‑swapping), но наиболее конверсионный. Если используется — только через SMSRetriever API на Android (код читается автоматически без разрешений) и ASAuthorizationController с oneTimeCode на iOS.

JWT: access и refresh токены

Паттерн: короткоживущий access token (15 минут – 1 час) + долгоживущий refresh token (30–90 дней). Access token в памяти (in‑memory — не в Keychain), refresh token в Keychain/EncryptedSharedPreferences. Silent refresh: при получении 401 — автоматический запрос нового access token с refresh token. Если refresh token истёк — принудительный логин.

Rotation refresh tokens: каждый обмен refresh token на access token выдаёт новый refresh token. Старый инвалидируется. Если старый refresh token попытался использоваться — компрометация, все токены пользователя отзываются.

Что входит в работу

При заказе модуля аутентификации мы предоставляем:

• Исходный код модуля авторизации (Swift/Kotlin) с интеграцией выбранных методов.
• Документацию по архитектуре и схеме токенов.
• Настроенный PKCE‑флоу для OAuth 2.0.
• Интеграцию Sign in with Apple и Google Sign-In по вашим client_id.
• Конфигурацию биометрии с правильными protection‑флагами.
• Инструкцию по деплою и тестированию (TestFlight, Firebase App Distribution).
• Чек‑лист для прохождения ревью App Store и Google Play.

Сроки и стоимость

Реализация базовой аутентификации (email + пароль + JWT) занимает от 1 до 2 недель. Добавление OAuth, биометрии и 2FA — ещё 1–3 недели. Итоговая стоимость рассчитывается после аудита вашего проекта. Получите консультацию — мы оценим сложность и предложим оптимальный стек.

Типичные ошибки (и как их избежать)

• Хранение токенов в UserDefaults / SharedPreferences — читаются без root на рутованных устройствах. Решение: Keychain / Keystore.
• Отсутствие certificate pinning в high‑security приложениях — MITM через корпоративный proxy. Решение: добавляем pinning в URLSession или OkHttp.
• Хранение секретов в Info.plist или BuildConfig — декомпилируются тривиально. Решение: использовать Keychain или серверную конфигурацию.
• OAuth через WKWebView / WebView вместо системного браузера — rejection App Store + security risk. Решение: ASWebAuthenticationSession / Custom Tabs.
• Неправильный kSecAttrAccessible — токен с kSecAttrAccessibleAlways не требует разблокировки устройства. Решение: WhenUnlockedThisDeviceOnly.

Мы реализовали безопасную аутентификацию для 30+ проектов за 5 лет работы. Гарантируем соответствие требованиям платформ и лучшим практикам (OAuth 2.0 + PKCE, Keychain, Keystore). Закажите разработку модуля аутентификации — разберём уязвимости и предложим решение под ваш бюджет. Получите консультацию через форму на сайте.