Как реализовать привязку и вход по номеру телефона с помощью Magic Link

В современной разработке термин «магия» (Magic Link) обычно относится к технологии беспарольной аутентификации (Passwordless Authentication). Суть метода проста: пользователь вводит только номер телефона (или email), получает уникальную ссылку с криптографически стойким токеном, переходит по ней и мгновенно авторизуется в системе. Никаких паролей, кодов из СМС для ввода вручную или сложных форм.

В этой статье мы подробно разберем, как реализовать привязку и вход по номеру телефона с помощью Magic Link, рассмотрим архитектуру, безопасность и нюансы внедрения.

Принцип работы: Как это устроено «под капотом»

Технически процесс выглядит как последовательность надежных криптографических операций:

1. Запрос: Пользователь вводит номер телефона на клиенте (веб/мобильное приложение) и нажимает «Войти».
2. Генерация токена: Сервер генерирует криптографически стойкий случайный токен (обычно 32+ байта, кодируемый в Base64URL или HEX).
3. Сохранение состояния: Токен хешируется (bcrypt/Argon2) и сохраняется в БД с привязкой к номеру телефона, временем создания (TTL), статусом «не использован» и метаданными (User-Agent, IP).
4. Доставка: Сервер формирует ссылку вида https://app.example.com/auth/callback?token=eyJhbGciOiJIUzI1NiIs... и отправляет её через SMS-шлюз (или WhatsApp/Telegram/Viber) на номер пользователя.
5. Переход: Пользователь открывает ссылку на устройстве.
6. Верификация: Бэкенд извлекает токен из URL, хеширует его и ищет в БД. Проверяется: существование, срок действия (обычно 5–15 минут), статус «не использован», привязка к номеру.
7. Создание сессии: При успехе токен помечается как «использован» (инвалидируется), создается JWT (Access/Refresh токены) или сессионная кука, пользователь редиректится в личный кабинет.

Пошаговая реализация (Backend-логика)

Этап 1: Эндпоинт запроса ссылки (Request Magic Link)

POST /api/v1/auth/magic-link/request
Content-Type: application/json

{
 "phone": "+7 -001234567",
 "device_fingerprint": "optional_client_hash"
}

Логика контроллера:

• Нормализация номера (E.164 формат).
• Rate Limiting: не более N запросов в минуту с одного IP/номера (защита от спама и брутфорса).
• Генерация raw_token = crypto.randomBytes(32).
• Хеширование: token_hash = await argon2.hash(raw_token).
• Запись в БД: MagicLinkToken { hash, phone, expires_at, used: false, meta }.
• Формирование URL: ${FRONTEND_URL}/auth/verify?token=${base64url.encode(raw_token)}.
• Отправка через SMS-провайдера (Twilio, Vonage, локальные гейты). Текст: «Ваша ссылка для входа в [App Name]: [URL]. Ссылка действует 10 минут. Не передавайте её никому».
• Возврат 202 Accepted (не раскрываем, существует ли пользователь).

Этап 2: Эндпоинт верификации (Verify Magic Link)

GET /api/v1/auth/magic-link/verify?token=eyJhbGciOiJIUzI1NiIs...

Логика контроллера:

• Декодирование токена из query-параметра.
• Поиск в БД по хешу (или перебор неиспользованных токенов для этого номера с верификацией хеша — в зависимости от индексов).
• Проверки:
  • Токен найден?
  • !used?
  • now < expires_at?
  • (Опционально) Соответствие User-Agent/IP?
• Если проверки пройдены: UPDATE ... SET used = true.
• Поиск/Создание пользователя (User) по номеру телефона.
• Генерация пары токенов доступа (Access Token + Refresh Token) или установка HttpOnly Secure Cookie.
• Редирект на фронтенд с токенами (в фрагменте URL для SPA или через куки).

Критические аспекты безопасности

«Магия» требует строгого соблюдения мер защиты, так как ссылка, это эквивалент пароля.

Однократность и короткий TTL

Токен обязан инвалидироваться сразу после использования. Время жизни (TTL) — 5–15 минут. Долгосрочные ссылки недопустимы.

Защита от перехвата (MITM)

• Используйте только HTTPS (HSTS, Certificate Pinning для мобильных приложений).
• Токен передается в URL — он попадает в логи прокси, браузеры, Referer-заголовки при переходе на сторонние ресурсы со страницы колбэка.
  • Решение: Страница колбэка (/auth/verify) должна быть максимально «чистой» — без сторонних скриптов, аналитики, картинок с внешних CDN. Сразу обменивать токен на куки/JWT и редиректить на главную (POST-запросом или через фрагмент #token=...).

Rate Limiting и бот-протекшн

• Лимиты на запрос ссылки (по IP, по номеру, по Device ID).
• CAPTCHA / Turnstile / reCAPTCHA на форме ввода номера.
• Мониторинг аномалий: много запросов на несуществующие номера, запросы из дата-центров (VPN/Proxy).

Привязка к устройству (Device Binding)

Для высокобезопасных систем (банкинг, госуслуги) при генерации ссылки сохраняют Device Fingerprint (User-Agent, хеш IP, Client Hints). При верификации сравнивают с текущим. Если не совпадает — требуют второй фактор (2FA) или блокируют вход.

Отзыв доступа (Revocation)

Должен существовать админский интерфейс или API для инвалидации всех активных Magic Link токенов пользователя (например, при смене номера телефона или подозрении на компрометацию).

Фронтенд: UX лучших практик

• Автоопределение: Используйте <input type="tel" autocomplete="tel"> и маски ввода (Inputmask / Cleave.js).
• Deep Linking (App Links / Universal Links): Если у вас есть нативное приложение, настройте assetlinks.json (Android) и apple-app-site-association (iOS). Ссылка из СМС должна открывать именно приложение, а не браузер. Это критично для конверсии.
• Состояния загрузки: Показывайте спиннер на кнопке «Отправить», таймер обратного отсчета для повторной отправки (Resend timer).
• Обработка ошибок: Четкие сообщения: «Ссылка устарела», «Ссылка уже использована», «Неверный формат номера».

Важное уточнение: HONOR Magic-link 2.0 vs Auth Magic Links

В интернете часто встречается термин HONOR Magic-link 2.0 (или Huawei Share). Это совершенно другая технология.

Пример структуры БД (PostgreSQL / MySQL)

CREATE TABLE magic_link_tokens (
 id BIGSERIAL PRIMARY KEY,
 token_hash VARCHAR(255) NOT NULL, -- Argon2id hash
 phone VARCHAR(20) NOT NULL, -- E.164 format
 user_id BIGINT NULL REFERENCES users(id), -- NULL если новый юзер
 expires_at TIMESTAMPTZ NOT NULL,
 used_at TIMESTAMPTZ NULL,
 created_at TIMESTAMPTZ DEFAULT NOW,
 meta JSONB DEFAULT '{}'::jsonb, -- ip, user_agent, device_fp
  CONSTRAINT chk_not_used CHECK (used_at IS NULL OR used_at > created_at)
);

CREATE INDEX idx_magic_phone_expires ON magic_link_tokens (phone, expires_at) WHERE used_at IS NULL;
-- Индекс для быстрой очистки просроченных и поиска при верификации

Чек-лист перед релизом

1. [ ] Токен генерируется CSPRNG (crypto.randomBytes, secrets.token_urlsafe).
2. [ ] В БД хранится только хеш (Argon2id / bcrypt), никогда raw token.
3. [ ] TTL ≤ 15 минут.
4. [ ] Токен инвалидируется сразу после успешного входа (One-time use).
5. [ ] Rate Limiting на эндпоинт /request.
6. [ ] Страница /verify не загружает сторонние ресурсы (CSP: default-src 'self').
7. [ ] Настроены Universal Links / App Links для мобильного приложения.
8. [ ] Есть логирование анонимно (без токенов в логах!) для аудита безопасности.
9. [ ] Реализована очистка просроченных токенов (Cron job / Partitioning).

Реализация привязки по номеру телефона через Magic Link, это золотой стандарт UX для современных приложений. Она убирает трение (friction) при регистрации и входе, снижает нагрузку на поддержку («забыл пароль») и при правильной реализации обеспечивает высокий уровень безопасности.

Главное, уважать криптографическую гигиену: короткие сроки жизни, однократное использование, защита канала доставки (HTTPS) и изоляция страницы верификации. Тогда «магия» будет работать надежно и предсказуемо.