Перейти к основному содержанию
Канал — это доверенное приложение, где пользователь подтверждает вход. Veriqa поставляет восемь адаптеров — MAX, Telegram, WhatsApp, Instagram*, Messenger*, WeChat, Viber и Email, — и настраиваются они одинаково: при встроенном запуске Veriqa и при self-hosted. Каждый канал проходит одни и те же три шага: зарегистрировать адаптер в коде, заполнить его секцию конфигурации Veriqa:Channels:{Channel} и сделать его вебхук доступным из интернета.
Program.cs
Каждый канал — свой пакет. Базовый набор ставится одним метапакетом Veriqa.Core.BaseChannels (Telegram, WhatsApp, Email); MAX, Instagram*, Messenger*, WeChat и Viber в него не входят и ставятся явно — dotnet add package Veriqa.Core.ChannelAdapter.Max, dotnet add package Veriqa.Core.ChannelAdapter.Instagram, dotnet add package Veriqa.Core.ChannelAdapter.Messenger, dotnet add package Veriqa.Core.ChannelAdapter.WeChat, dotnet add package Veriqa.Core.ChannelAdapter.Viber. Нужен один канал — ставьте только его пакет (Veriqa.Core.ChannelAdapter.Telegram, .WhatsApp, .Max, .Instagram, .Messenger, .WeChat, .Viber, .Email): вместе с ним приедет только его SDK, и почтовая библиотека не окажется в установке, которая пускает пользователей через Telegram. Вызов регистрации от выбора пакета не зависит — adapters.AddTelegram() пишется одинаково в обоих случаях. Если пакета канала нет, а Add*() вызван — это ошибка компиляции, а не молчаливо отсутствующий канал. Вход через аккаунт провайдера — тоже отдельный пакет, Veriqa.Core.ChannelAdapter.WebProviders, см. Вход через аккаунт провайдера.
Регистрация адаптера — не то же самое, что его включение. Адаптер включается, только если в его секции стоит "Enabled": true; иначе регистрируются лишь его опции и стартовый валидатор, а канал никогда не появляется на странице входа. Добавляйте только те каналы, которые используете.
Токены ботов, access-токены и SMTP-пароли — секреты. Держите их в user-secrets в разработке и в хранилище секретов в продакшне, но никогда — в закоммиченном appsettings.json.

Уровень проверки входящего события

У каждой канальной секции есть обязательный ключ InboundVerification — он объявляет, как проверяется подлинность входящего события этого канала. Факт объявляете вы: Veriqa видит лишь то, что проверка выполнилась и прошла, но не то, чем именно она была.
Развёртывание, где включён поставляемый канал, а значение не задано или не входит в словарь, не стартует. Проставьте значение и в секциях выключенных каналов — тогда переключение Enabled в true не остановит старт. Стартовая проверка перебирает тот же набор каналов, из которого ядро строит список включённых. Все поставляемые каналы в нём есть, а канала стороннего адаптера, подключённого одним вызовом AddChannel, нет: ключ его секции обязателен, но на старте не проверяется (см. Свой канал на C#).
Значения для поставляемых каналов — по режиму, в котором вы их запускаете: Если каналу в режиме Polling (в том числе Email, который читает ящик по IMAP) объявлено значение, отличное от outbound_fetch, при старте в логе появляется Warning; старт при этом продолжается. Полный словарь значений — в справочнике конфигурации.

Настройки, общие для любого канала с чатом

В секцию любого канала — поставляемого, канала вашего адаптера или HTTP-канала — можно добавить два необязательных ключа. Задавать их не требуется: развёртывание, которое о них молчит, ведёт себя так, как описано на этой странице.
appsettings.json
Оба ключа задаются на том же уровне, что и учётные данные канала: в конфигурации хоста либо для одного тенанта. Имя попадает в два текста страниц — подпись над запасным кодом, «Отправьте код в чате с ботом Acme Support, если бот не отправил вам подтверждения», и строку, которая просит подтвердить вход в чате. Эту просьбу страница входа и страница, открывающая подтверждение, показывают в строке состояния для любого канала с чатом, как только бот ответил на старт: пользователь вошёл в переписку, и ответ теперь ждут там. Если имя не задано, оба текста показываются в формулировке без имени; название канала на его место не подставляется. Выключенный запасной код означает, что страницы его не предлагают и код от имени этого канала не выдаётся. Отказываться от кода канал при этом не начинает: код у транзакции один, и код, выданный ради другого канала того же входа, там по-прежнему принимается. Один бот или аккаунт обслуживает одного тенанта. Событие, которое пришло на адрес тенанта или которое ядро получило опросом для тенанта, действует только на вход или подтверждение этого тенанта: ссылка, кнопка или код чужого входа получают тот же ответ, что и несуществующие, а сам вход не меняется. Бот или аккаунт на нескольких тенантов не поддерживается: его вебхук указывает на адрес одного тенанта, и пользователи остальных через него не войдут. Бот, общий для всей установки, работает на адресе без сегмента тенанта — там тенант берётся из самого входа.

Telegram

Вход на компьютере через Telegram: в окне входа QR-код, камера телефона его сканирует, пользователь нажимает «Подтвердить» в чате Telegram, бот отвечает «Вход подтверждён».

Что видит пользователь: QR-код, камера телефона, одно касание в Telegram.

Что нужно: бот, созданный через @BotFather, и его токен.
appsettings.json
В режиме Webhook Veriqa регистрирует вебхук сам на старте (и снимает при остановке) — вы не вызываете setWebhook вручную. Эндпоинт — POST {WebhookBaseUrl}/api/channels/telegram/webhook, а заголовок X-Telegram-Bot-Api-Secret-Token каждого запроса Veriqa сверяет с WebhookSecretToken. Регистрация не задерживает старт: если Bot API не отвечает или отказывает, хост всё равно стартует, пишет предупреждение в лог и повторяет попытки в фоне, а пауза между ними растёт до пяти минут. Пока вебхук не зарегистрирован, проверка здоровья каналов показывает канал unhealthy.
Режим Polling не требует публичного URL, поэтому он подходит для локальной разработки; на развёрнутой установке переключайтесь на Webhook. Ещё он допускает только одного опрашивающего на бота: Bot API отдаёт очередь обновлений единственному клиенту getUpdates. Второй процесс на том же токене не получает ничего, а его цикл опроса повторяет отказ 409 Bot API; в логе отказ записан как Conflict: terminated by other getUpdates request, без номера. Отчёт здоровья этого не ловит — токен валиден, и канал считает себя healthy (запуск более одного инстанса).
Telegram не отдаёт email, а номер телефона даёт только тогда, когда Veriqa запрашивает его в чате. И то и другое можно собрать внутри входа: Номер телефона, Получение телефона и email.

WhatsApp

Вход на компьютере через WhatsApp: камера телефона сканирует QR-код, WhatsApp открывает готовое сообщение, пользователь отправляет его, бот отвечает «Вход подтверждён».

Что видит пользователь: QR-код, камера телефона, отправка готового сообщения в WhatsApp.

Что нужно (Meta* Cloud API, провайдер по умолчанию): Meta*-приложение с WhatsApp Business, phone number ID и постоянный access-токен из консоли Meta* for Developers. Доставка через Twilio настраивается ниже.
Сообщения WhatsApp платные сверх бесплатного объёма. Вопрос и квитанция — сервисные сообщения: 1000 в месяц на номер бесплатно, а с 1 октября 2026 года каждое следующее платное по тарифам Meta*. Без способа оплаты в аккаунте Meta* не доставляет сообщения сверх этого объёма, и вход перестаёт работать. Twilio добавляет свой сбор за каждое сообщение, входящее и исходящее.
appsettings.json
BusinessPhoneNumber — номер в формате E.164, на который пишут пользователи; на него указывают deep link и QR-код. В отличие от Telegram, вебхук регистрируется на стороне Meta*. В панели приложения WhatsApp → Configuration задайте callback URL https://auth.your-domain.com/api/channels/whatsapp/webhook, вставьте тот же WebhookVerifyToken и подпишитесь на поле messages. Meta* верифицирует URL запросом GET с hub.mode и hub.verify_token; Veriqa отвечает на него автоматически, как только канал включён и хост публично доступен. Каждый следующий POST Meta* подписывает заголовком X-Hub-Signature-256, а Veriqa сверяет подпись с AppSecret. Если AppSecret не задан или неверен, Veriqa отвергает и подлинные доставки.
С каналом поставляются два провайдера доставки: Meta* Cloud API (MetaCloudApi, по умолчанию) и Twilio (Twilio). Ключ Provider выбирает, какой из них регистрируется, и объявляет, какого провайдера ожидает установка; на старте он сверяется с фактически зарегистрированным. Собственный провайдер, подключённый через UseWhatsAppProvider<TProvider>(), заменяет поставляемый, и в Provider ставится его код. Расхождение останавливает хост с ошибкой, называющей оба кода. Такой провайдер обязан заполнять SenderUserId каждого входящего сообщения business-scoped user ID (BSUID) отправителя — сообщение без него отклоняется — и получает BSUID как получателя каждого исходящего сообщения.

Доставка через Twilio

Что нужно: аккаунт Twilio (Account SID и Auth Token), WhatsApp-отправитель (чтобы попробовать — Twilio Sandbox for WhatsApp, в продакшне — зарегистрированный отправитель) и контент twilio/quick-reply, созданный в Twilio Content Template Builder.
appsettings.json
BusinessPhoneNumber — номер отправителя Twilio (при Sandbox — номер песочницы). При Provider = Twilio обязательны AccountSid, AuthToken, QuickReplyContentSid и WebhookUrl: без любого из них хост не стартует, а ошибка называет ключ, но не его значение. ApiBaseUrl необязателен, по умолчанию https://api.twilio.com. Учётные данные Twilio тенант хранит в той же группе WhatsApp, что и учётные данные Meta*. Контент quick-reply. Вопрос подтверждения уходит одним контентом с двумя кнопками. Создайте его типа twilio/quick-reply ровно с этими переменными — Veriqa заполняет их сама:
twilio/quick-reply
Вопрос отвечает на сообщение самого пользователя, поэтому уходит внутри 24-часовой сессии, и одобрение шаблона WhatsApp ему не нужно. Не отправляйте этот контент на одобрение. Вебхук. В консоли Twilio задайте URL входящих сообщений отправителя (у Sandbox — When a message comes in, метод POST): https://auth.your-domain.com/api/channels/whatsapp/webhook. Twilio подписывает каждый запрос заголовком X-Twilio-Signature, посчитанным над URL, который знает он, поэтому WebhookUrl должен совпадать с этим URL символ в символ — схема, хост, порт, путь и query. За прокси Veriqa видит свой внутренний адрес, поэтому URL берётся из конфигурации, а не из запроса; расхождение отвергает каждое входящее сообщение с 403. Тенант со своим маршрутом вебхука указывает свой WebhookUrl. GET-рукопожатия у Twilio нет: GET на вебхук отвергается. При Sandbox каждый тестовый телефон один раз присоединяется к песочнице, отправив на её номер join <keyword>; ключевое слово показано в консоли Twilio. Этот провайдер работает внутри Veriqa. Пример node/custom-channel-whatsapp-twilio — другое: внешний адаптер, работающий отдельным сервисом под собственным типом канала, см. Свой канал на любом языке.

Текст предзаполненного сообщения

WhatsApp — единственный из поставляемых каналов, где deep link несёт текст сообщения, а не служебный параметр: пользователь видит его в поле ввода и отправляет как обычное сообщение. Текст зависит от того, где открывается ссылка. Кнопка канала и ссылка, к которой ведёт QR-код hop-режима, несут сообщение с линейками. В QR-код, который несёт саму ссылку, идёт короткое сообщение без графики: каждый лишний символ делает такой QR-код плотнее (см. предупреждение ниже). Код входа в обоих стоит на последней строке:
Кнопка и hop-режим — базовый текст (en)
QR-код с самой ссылкой — базовый текст (en)
Текст настраивается там же, где остальные тексты каналов — в locale-файлах вашего хоста (wwwroot/locales/{язык}.json, см. Локализация). Ключей четыре: у каждого из двух сообщений есть полный вариант с именем приложения и запасной без него. Запасной используется, когда имя приложения недоступно. Отдельной секции в Veriqa:Channels:WhatsApp для текста нет.
wwwroot/locales/ru.json
У подтверждения свои четыре ключа с теми же раскладками:
wwwroot/locales/ru.json
Шаблоны лежат в deeplink-prefill:ByType:confirmation, поэтому правка ключей входа их не меняет. Какое сообщение получает какая ссылка, задаёт конфигурация шаблонов deeplink-prefill — ось link_purpose в Veriqa:MessageTemplates. Чтобы, например, кнопка тоже получала короткое сообщение, задайте там свой шаблон для button. Свой текст задаётся значением этих ключей (для английского — правкой en.json). Доступны два слота: {app} — имя приложения, к которому идёт вход, и {code} — код входа auth_…. Язык берётся из транзакции, поэтому переводить стоит все языки, которые вы поставляете. Имя приложения приходит из регистрации вашего OIDC-клиента и подставляется как есть — Veriqa его не сокращает (общий предел значения слота — 128 символов). Держите имя коротким: длинное ломает вёрстку сообщения и целиком уходит в QR-код, увеличивая его плотность (см. предупреждение ниже).
Длина текста напрямую влияет на читаемость QR-кода. В QR-коде кодируется весь wa.me-URL, а текст в нём percent-кодируется: пробел и перевод строки стоят 3 символа, буква кириллицы — 6, символ псевдографики вроде ═ — 9. Чем длиннее текст, тем выше версия QR-кода и тем мельче его модули при том же размере картинки на экране.
Отсюда следуют правила оформления:
  • код — последней отдельной строкой: его длина — 48 символов (auth_ + идентификатор транзакции на 43 символа) и не влезает ни в какую рамку;
  • не использовать *, _, ~ как элементы графики — WhatsApp трактует их как разметку (жирный, курсив, зачёркнутый). Безопасны -, ., :, +, |;
  • рамки с вертикальными палками (|…|) выравниваются только внутри моноширинного блока (тройные бэктики) — в обычном сообщении шрифт пропорциональный и рамка разъедется. Часть клиентов к тому же показывает в поле ввода сами бэктики, а моноширинность — уже в отправленном сообщении, поэтому такое оформление проверяйте на устройстве до запуска;
  • горизонтальные линейки (------) работают в любом клиенте и обёртки не требуют.
Таблица показывает, во что обходится оформление. Замер сделан генератором QR-кодов из поставки Veriqa: телефон 11 цифр, идентификатор транзакции 43 символа, уровень коррекции M, имя приложения «Acme Corp». Колонка «px на модуль» — размер одного модуля QR-кода при штатном боксе 220 px на странице входа. Порог сканируемости — 2,86 px на модуль. Строки помечены языком текста — нелатинский алфавит стоит заметно дороже за символ: Русские варианты без графики и с линейками-заголовком стоят ровно на пороге — запаса у них нет: любое удлинение текста поднимает версию QR-кода и выводит код из нормы. Английский вариант без графики проходит с запасом. У вариантов с рамкой препятствий два: русские рамки не проходят ещё и порог плотности (2,37 и 1,88), а моноширинный блок нужен любой рамке — даже английская, стоящая ровно на пороге, в обычном сообщении разъедется. Отсюда «Нет» в колонке. Практический вывод: если сообщение показывается и как QR-код, держитесь варианта без графики или ограничьтесь горизонтальными линейками — рамки и псевдографика делают QR-код трудным для камеры. Русский текст обходится примерно вдвое дороже английского при том же оформлении: тот же текст без графики стоит 388 символов против 171. Готовые образцы каждого варианта — ниже; {app} и {code} подставит Veriqa.
Без графики — по умолчанию для QR-кода с самой ссылкой
Линейки из дефисов + центрированный заголовок — по умолчанию для кнопки и hop-режима
Линейки из дефисов
Варианты с рамкой требуют моноширинного блока — сам текст обёрнут в тройные бэктики, а код вынесен под блок (внутрь рамки строка кода не влезает):
Рамка «+--+» — только после проверки на устройстве
Рамка Unicode — самый дорогой вариант, для QR-кода непригоден
Выбранный образец переносится в locale-файл одной строкой — переводы строк записываются как \n. Например, так QR-код с самой ссылкой получит линейки, как у кнопки:
wwwroot/locales/ru.json — вариант с линейками для QR-кода с самой ссылкой
Оформляйте оба ключа сразу. Второй — запасной вариант без имени приложения; если оформить только первый, пользователи, у которых имя приложения недоступно, увидят другое сообщение. Выравнивание по {app} — приблизительное: имя приложения у каждого клиента своей длины, поэтому ни центрирование пробелами, ни правая граница рамки не сойдутся точно. Если рамка нужна ровной — берите вариант без имени приложения.

MAX

Вход на компьютере через MAX: в окне входа QR-код, камера телефона его сканирует, пользователь нажимает «Подтвердить» в чате MAX, бот отвечает «Вход подтверждён».

Что видит пользователь: QR-код, камера телефона, одно касание в MAX.

Что нужно: бот MAX и его токен. Конфигурация такая же, как у Telegram:
appsettings.json
Как и с Telegram, Veriqa регистрирует вебхук на старте в режиме Webhook. При остановке она снимает свою подписку — ту, что зарегистрировала на этот адрес. Эндпоинт — POST {WebhookBaseUrl}/api/channels/max/webhook, аутентифицируется заголовком X-Max-Bot-Api-Secret. BotPublicName — имя, показываемое пользователю на странице входа. ApiBaseUrl — адрес MAX Bot API, на который канал отправляет все запросы. По умолчанию это https://platform-api2.max.ru: с 19 июля 2026 года MAX требует от ботов обращаться на этот домен. Меняйте значение, только если MAX объявит другой адрес. Это настройка установки, а не тенанта. Значение должно быть абсолютным HTTPS-адресом из схемы, хоста и при необходимости порта, без пути, строки запроса и фрагмента, иначе хост не запустится.
Цепочка сертификата platform-api2.max.ru ведёт к Russian Trusted Root CA — корневому сертификату Минцифры, и MAX просит владельцев ботов добавить его в доверенные (журнал изменений MAX Bot API, 19 июля 2026 года). Добавьте его в хранилище доверенных сертификатов машины или образа контейнера, где работает Veriqa. Без него ни один запрос к Bot API не пройдёт проверку TLS: бот не отправит сообщения, а вебхук не зарегистрируется.

Instagram*

Пользователь подтверждает вход в Instagram* Direct — в переписке с вашим аккаунтом Instagram*. Канал работает на Instagram* API with Instagram* Login и обращается к graph.instagram.com по обычному HTTP — SDK платформы в пакете нет.
Вход на компьютере через Instagram*: в окне входа QR-код, камера телефона его сканирует, пользователь нажимает «Confirm» в чате Instagram*, бот отвечает «Sign-in confirmed».

Что видит пользователь: QR-код, камера телефона, одно касание в Instagram*. Интерфейс на английском.

Что нужно: профессиональный аккаунт Instagram* (business или creator), Meta*-приложение из консоли Meta* for Developers с подключённым к нему аккаунтом, а из консоли — секрет приложения, access-токен аккаунта, идентификатор аккаунта и его username.
appsettings.json
При "Enabled": true обязательны AppSecret, WebhookVerifyToken, AccessToken, AccountId и Username: если любой из них пуст, развёртывание не стартует, а сообщение об ошибке называет ключ. У GraphApiBaseUrl и GraphApiVersion есть значения по умолчанию; это настройки установки, а пять обязательных ключей — учётные данные тенанта. Ссылка входа — https://ig.me/m/{Username}?ref=auth_{transactionId}. Она открывает переписку с вашим аккаунтом, Instagram* передаёт значение ref в Veriqa, и пользователь получает вопрос с кнопками подтверждения и отказа; итог приходит отдельным сообщением. Когда значение ref не дошло, у входа есть второй способ начаться. Страница входа показывает под кнопкой и QR-кодом Instagram* короткий код; пользователь отправляет его вашему аккаунту сообщением — одни цифры, с пробелами или без, — и вход начинается так же, как по ссылке. На код, по которому вход не нашёлся, — набранный с ошибкой, истёкший или уже использованный — ответ один на все причины: сверьте код на странице входа и отправьте его ещё раз либо откройте страницу входа заново. Код появляется тогда, когда он может понадобиться, а не вместе со страницей, и только пока ваш аккаунт не ответил. Где он появится, зависит от устройства, на котором открыта страница входа:
  • Компьютер или планшет показывает код через 8 секунд после загрузки — если только QR-код Instagram* на странице не hop-QR hop-режима. Тогда код ждёт перехода телефона в Instagram*, и страница входа показывает его под инструкцией «продолжите на телефоне» через 6 секунд после перехода.
  • Телефон сам код не открывает. Когда пользователь нажал кнопку Instagram* и вернулся на страницу, под строкой состояния появляется ссылка «Проблема со входом» — для канала, нажатого последним; ссылка открывает код. Перезагрузка страницы нажатие забывает.
  • Страница, которую телефон открывает по QR-коду hop-режима с несколькими каналами, оставляет выбор канала ему. Нажатие кнопки Instagram* переводит её на этот канал: заголовок и инструкция уступают место «Продолжите в Instagram*» со значком канала, кнопки каналов скрываются, а ссылка «Вернуться к выбору канала» под ним возвращает выбор, не трогая вход. По возвращении из приложения под строкой состояния появляется ссылка «Проблема со входом», и код за ней идёт с кнопкой «Скопировать и открыть Instagram*», как на странице запуска. Когда ваш аккаунт ответил или вход закончился, путь назад к выбору исчезает со страницы насовсем.
  • Страница запуска на телефоне в hop-режиме предлагает код за той же ссылкой через 6 секунд после того, как увела пользователя в приложение. Код там идёт с одной кнопкой — «Скопировать и открыть Instagram*»: она копирует код и открывает приложение. Когда код открыт, кнопка Instagram* над ним со страницы исчезает.
Браузер с выключенными скриптами показывает код с самого начала. Код исчезает, как только ваш аккаунт ответил. Когда пользователь уже в переписке и вопрос с кнопками отправлен, страница входа скрывает код и его ссылку, больше их не предлагает, а её строка состояния просит подтвердить вход в чате: «Вы перешли в Instagram*. Нажмите кнопку подтверждения в чате с @your_account, если хотите продолжить вход, или отмену». Вместе с ними со страницы исчезает выбор канала — QR-коды, кнопки и инструкция «продолжите на телефоне»: другой канал теперь привёл бы только к отказу. Заголовок, строка состояния, обратный отсчёт и «Отменить вход» остаются. То же происходит, когда пользователь возвращается на страницу, оставленную открытой на том же телефоне. Об ответе страница входа узнаёт по живому соединению; страница, перешедшая на опрос, код и выбор канала не скрывает. Страница запуска на телефоне узнаёт об ответе у сервера, пока открыта, и убирает ссылку и код насовсем; кнопка Instagram* на ней остаётся, если код не открывали. Целиком код выключается настройкой SpareStartCodeEnabled. На нажатую кнопку, которая не называет вход, — Icebreaker, нажатый без ссылки за ним, — канал отвечает подсказкой ровно об этом: отправьте код со страницы входа или отсканируйте QR-код ещё раз. Набранное сообщение, которое не код и не маркер входа, ответа не получает: человек, пишущий вашему аккаунту о другом, входа не просит. Чтобы выключить подсказку, добавьте в секцию канала "UnaddressedReplyEnabled": false: на такое нажатие ваш аккаунт не ответит ничего, а код продолжит работать. Ключ необязателен, значение по умолчанию — true. Оба ответа — обычные тексты канала: их формулировка меняется в locale-файлах. Вебхук регистрируется на стороне Meta*, как и у WhatsApp. В Meta*-приложении задайте callback URL https://auth.your-domain.com/api/channels/instagram/webhook, вставьте тот же WebhookVerifyToken и подпишитесь на поля messages, messaging_postbacks и messaging_referral. Meta* верифицирует URL запросом GET с hub.mode, hub.verify_token и hub.challenge; Veriqa отвечает на него автоматически, как только канал включён и хост публично доступен. Каждый последующий POST подписывается заголовком X-Hub-Signature-256 — HMAC-SHA256 тела запроса на секрете приложения, — и доставка без подписи или с неверной подписью отклоняется (Meta*: webhooks). Разрешения: instagram_business_basic и instagram_business_manage_messages (Meta*: send messages). Тенант со своим Meta*-приложением получает тот же адрес с именем тенанта последним сегментом: https://auth.your-domain.com/api/channels/instagram/webhook/{tenant}. Без сегмента доставка относится к тенанту по умолчанию; на доставку для тенанта, которому канал не разрешён, приходит ответ 403.
Доступ к пользователям вне вашей команды выдаёт Meta*. Настройте канал в Meta* сами или подключитесь через партнёра Meta* — например, через посредника UChat (прочие мессенджеры).
Что ограничивает платформа:
  • Окно 24 часа. Аккаунт может писать пользователю только в течение 24 часов после его последнего сообщения аккаунту (Meta*: send messages). Вход в него укладывается: каждое сообщение сценария отвечает пользователю, только что открывшему ссылку.
  • Реферал может не прийти, пока Meta*-приложение в режиме разработки. Пользователь открывает ссылку ig.me, а Instagram* ничего не доставляет на вебхук. Это ограничение платформы, а не адаптера. Вход тогда начинается кодом со страницы входа: пользователь отправляет его аккаунту сообщением.
  • Первое нажатие нового пользователя может прийти без значения ref. Пока пользователь ни разу не писал вашему аккаунту, открытие ссылки ig.me само ничего не доставляет: Instagram* сообщает о ссылке вместе с первым действием пользователя — нажатым Icebreaker или отправленным сообщением (Meta*: ссылки ig.me). Настройте Icebreakers аккаунта до того, как предлагать канал, чтобы новому пользователю было что нажать, — но и это первое нажатие может дойти до Veriqa без значения ref. Пользователь тогда получает подсказку (если вы её не выключили) и продолжает кодом со страницы входа либо сканирует QR-код ещё раз: переписка к этому моменту уже есть, и Instagram* сообщает о ссылке сразу. Ссылка работает только в мобильном приложении Instagram*.
  • Ссылка входа не срабатывает из открытой переписки с аккаунтом. Если у пользователя в приложении Instagram* уже открыта переписка с вашим аккаунтом, ссылка ig.me просто возвращает его в неё, а значение ref в Veriqa не приходит — вход не начинается. С любого другого экрана приложения ссылка работает. Пользователю достаточно отправить в эту переписку код со страницы входа либо выйти из неё и открыть ссылку ещё раз. От hop-режима и стиля перехода это не зависит. Наблюдалось на Instagram* для iPhone в октябре 2026; поведение принадлежит платформе и может измениться.
  • Одно событие на доставку. Когда Meta* кладёт в одну доставку вебхука несколько событий, Veriqa обрабатывает одно из них, а остальные пропускает: событие, называющее вход (открытая ссылка, нажатая кнопка), идёт раньше переданного номера телефона, а тот — раньше любого другого сообщения.
  • Текст вопроса обрезается до 640 символов — это лимит сообщения с кнопками (Meta*: button template).
  • Языка пользователя нет. Instagram* не сообщает адаптеру язык пользователя, поэтому сообщения идут на языке входа.
  • Номер телефона запрашивается кнопкой, которую Instagram* показывает только в мобильном приложении и только пользователю с номером в профиле, — см. номер телефона.

Messenger*

Пользователь подтверждает вход в Messenger* — в переписке с вашей страницей Facebook*. Канал работает на Messenger* Platform и обращается к graph.facebook.com по обычному HTTP — SDK платформы в пакете нет.
Вход на компьютере через Messenger*: в окне входа QR-код, камера телефона его сканирует, пользователь нажимает «Confirm» в чате Messenger*, бот отвечает «Sign-in confirmed».

Что видит пользователь: QR-код, камера телефона, одно касание в Messenger*. Интерфейс на английском.

Что нужно: страница Facebook*, Meta*-приложение из консоли Meta* for Developers с подключённой к нему страницей, а из консоли — секрет приложения, access-токен страницы, идентификатор страницы и её username.
appsettings.json
При "Enabled": true обязательны PageId, PageAccessToken, AppSecret, WebhookVerifyToken и InboundVerification (для Messenger* — signature), а если DeepLinkByPageId не включён, — ещё и PageName. Если любой из них пуст, развёртывание не стартует, а сообщение об ошибке называет ключ. У GraphApiBaseUrl и GraphApiVersion есть значения по умолчанию; это настройки установки, а PageId, PageName, PageAccessToken, AppSecret и WebhookVerifyToken — учётные данные тенанта. Ссылка входа — https://m.me/{PageName}?ref=auth_{transactionId}. Она открывает переписку с вашей страницей, Messenger* передаёт значение ref в Veriqa, и пользователь получает вопрос с кнопками подтверждения и отказа; итог приходит отдельным сообщением. В уже существующей переписке значение ref приходит событием реферала, в новой Messenger* сообщает его вместе с нажатием кнопки Get Started (Meta*: ссылки m.me) — и это первое нажатие может дойти до Veriqa без значения ref. Если ссылка открывает магазин приложений вместо переписки, добавьте в секцию канала "DeepLinkByPageId": true. Ссылка станет https://m.me/{PageId}?ref=auth_{transactionId}, а PageName больше не нужен. Ссылка по username — единственная форма, которую описывает Meta*, поэтому она остаётся значением по умолчанию; ссылка по идентификатору — для страницы, чья ссылка по username не открывает переписку в приложении Messenger* (наблюдалось на iPhone с установленным Messenger* в октябре 2026 года). Когда значение ref не дошло, у входа есть второй способ начаться. Страница входа показывает под кнопкой и QR-кодом Messenger* короткий код; пользователь отправляет его вашей странице сообщением — одни цифры, с пробелами или без, — и вход начинается так же, как по ссылке. На код, по которому вход не нашёлся, — набранный с ошибкой, истёкший или уже использованный — ответ один на все причины: сверьте код на странице входа и отправьте его ещё раз либо откройте страницу входа заново. Код появляется и исчезает на условиях, описанных для Instagram*: показывается, когда может понадобиться, и скрывается, как только ваша страница ответила. На iPhone путь в Messenger* может пройти через страницу браузера. В hop-режиме, как только замечен переход телефона в Messenger*, инструкция «продолжите на телефоне» на странице входа получает ещё одну строку: «На iPhone сначала может открыться страница браузера с двумя кнопками. Нажмите ту, что открывает Messenger*, затем подтвердите, что хотите открыть приложение Messenger*.» Операционную систему телефона страница входа не знает, поэтому строка написана для iPhone и показывается для любого телефона; она исчезает вместе с кнопкой «Выбрать другой способ» и как только ваша страница ответила. Страница запуска на телефоне показывает ту же строку под своей инструкцией, тоже на любом телефоне. Это подсказка канала: её текст и каналы, которые её получают, задаёт вид сообщения hop-channel-hint (см. строки канала). На нажатую кнопку, которая не называет вход, — Get Started, нажатый без ссылки за ним, — канал отвечает подсказкой ровно об этом: отправьте код со страницы входа или отсканируйте QR-код ещё раз. Набранное сообщение, которое не код и не маркер входа, ответа не получает: человек, пишущий вашей странице о другом, входа не просит. Чтобы выключить подсказку, добавьте в секцию канала "UnaddressedReplyEnabled": false: на такое нажатие ваша страница не ответит ничего, а код продолжит работать. Ключ необязателен, значение по умолчанию — true. Оба ответа — обычные тексты канала: их формулировка меняется в locale-файлах. Вебхук регистрируется на стороне Meta*, как и у WhatsApp. В Meta*-приложении задайте callback URL https://auth.your-domain.com/api/channels/messenger/webhook, вставьте тот же WebhookVerifyToken и подпишите страницу на поля messages, messaging_postbacks и messaging_referrals — два последних и доставляют ref ссылки m.me (Meta*: messaging_referrals). Meta* верифицирует URL запросом GET с hub.mode, hub.verify_token и hub.challenge; Veriqa отвечает на него автоматически, как только канал включён и хост публично доступен. Каждый последующий POST подписывается заголовком X-Hub-Signature-256 — HMAC-SHA256 тела запроса на секрете приложения, — и доставка без подписи или с неверной подписью отклоняется. Тенант со своим Meta*-приложением получает тот же адрес с именем тенанта последним сегментом: https://auth.your-domain.com/api/channels/messenger/webhook/{tenant}. Без сегмента доставка относится к тенанту по умолчанию; на доставку для тенанта, которому канал не разрешён, приходит ответ 403.
Доступ к пользователям вне вашей команды выдаёт Meta*. Настройте канал в Meta* сами или подключитесь через партнёра Meta* — например, через посредника UChat (прочие мессенджеры).
Что ограничивает платформа:
  • Реферал может не прийти, пока Meta*-приложение в режиме разработки. Пользователь открывает ссылку m.me, а Messenger* ничего не доставляет на вебхук. Это ограничение платформы, а не адаптера. Вход тогда начинается кодом со страницы входа: пользователь отправляет его странице сообщением.
  • Окно 24 часа. Страница отвечает пользователю в стандартном окне переписки — 24 часа после его последнего сообщения. Вход в него укладывается: каждое сообщение сценария отвечает пользователю, только что открывшему ссылку.
  • Профилю нужны свои разрешения. Имя и фото читаются при функции Business Asset User Profile Access, язык — при разрешении pages_user_locale. Без них вход всё равно завершается: пользователя определяет page-scoped ID, а в токене нет given_name, family_name, picture и locale.
  • Одно событие на доставку. Когда Meta* кладёт в одну доставку вебхука несколько событий, Veriqa обрабатывает одно из них, а остальные пропускает: событие, называющее вход (открытая ссылка, нажатая кнопка), идёт раньше переданного номера телефона, а тот — раньше любого другого сообщения.
  • Текст вопроса обрезается до 640 символов — это лимит сообщения с кнопками.
  • Язык сообщений — язык профиля Facebook* пользователя, если у приложения есть разрешение pages_user_locale, иначе язык входа: сам вебхук языка пользователя не несёт.
  • Номер телефона запрашивается кнопкой, которую Messenger* показывает только пользователю с номером в профиле, — см. номер телефона.

WeChat

Пользователь сканирует QR-код в WeChat и подтверждает вход в чате с вашим Official Account. Канал обращается к api.weixin.qq.com по обычному HTTP — SDK платформы в пакете нет. Что нужно: верифицированный Service Account WeChat — платформа верифицирует юридическое лицо, — а из его консоли AppID и AppSecret, плюс Token, который вы сами задаёте в настройке сервера аккаунта.
appsettings.json
При "Enabled": true обязательны первые три ключа, а с ними и InboundVerification — его значение для WeChat shared_secret: если любой из них пуст, развёртывание не стартует, а сообщение об ошибке называет ключ. ApiBaseUrl — настройка установки; остальные три — учётные данные тенанта. Ссылку здесь строить не из чего: на каждый вход Veriqa запрашивает у платформы временный QR-код со сценой auth_{transactionId}, и страница входа показывает именно его. Пользователь сканирует код в WeChat — тот, кто ещё не подписан на аккаунт, сначала подписывается — и получает вопрос с двумя вариантами под ним; нажатие варианта и есть ответ, а итог приходит отдельным сообщением. Код живёт 30 минут — это наибольший допустимый срок жизни транзакции, поэтому код не истекает раньше входа. Вебхук задаётся на стороне платформы. В настройке сервера аккаунта укажите URL https://auth.your-domain.com/api/channels/wechat/webhook, введите тот же Token и выберите режим сообщений без шифрования. Платформа проверяет URL запросом GET с signature, timestamp, nonce и echostr; Veriqa отвечает на него автоматически, как только канал включён и хост публично доступен. Каждый запрос — и эта проверка, и любой POST после неё — подписан SHA-1 над Token, меткой времени и nonce; запрос без подписи, с неверной подписью или подписанный более чем в пяти минутах от часов хоста отклоняется. Тенант со своим Official Account получает тот же адрес с именем тенанта последним сегментом: https://auth.your-domain.com/api/channels/wechat/webhook/{tenant}. Без сегмента запрос относится к тенанту по умолчанию; на запрос для тенанта, которому канал не разрешён, приходит ответ 403. Подпись проверяется Token этого тенанта, и у каждого аккаунта свой access-токен.
Внесите свои хосты в список разрешённых IP аккаунта. Платформа принимает вызовы API только с перечисленных там адресов. Вызов с любого другого адреса отклоняется, и QR-код входа создать не удаётся.
Что ограничивает платформа:
  • Окно сообщений. Аккаунт может отправить три сообщения в течение минуты после скана и пять в течение 48 часов после сообщения пользователя. Вход в него укладывается: вопрос идёт за сканом, итог — за нажатым вариантом. Сообщение вне окна платформа отклоняет, и повторно оно не уходит.
  • Только режим без шифрования. Доставка в шифрованном режиме не читается.
  • Медленный ответ повторяет вопрос. Платформа доставляет событие повторно, не получив ответа за пять секунд, и канал не отличает такую доставку от нового скана — пользователь может получить вопрос дважды. Ответить можно на любой из двух вопросов.
  • OpenID и больше ничего. Платформа не даёт Official Account ни имени, ни фото, ни языка пользователя: в токене только базовые claims, в name стоит OpenID, а сообщения идут на языке входа.
  • Номера телефона нет. У Official Account нет способа запросить номер телефона в чате, поэтому канал его не даёт — см. номер телефона.
  • Подтверждённый способ входа — скан. Кнопка канала открывает содержимое того же QR-кода. Передаёт ли мобильный браузер этот адрес приложению WeChat и что делает с кодом системная камера, не подтверждено — рассчитывайте на сканер самого WeChat.
  • Несколько хостов, один аккаунт. Access-токен берётся вызовом stable-token платформы, поэтому хосты одного аккаунта не отзывают токен друг у друга.
  • Имя wechat занято. HTTP-канал, зарегистрированный под этим именем, останавливает старт хоста — переименуйте его.

Viber

Пользователь подтверждает вход в Viber, в чате с вашим ботом. Канал обращается к chatapi.viber.com по обычному HTTP — SDK платформы в пакете нет.
На живой платформе не проверен. Адаптер проверен только на моке Viber Bot API; ни одного входа через настоящего бота Viber не сделано. Всё, что этот раздел говорит о платформе, взято из документации Viber REST Bot API — проверьте канал на своём боте, прежде чем на него полагаться.Бот — коммерческий продукт Viber. С 5 февраля 2024 года Viber выдаёт новых ботов только на коммерческих условиях. Получите бота и его токен у Viber до того, как планировать развёртывание.
Что нужно: бот Viber, а от Viber — его токен аутентификации и URI.
appsettings.json
При "Enabled": true обязательны AuthToken, BotUri и WebhookBaseUrl, а с ними и InboundVerification — его значение для Viber signature: если любой из них пуст, развёртывание не стартует, а сообщение об ошибке называет ключ. У SenderName и ApiBaseUrl есть значения по умолчанию. WebhookBaseUrl и ApiBaseUrl — настройки установки; AuthToken, BotUri и SenderName — учётные данные тенанта. Ссылка входа — viber://pa?chatURI={BotUri}&context=auth_{transactionId}. Она открывает чат с вашим ботом, Viber передаёт значение context в Veriqa, и пользователь получает вопрос с кнопками подтверждения и отказа; итог приходит отдельным сообщением. Вебхук собственного бота установки регистрирует Veriqa. Как только хост начал принимать запросы, он вызывает set_webhook с адресом {WebhookBaseUrl}/api/channels/viber/webhook и подписывается на событие conversation_started; сообщения пользователя доставляются вебхуку без подписки. Viber отвечает на этот вызов только после того, как отправил на адрес проверочный запрос и получил 200, поэтому к этому моменту хост должен быть публично доступен по HTTPS. Отклонённая регистрация пишется в лог предупреждением и хост не останавливает: остальные каналы продолжают работать, а Veriqa повторяет попытки в фоне, и пауза между ними растёт до пяти минут. Пока вебхук не зарегистрирован, проверка здоровья каналов показывает канал unhealthy. При остановке хост вебхук снимает. Каждая доставка несёт заголовок X-Viber-Content-Signature — HMAC-SHA256 тела запроса ключом — токеном бота, в шестнадцатеричной записи. Доставка без подписи или с неверной подписью отклоняется. Тенант со своим ботом получает тот же адрес с именем тенанта последним сегментом: https://auth.your-domain.com/api/channels/viber/webhook/{tenant}. Veriqa регистрирует вебхук только собственного бота установки. Вебхук бота тенанта регистрирует тот, кто заводит тенанта: вызов set_webhook с токеном этого бота, адресом с сегментом {tenant} и типом события conversation_started (Viber: setting a webhook). Без сегмента доставка относится к тенанту по умолчанию; на доставку для тенанта, которому канал не разрешён, приходит ответ 403. Подпись проверяется токеном, который разрешается для этого тенанта, — его собственным, а если своего нет — токеном установки. Что ограничивает платформа:
  • Одно сообщение до ответа пользователя. После открытия чата бот может отправить одно сообщение; следующее пройдёт только после того, как пользователь написал боту. Вход в это укладывается: вопрос и есть это одно сообщение, а нажатие кнопки подтверждения или отказа — ответ пользователя.
  • Нажатие видно в чате. Кнопка клавиатуры Viber отправляет своё значение сообщением пользователя, поэтому в переписке появляется строка, начинающаяся с vq_confirm_ или vq_decline_.
  • Отправленное сообщение изменить нельзя. Итог всегда приходит новым сообщением; оно же убирает кнопки вопроса.
  • Профиль — то, что несёт событие: имя, фото и язык пользователя. Сообщения идут на этом языке; если его нет — на языке входа.
  • Номер телефона запрашивается кнопкой share-phone, и Viber не доказывает, что номер принадлежит пользователю, — см. номер телефона.
  • Опроса нет. Bot API доставляет события только вебхуком, поэтому канал не работает на хосте, недоступном из интернета.
  • Имя viber занято. HTTP-канал, зарегистрированный под этим именем, останавливает старт хоста — переименуйте его.

Email

Email — единственный канал с двумя независимыми направлениями, и они могут работать вместе:
  • Pull (magic link) — Veriqa отправляет письмо со ссылкой, пользователь переходит по ней. Включено по умолчанию (PullEnabled). Вместо ссылки письмо может нести код, который вводится на странице, или и то и другое — см. Ссылка, код или оба.
  • Push — письмо в один тап (one-tap email) — пользователь отправляет готовое письмо на входящий адрес (один тап с кнопки или по QR-коду), Veriqa его читает. Выключено по умолчанию (PushEnabled); требует входящей доставки и политики верификации отправителя. Push — значение в конфигурации; «письмо в один тап» — как режим называется для пользователей.
appsettings.json
PublicBaseUrl обязателен всегда, когда канал включён — из него строятся magic-link и QR-код. TokenTtl — срок жизни magic-link, кода письма входа и токенов добора claims; токен письма входа Push живёт иначе — до истечения своей транзакции. MailResendInterval — наименьшее время между двумя письмами одного входа, см. Повторная отправка письма. Port: 587 с UseSsl: false означает STARTTLS; UseSsl: true означает неявный TLS на порту 465. RequireStartTls (по умолчанию true) действует, когда UseSsl равен false и заданы Username и Password: если сервер не предлагает STARTTLS, соединение отвергается — пароль никогда не уходит открытым текстом. Ставьте false только для внутреннего релея, к которому вы сознательно ходите без TLS: тогда STARTTLS применяется, лишь если сервер его предложил. На анонимный релей (без учётных данных) настройка не влияет. Username и Password задаются только вместе. Обе настройки пустые — допустимая конфигурация: это релей без аутентификации, типовой вариант для внутреннего SMTP в контуре компании. А вот заданное ровно одно из двух приложение отвергает на старте: аутентификация в таком случае не выполнялась бы вовсе, то есть указанное значение молча никогда не применялось бы. Если Veriqa не стартует с сообщением про Username и Password — удалите лишнее из двух значений либо задайте оба.

Какой режим выбрать

Magic link включён по умолчанию и не требует ничего, кроме исходящей почты, — это более дешёвый старт. Письму в один тап нужны способ принимать почту и политика отправителя; отдельный провайдер входящей почты для него не обязателен: Veriqa умеет читать обычный ящик сама, см. Письмо в один тап через IMAP. Оно даёт четыре вещи, которых magic link дать не может:
  • Пользователю ничего не нужно доставлять. Письмо идёт в обратную сторону, поэтому вход больше не зависит от того, дойдёт ли ваше исходящее письмо: ни папки «Спам», ни greylisting, ни репутации домена. При PullEnabled: false каналу вообще не нужен SMTP — валидатор настроек требует блок исходящей почты только при включённом Pull.
  • Нет ссылки, которую израсходует почтовый шлюз. Корпоративная почтовая защита открывает ссылки во входящих письмах для проверки, и одноразовый magic link может быть израсходован до того, как по нему перейдёт человек. В письме, которое отправляет сам пользователь, такой ссылки нет.
  • Доказывается владение ящиком, а не факт получения письма. Переход по ссылке показывает, что письмо до кого-то дошло, — в том числе через правило пересылки или общий ящик. Отправка письма показывает, что отправитель управляет ящиком, и отправитель проверяется политикой VerificationPolicy (по умолчанию DmarcAlignedPass).
  • Это то же действие, что и в мессенджерах. Пользователь отправляет готовое сообщение в один тап — секретное сообщение. Email — тот же приём, только письмом вместо сообщения в чате: страница входа учит одной привычке, а не двум.
Режимы независимы и могут работать вместе: PreferredMode решает, какой из них страница входа предлагает первым, а при первом Push на странице входа, пока включён Pull, остаётся поле адреса — запасной путь через magic link.

Режимы для одного тенанта или приложения

PullEnabled и PushEnabled задают режимы, которые обслуживает установка. Тенант и приложение выбирают из них членами Channels:Email:SignInModes и Channels:Email:PreferredMode своей записи — см. Режимы входа по Email для одного приложения. Вход и подтверждение предлагают режимы, оставшиеся после этого выбора. Где эта страница описывает, что показывает вход при включённом Pull или Push, имеется в виду, что режим есть среди них.
  • Выбор только сужает. Запись не включает режим, выключенный в секции. Пустой список или список, в котором нет ни одного режима, обслуживаемого установкой, пропускается с предупреждением в журнале, и действует уровень выше.
  • Добор claims зависит от секции. Письма с кодом и ссылкой, которыми подтверждается недостающий адрес, уходят, пока Pull включён в секции, — даже у приложения, которое предлагает только Push.
  • Список не выключает Email. Для этого служит Enabled секции, а клиент сужает каналы своих входов параметром acr_values — см. Как дать клиенту выбрать канал.

Ссылка, код или оба

PullMethods задаёт, что несёт письмо входа: magic link (MagicLink, по умолчанию), код, который пользователь вводит на той же странице, где ввёл адрес (Code), или то и другое в одном письме. Секция задаёт значение для установки; тенант и приложение задают своё членом Channels:Email:PullMethods своей записи. Значение приложения заменяет значение тенанта, а значение тенанта — значение секции. Порядок значений в списке ничего не меняет. Настройка действует только там, где предлагается Pull.
appsettings.json
Пользователь между ссылкой и кодом не выбирает: в форме одно поле адреса и одна кнопка. Список, в котором нет ни одного из двух значений, пропускается, и действует уровень выше — на уровне установки ["MagicLink"]. О пустом списке в записи тенанта или приложения Veriqa пишет предупреждение в журнал. Код состоит из шести цифр. Он действует до времени, указанного в письме: TokenTtl после отправки письма, но не дольше самого входа или подтверждения. На ввод даётся SignInCodeAttempts попыток, по умолчанию 5. Тенант и приложение могут уменьшить это число членом Channels:Email:SignInCodeAttempts своей записи; большее значение лимит уровня выше не поднимает. Эта настройка не зависит от ClaimCompletionEmailLimits:CodeAttempts, поэтому лимит добора claims на вход не влияет. Истёкший код и код без оставшихся попыток не действуют — пользователь запрашивает новое письмо. Каждое новое письмо несёт новый код, и код прежнего письма перестаёт действовать, как только новое ушло. Письмо с кодом и ссылкой. Пользователь вводит код или переходит по ссылке, и засчитывается то, что сделано первым. Что видит пользователь. Когда письмо ушло, на месте поля адреса и кнопки появляются строка «Код отправлен на u***@example.com», поле кода и кнопка «Подтвердить». На неверный код страница отвечает «Неверный код. Осталось попыток: 4». «Отправить снова» возвращает поле адреса с тем же адресом, и следующее письмо уходит, когда пройдёт MailResendInterval, см. Повторная отправка письма. Верный код делает то же, что ссылка того же письма:
  • при входе страница продолжает так же, как после ссылки. Там, где вопрос задаёт окно входа, — по умолчанию у Email, см. Страница ссылки из письма, — окно его задаёт; при LoginConfirmation.Mode, равном None, вход завершается. Форма добора claims, которая показывается на устройстве, подтвердившем вход (ClaimCompletionFormSurface: CrossDevicePage), открывается в браузере, где введён код;
  • при подтверждении браузер, где введён код, переходит на страницу, где показано, что именно подтверждается; там пользователь и отвечает.
В hop-режиме код спрашивает сама страница телефона с формой адреса, и пользователь вводит его на телефоне. Отдельная форма /auth/email/start спрашивает код так же: после верного кода она открывает страницу, которую назвал ответ, или показывает строку, которую при том же исходе показывает страница ссылки из письма. В письме с одним кодом нет ссылки, которую корпоративная защита почты может израсходовать, открыв её. В браузере с выключенным JavaScript форма письмо отправляет, но поля кода страница не показывает. Если у ваших пользователей могут быть выключены скрипты, оставьте в письме ссылку: ["MagicLink", "Code"]. Своя страница входа. Ответ POST /auth/email/start несёт code_expected — true, когда в письме есть код. Тогда страница отправляет код в формате JSON на POST /auth/email/code — { "session_id": "…", "code": "123456" }. Лимит запросов старта действует и на этот эндпоинт. На неизвестный session_id эндпоинт отвечает 400, как и старт.

Режим Push — письмо в один тап

Push дополнительно требует блок Inbound. Входящая почта попадает в Veriqa одним из двух способов: провайдер входящей почты отправляет её на вебхук (ниже) либо Veriqa сама читает ящик — Письмо в один тап через IMAP.
appsettings.json
Входящая почта отправляется на POST https://auth.your-domain.com/api/channels/email/inbound с заголовком аутентификации X-Email-Webhook-Secret. Эндпоинт принимает один плоский JSON-объект в собственном формате Veriqa — не родной payload почтового сервиса:
Поэтому сервису входящей почты, который отправляет письма в своём формате (Mailgun, Postmark, SendGrid Inbound Parse, …), нужен небольшой пересыльщик перед эндпоинтом — Cloudflare Email Worker или собственная функция, — который приводит каждое письмо к этому объекту. Чтобы разбирать родной формат внутри хоста, укажите Provider = Custom и зарегистрируйте собственный IEmailInboundProcessor. В мультитенантной установке тот же маршрут принимает и необязательный тенант-сегмент — POST https://auth.your-domain.com/api/channels/email/inbound/{tenant}, — и каждый тенант прописывает свой сегмент в настройках своего входящего провайдера. Письмо, пришедшее туда, обрабатывается настройками Inbound и webhook-секретом этого тенанта. Без сегмента маршрут использует настройки установки целиком. UsePlusAddressing встраивает correlation-токен в адрес для ответа (login+{token}@…), чем входящее письмо и привязывается обратно к своей транзакции входа. VerificationPolicy решает, насколько доверять отправителю: From в письме легко подделать, поэтому от этой настройки зависит безопасность входа:
Не отключайте верификацию отправителя в продакшне. Без неё любой, кто может подделать заголовок From, способен завершить чужой вход.

Что видит пользователь после нажатия

Вход на компьютере по почте: QR-код, камера телефона, пользователь отправляет готовое письмо, страница проверяет отправителя, пользователь подтверждает вход на компьютере.

Что видит пользователь: QR-код, готовое письмо, страница проверяет отправителя, и пользователь подтверждает вход на компьютере.

Без hop-режима QR-код и кнопка «Отправить письмо-подтверждение» страницы входа несут само письмо — ссылку mailto: с заполненными получателем, темой и текстом. Никакая страница Veriqa между ними не открывается: телефон, отсканировавший код, или компьютер, на котором нажали кнопку, открывает почтовый клиент с готовым письмом.
  • По нажатию своей кнопки страница входа сама показывает строку «Письмо-подтверждение открыто в почтовом приложении. Отправьте его, чтобы продолжить.». Когда пользователь возвращается на страницу из почтового приложения, а эта строка ещё на ней, строка меняется на «Если вы уже отправили письмо, ожидайте подтверждения — обычно это занимает несколько секунд.». Перезагрузка нажатие забывает.
  • Письмо, открытое по QR-коду, странице входа ничего не сообщает, пока не придёт; дальше страница показывает, что письмо получено и чем закончился вход.
  • Отправитель, прошедший проверку, — ещё не вход: если вход уже занят учётной записью другого канала, письмо в учётную запись не входит, и вместо «Отправитель подтверждён» страница говорит «Вход уже начат в другом канале.» («Подтверждение уже начато в другом канале.» — на странице подтверждения).
  • Там, где спрашивает окно входа (для Email это поведение по умолчанию, см. «Страница ссылки из письма» ниже), письмо само в учётную запись не входит: оно доказывает владение ящиком, и страница входа переходит к тому же вопросу, который пришёл бы в чат мессенджера, — Confirm sign-in to "{app}" — request at {requested_at} from {browser} on {os}, {region} с подставленными значениями. «Да» входит в учётную запись; «Нет» отклоняет вход, и приложение получает access_denied. При LoginConfirmation.Mode = None письмо завершает вход само; чтобы убрать вопрос только у Email, задайте Veriqa:LoginConfirmation:ModeByChannel:email = None.
Inbound:TokenInLocalPart выбирает, в какой форме записан адрес получателя: Тема и текст — это формулировка deeplink-prefill для канала email. Если токен передаётся в тексте, тема письма входа — Sign in to {app}: {token}, а письма подтверждения — Confirm in {app}: {token}; без имени приложения тема — Sign in: {token} или Confirm: {token}. Формулировки можно менять как угодно: Veriqa находит токен по его форме, а не по словам вокруг. Оставьте {token} в тексте, если токена нет в адресе. QR-код несёт письмо целиком, поэтому самый маленький код получается с TokenInLocalPart. Если письмо собрать не удалось, причина пишется в журнал. Так бывает, когда на InboundAddress письмо нельзя адресовать (адрес не задан вне Production либо в нём нет домена при включённом TokenInLocalPart) или когда отказало хранилище токенов. Канал при этом сохраняет то, что осталось: при PullEnabled страница входа показывает поле адреса без кнопки почтового клиента и без QR-кода; без него канал Email не предлагается. Письмо, которое не помещается в QR-код (длинный текст заполненного письма), оставляет канал с кнопкой и без QR-кода.

Email в hop-режиме

В hop-режиме QR-код канала Email несёт hop-ссылку вместо письма, и телефон по-прежнему попадает в само письмо. Как он туда попадает, решает RedirectStyle, как у любого канала; вход по ссылке из письма (PullEnabled) меняет только страницу при Interstitial: Обе страницы открывают письмо сами, один раз на вкладку браузера, и оставляют кнопку на случай, если оно не открылось. На странице с включённым входом по ссылке под кнопкой стоит ссылка «Войти по ссылке на почту» («Подтвердить по ссылке на почту» — при подтверждении): она открывает форму адреса. Подпись этой ссылки и кнопка формы зависят от того, что несёт письмо входа. Как только письмо открылось — само или по нажатию кнопки, — страница говорит «Письмо-подтверждение открыто в почтовом приложении. Отправьте его, чтобы продолжить.», а по завершении входа показывает итог. Пользователь, вернувшийся на страницу из почтового приложения или кнопкой «Назад», видит вместо этой строки «Если вы уже отправили письмо, ожидайте подтверждения — обычно это занимает несколько секунд.», и письмо второй раз не открывается. При Direct строку «письмо открыто в почтовом приложении» окно входа получает от самого перенаправления. Там, где вопрос задаёт окно входа, — по умолчанию у Email, см. Страница ссылки из письма, — письмо привязывает ящик ко входу, а вопрос ждёт в окне входа. Тогда обе страницы телефона говорят «Вернитесь к окну входа и подтвердите вход там.»: страница с кнопкой письма убирает поле адреса и кнопку письма и оставляет обратный отсчёт; страница запуска убирает инструкцию, кнопку и запасной код и продолжает показывать, чем закончился вход. Следующие статусы письма эту строку больше не заменяют. Так же ведут себя страницы телефона любого другого канала, когда LoginConfirmation.Mode этого канала равен OnWebPage. Если в это время отсканировать код Email ещё раз, страница с кнопкой письма откроется, но в почтовое приложение сама не перейдёт. При OnWebPage чат тоже не молчит: как только отправитель привязан ко входу, канал, который отправляет сообщения в чат, один раз отвечает «Вход начат — подтвердите его на странице входа» на языке получателя, чтобы пользователь знал, что смотреть надо в окно входа. При подтверждении, на которое отвечают на странице подтверждения, канал отправляет то же сообщение в формулировке подтверждения: «Подтверждение начато — подтвердите его на странице подтверждения». Сообщение уходит один раз на транзакцию — повторный старт по той же ссылке ничего больше не присылает. Email такого письма не отправляет. Текст — вид сообщения web-confirmation-notice, формулируется как любое другое сообщение, в том числе по каналам, — см. Veriqa:MessageTemplates. Когда пользователь отвечает на странице, в тот же чат новым сообщением приходит квитанция исхода — о подтверждении на «Да», об отказе на «Нет» — без значений вызывающей стороны: вопрос в чате не задавался. «Да» на вход, которое ведёт в добор claims, получает квитанцию, когда добор закончится. Квитанция, которую канал не принял, пишется в лог и не повторяется; ответ приложению не меняется. Страница входа на компьютере следует за телефоном: скан QR-кода Email показывает «QR-код отсканирован. Продолжите на телефоне, чтобы подтвердить по почте.», а начало письма — по нажатию, по автозапуску страницы запуска либо, где страницы нет, от самого перенаправления — «Письмо-подтверждение открыто в почтовом приложении. Отправьте его, чтобы продолжить.»

Страница ссылки из письма

Ссылка письма входа (PullEnabled) открывает страницу Veriqa, и что она делает, зависит от того, где подтверждается вход, — режим Veriqa:LoginConfirmation у канала Email:
  • Спрашивает окно входа — умолчание для Email. Страница ни о чём не спрашивает. Под заголовком «Запрос входа» она называет приложение — «Запрошен вход в {app}. Если это не вы — закройте страницу.» — и предлагает «Продолжить вход» и «Отмена». «Продолжить вход» передаёт вход окну входа: расходует ссылку и привязывает ящик ко входу, не завершая его, — и страница сменяется строкой «Вернитесь к окну входа и подтвердите вход там.» с кнопкой «Закрыть». Единственный вопрос входа — подтвердить или отклонить — задаётся один раз, в окне входа, где вход начат: «Да» входит в учётную запись, и данные профиля, которых приложению не хватает, добираются там же; «Нет» отклоняет вход, и приложение получает access_denied. Повторно открытая та же ссылка сообщает, что недействительна или устарела.
  • Окно входа не спрашивает (None). Ссылка завершает вход при открытии, и страница показывает, чем он закончился. Почтовый шлюз, проверивший ссылку, завершает вход того, кто его начал, поэтому этот режим включают только в исключительных случаях — в тестовых окружениях и приложениях с низким риском, см. Veriqa:LoginConfirmation.
Браузеру, участвовавшему во входе, нажимать кнопку не нужно. Когда вход хранит отпечаток и IP-адрес телефона, отсканировавшего его hop-QR, — hop-режим с включённым HopMode.CollectFingerprint и включённым HopMode.CollectIpAddress (по умолчанию), — страница вычисляет отпечаток браузера, в котором открыта, и при совпадении обоих значений продолжает сама: пользователь видит «Вернитесь к окну входа…» без нажатия. Любое несовпадение, браузер, не сумевший вычислить отпечаток, или вход без этих значений оставляют на странице кнопку. Присланный страницей отпечаток сравнивается и отбрасывается: он не сохраняется и в журнал не пишется. «Отмена» и «Закрыть» только закрывают вкладку и ничего не меняют; если браузер оставляет вкладку, открытую не скриптом, страница вместо этого пишет «Эту вкладку можно закрыть.». Когда спрашивает окно входа, открытие страницы ссылку не расходует: почтовый шлюз, прошедший по ней, ничего дальше не передаёт — передаёт только POST кнопки. При None вход завершает само открытие. Ссылка подтверждения открывает ту же страницу с формулировками подтверждения: под заголовком «Требуется подтверждение» она пишет «Запрошено подтверждение. Если это не вы — закройте страницу.» и предлагает «Продолжить подтверждение» и «Отмена». В отличие от страницы входа, приложение здесь не названо. Чтобы страница называла ваше приложение, задайте для него свою формулировку этой строки в AuthPage:Texts. Браузеру, участвовавшему в подтверждении, кнопку тоже нажимать не нужно: страница проверяет его так же, как при входе. «Продолжить подтверждение» ведёт на страницу, где показано, что именно подтверждается; там пользователь и отвечает.

Повторная отправка письма

После отправки ссылки поле адреса на странице входа остаётся редактируемым, а кнопка становится «Отправить снова». Она удерживается на MailResendInterval — по умолчанию 30 секунд — и возвращается сама; запрос, пришедший раньше, отклоняется с 429, письмо не уходит. Письмо с кодом отправляется снова так же: «Отправить снова» под полем кода возвращает поле адреса, и его кнопка удерживается на тот же интервал.
appsettings.json
  • Интервал считается на вход, а не на адрес: исправить адрес и нажать кнопку в пределах интервала — тот же отказ.
  • Письмо входа и письма добора claims считаются раздельно: вход по ссылке из письма первое письмо добора не задерживает.
  • 00:00:00 выключает интервал; отрицательное значение останавливает старт. Настройка задаётся только в конфигурации хоста: тенант и запись клиента её не переопределяют.
  • Письма входа ограничены ещё и по адресу и по домену за час, по всем входам тенанта: SignInMailsPerAddress (по умолчанию 5) и SignInMailsPerDomain (по умолчанию 0, лимит выключен; включите его сами). Сверх любого из лимитов запрос отклоняется с 429, письмо не уходит. Письма добора claims считаются отдельно. См. справочник конфигурации.
  • Интервал, лимиты по адресу и домену, лимит запросов и лимиты писем добора (ClaimCompletionEmailLimits) действуют независимо друг от друга.
  • Письмо, которое не удалось отправить, всё равно запускает интервал и засчитывается в лимиты по адресу и домену — следующая попытка ждёт.
Ответ POST /auth/email/start несёт retryAfterSeconds — сколько ждать до следующего письма — и при успехе, и в отказе 429 по интервалу, который также ставит заголовок Retry-After. Отказ 429 по лимиту адреса или домена не несёт ни того, ни другого: кнопка страницы остаётся доступной, и можно ввести другой адрес. Собственная страница входа может удерживать кнопку по этому числу. При успехе ответ несёт ещё и code_expected, см. Ссылка, код или оба.

Письмо в один тап через IMAP

При Inbound:Provider = ImapPolling Veriqa читает почтовый ящик сама: не нужны ни входящий провайдер, ни секрет вебхука, ни публичный адрес вашего сервера — достаточно ящика и пароля к нему. Фоновый сервис входит в ящик по IMAP, берёт непрочитанные письма и передаёт каждое в ту же обработку, что и письмо, пришедшее вебхуком, — проверка отправителя и итог входа одинаковы.
appsettings.json
Ключи секции Veriqa:Channels:Email:Inbound:Imap: InboundAddress с этим провайдером обязателен в любом окружении, а не только в Production: это адрес, на который пользователь отправляет письмо, то есть адрес этого ящика. При UsePlusAddressing письмо уходит на login+{token}@… — проверьте, что ваш почтовый провайдер доставляет письма с плюс-адресом в основной ящик. Как это работает.
  • Письмо срабатывает не позже чем через PollIntervalSeconds плюс время одного обращения к ящику после того, как пришло: завершает вход либо, где спрашивает окно входа, привязывает к нему ящик.
  • Берутся только непрочитанные письма, пришедшие не раньше чем TokenTtl назад: более старое письмо не читается и не помечается. Обработанное письмо — принятое или отклонённое — помечается прочитанным. Письма никогда не удаляются.
  • Соединение — только по TLS, сертификат сервера проверяется всегда; отключить проверку нельзя.
  • Отказ ящика или сервера авторизации — сеть, неверный пароль, отказ в токене — не останавливает приложение и другие каналы. Ошибка пишется в лог без секретов, обращение повторяется через 1 секунду, затем через 2, 4 и так далее до 60 секунд; первое успешное обращение сбрасывает паузу.
  • Маршрут вебхука /api/channels/email/inbound с этим провайдером отвечает 404.
  • В мультитенантной установке каждого тенанта с этим провайдером читает свой цикл со своими настройками ящика.
Откуда взять AuthservId. SPF, DKIM и DMARC проверяет почтовый сервер ящика и записывает результаты в заголовок письма Authentication-Results (RFC 8601). Отправитель может вписать в письмо поддельный заголовок с тем же именем, поэтому Veriqa доверяет только заголовку, первое слово которого — authserv-id — равно AuthservId, а из нескольких таких — верхнему. Если в письме нет заголовка с таким идентификатором, результаты пусты, и политика письмо отклоняет. Политика AllowListOnly заголовок не читает, ключ ей не нужен. Чтобы узнать значение, откройте исходник любого письма, полученного этим ящиком («Показать оригинал» или похожая команда почтового клиента), и посмотрите на верхний заголовок Authentication-Results:
  • Authentication-Results: mx.your-provider.com; spf=pass …; dkim=pass …; dmarc=pass … — значение начинается с имени хоста, за которым стоит ;. Это имя и есть AuthservId.
  • Authentication-Results: spf=pass …; dkim=pass …; dmarc=pass … — значение начинается с результата (слова с =), то есть сервер authserv-id не указывает. Записать в AuthservId нечего: spf=pass туда не копируйте.
Сравните исходники нескольких писем: значение в AuthservId одно. Ящик, у которого идентификатор отсутствует или различается от письма к письму, для этого режима непригоден — подключите его через вебхук или возьмите ящик другого провайдера.
Ящик, сервер которого пишет заголовок без authserv-id, с политиками DmarcAlignedPass и SpfOrDkimPass использовать нельзя. Отличить заголовок такого сервера от вписанного отправителем Veriqa не может, поэтому заголовок без идентификатора доверенным не считается никогда. Не вписывайте в AuthservId значение, которого сервер ящика сам не ставит. Тогда письмо, в котором нет заголовка с этим значением, отклоняется и помечается прочитанным, и честные входы не завершаются. А отправитель, вписавший в письмо заголовок с этим значением, получает доверие: проверка отправителя проходит по результатам, которые он написал сам. Такую форму заголовка Microsoft документирует для Microsoft 365 — см. Authentication-results message header; проверьте письмо своего ящика, как описано выше. Для такого ящика либо принимайте письма через вебхук почтового провайдера (Inbound:Provider: Webhook), либо читайте ящик другого провайдера. С AllowListOnly такой ящик работает, но эта политика сверяет только домен из From, который отправитель может подделать, — проверку SPF, DKIM и DMARC она не заменяет.
Выделите ящик — или хотя бы папку — под Veriqa. Любое непрочитанное письмо папки Folder, достаточно свежее, чтобы нести живой токен, будет помечено прочитанным, кто бы его ни отправил. Не направляйте сервис на ящик, который читают люди.
Ограничения:
  • VerificationPolicy: ProviderVerified с ImapPolling несовместима — у ящика нет отправителя, проверенного провайдером; с такой парой хост не стартует.
  • Расхождение ImapPolling и значения InboundVerification, отличного от outbound_fetch, даёт Warning при старте — как у мессенджера в режиме Polling.

Вход в ящик по OAuth

Некоторые ящики пароль не принимают вовсе — Microsoft 365 и организации Google Workspace, отключившие парольный вход. OAuth меняет только способ входа Veriqa в ящик: отправителя письма по-прежнему проверяет VerificationPolicy, поэтому сначала убедитесь, что ящик проходит проверку AuthservId, описанную выше. Для таких ящиков задайте AuthMode = OAuth2 и заполните секцию Veriqa:Channels:Email:Inbound:Imap:OAuth. В ней лежит не токен доступа — он живёт около часа, — а долгоживущие данные для его получения: Veriqa сама запрашивает токен у TokenEndpoint, держит его в памяти и запрашивает новый, когда срок вышел. Password в этом режиме игнорируется, а секция OAuth игнорируется при AuthMode: Password. Вход в ящик выполняется под Username механизмом OAUTHBEARER, если сервер его предлагает, иначе XOAUTH2. Какой из двух стандартных способов получения токена (RFC 6749) применяется, определяет RefreshToken:
  • По refresh token — ящик конкретного пользователя, который один раз выдал согласие. Выбирайте, когда ящик — обычная учётная запись и провайдер выдаёт для неё refresh token.
  • По учётным данным приложения (client_credentials) — приложение читает ящик без пользователя. Выбирайте, когда администратор организации может выдать приложению доступ к ящику; refresh token при этом нет, и обновлять нечего.
По refresh token
По учётным данным приложения
Адреса и права в примерах — заглушки. Регистрацию приложения, нужные ему права и действительные значения описывает почтовый провайдер — берите их из его документации, они меняются: Ограничения входа по OAuth:
  • Согласие выдаётся вне Veriqa. Экрана согласия и адреса возврата у Veriqa для этого нет: администратор получает refresh token по инструкции почтового провайдера и кладёт его в секреты.
  • Обновлённый refresh token не записывается обратно. Сервер авторизации может вернуть новый refresh token вместе с токеном доступа; Veriqa пользуется им до остановки процесса и в конфигурацию не записывает. У провайдера, где refresh token имеет срок жизни, администратор заменяет значение в секретах сам.
  • Сервисный аккаунт Google не поддерживается — вход подписанным JWT (RFC 7523) не реализован.

Провайдеры

Поставляемые провайдеры — Smtp для исходящих, Webhook и ImapPolling для входящих. Обе настройки также принимают Custom, в этом случае вы регистрируете свой IEmailOutboundSender / IEmailInboundProcessor в DI до вызова AddEmail(). Любое другое значение сразу останавливает старт с ошибкой, а не молча бездействует. Свой IEmailOutboundSender отправляет только письмо входа, если он не отвечает SupportsClaimCompletionEmail значением true и не реализует SendClaimCompletionEmailAsync: эти два члена отправляют письма с кодом и со ссылкой, подтверждающие адрес почты при доборе claims. Без них способ «Код на почту» («Ссылка на почту», если в списке только MagicLink) — тот, что стоит за Code и MagicLink, — недоступен, и веб-шаг предлагает только оставшиеся.
Оговорка про несколько инстансов. Токены magic-link Email и Push-correlation токены держатся в памяти поставляемыми хранилищами. На нескольких инстансах ссылка, выданная одним инстансом, неизвестна остальным. Запускайте Email на одном инстансе, маршрутизируйте sticky-сессиями или зарегистрируйте распределённые реализации IEmailActionTokenStore и IEmailPushCorrelationStore. Остальных каналов это не касается.Своя реализация IEmailPushCorrelationStore должна переопределить StoreOrReuseAsync — идемпотентную регистрацию токена («у транзакции уже есть живой токен — верни его и ничего не пиши»). Реализация по умолчанию в интерфейсе просто пишет переданный токен, поэтому без переопределения режим Push выпускает новый correlation-токен на каждый рендер страницы входа, и все они живут до TTL или погашения. Захват индекса «транзакция → живой токен» обязан быть атомарным (compare-and-swap / SET NX / транзакция), а TTL переиспользованного токена — не продлеваться.

Своё тело письма

Письмо входа — обычное сообщение механизма текстов: и тема, и HTML-документ тела целиком задаются значением ключа Veriqa:MessageTemplates:sign-in-mail (устройство ключа — в Справочнике конфигурации). Поэтому переписать письмо можно настройкой, не трогая код: задайте свою лестницу вариантов на нужном уровне. Письмо подтверждения — то же сообщение, его формулировка задаётся на Veriqa:MessageTemplates:sign-in-mail:ByType:confirmation со своим контрактом: поставляемый текст начинается со слов «Требуется подтверждение» и, как письмо входа, называет приложение. Лестница, заданная на самом sign-in-mail в Veriqa:MessageTemplates, меняет только письмо входа, а в записи приложения — оба письма этого приложения. Своё письмо подтверждения задайте лестницей на ByType:confirmation на том же уровне. Письмо с кодом — отдельный вид сообщения, и задаётся он так же: sign-in-code-mail — письмо с одним кодом, sign-in-code-link-mail — с кодом и ссылкой (см. Ссылка, код или оба). У каждого своя формулировка подтверждения на ByType:confirmation, и ни в одном нет QR-кода. Слот {code} гарантирован в обоих, {link} — только в sign-in-code-link-mail. Лестница, заданная для sign-in-mail, эти письма не меняет.
appsettings.json
Что здесь важно знать:
  • разметку в тексте варианта продукт не экранирует — её пишет владелец конфигурации. Экранируются значения слотов: они приходят снаружи, в том числе от приложения по API;
  • видимые фразы остаются ключами локализации. {button}, {qr_instruction}, {qr_alt} и прочие подобные — слоты локализованной строки: контракт сообщения указывает, на какой ключ смотрит слот, а подставится перевод на язык получателя. Разметка при этом одна на все языки, и переводить её копиями не нужно. В поставляемом письме вне таких слотов нет ни одной фразы — {heading}, {text_intro}, {request_from_label}, {button_hint}, {valid_until_label} и остальные; пример из двух вариантов выше пишет заголовок и строку «Request from» прямо в разметку, и они остаются на том языке, на котором вы их написали;
  • то, что Veriqa вычисляет сама, не укорачивается; то, что приходит извне, — укорачивается. {link}, {valid_until} и прочие значения, которые продукт вычисляет сам, подставляются полностью. Имя приложения, детали инициатора и переведённая фраза ограничены 128 символами — держите фразу одного слота короткой, а длинное предложение раскладывайте на несколько слотов;
  • форму QR-кода решает текст, а не настройка. Вариант, сославшийся на {qr_cid}, получает PNG-вложение; вариант, сославшийся на {qr_url} (ссылку на QR-эндпоинт, если её кладёт ваш композер), получает картинку по ссылке и вложения не несёт; вариант, не назвавший ни одного из них, — письмо без QR-кода. Лишнего вложения, на которое никто не ссылается, не бывает;
  • письмо одно, а редакций у ступени две. Ступень лестницы — либо строка (текст, годный любому приёмнику), либо объект { "Subject": …, "Html": …, "Plain": … }. Каждая редакция необязательна, но хотя бы одну ступень обязана заявить: ступень без единой редакции останавливает старт с указанием рода сообщения и номера ступени. Ступень, заявившая только Html, для текстовой части не годится — подбор просто идёт ниже по лестнице, так что две части одного письма могут прийти с разных ступеней. Тема при этом берётся у ступени, выбранной для Html;
  • последняя ступень лестницы обязана опираться только на гарантированные слоты (app, valid_until, link, lang; в sign-in-code-mail место link занимает code, а sign-in-code-link-mail гарантирует оба). Детали инициатора и QR-код гарантированными не являются: транзакция без них штатно доходит до ступени, которая их не называет, — и в письме не появляется ни пустого абзаца, ни литерала {browser}. Считается это по каждой редакции отдельно: подбор идёт среди ступеней, заявивших нужную редакцию, поэтому у лестницы две «последних» ступени — последняя с Html и последняя с Plain, — и требование распространяется на обе. Лестница, где последняя ступень с Html называет {browser}, а бесслотовой сделана только Plain, останавливает старт;
  • письмо только в html (или только текстом) — законное объявление. Если Plain не заявляет ни одна ступень, письмо уходит без текстовой части: ошибки в логе нет, подмены редакций нет. Ровно поэтому проверьте, что односоставное письмо — ваш выбор, а не забытая редакция: в данных эти два случая неотличимы.
Лестница страхует от недостающих данных и не заменяет настройку. Она существует потому, что детали инициатора ({browser}, {os}, {region}) и QR-код в рантайме могут отсутствовать, — а не потому, что формулировки можно не дописывать. Объявление заменяет лестницу целиком: интегратор, объявивший одну ступень, чтобы «поменять формулировку», молча теряет всю поставляемую ядром лестницу вместе со всеми обеднёнными вариантами. И последняя ступень — не техническая заглушка: именно её текст пользователь прочитает чаще всего, когда контекста не будет.Об обоих случаях ядро один раз сообщает при старте записью уровня Warning: когда объявленная лестница короче поставляемой по тому же адресу (в сообщении — род, адрес и оба числа ступеней) и когда Plain не заявляет ни одна ступень. Старт при этом не блокируется — короткая лестница и односоставное письмо остаются законными объявлениями. Проверяется то, что видно при старте: секция развёртывания и поставляемый файл, то есть уровень Core. Значения, объявленные тенантом, приложением или записью ui_config, при старте перечислить нельзя — их отсутствие в предупреждениях не означает, что там всё в порядке.
Если письмо нужно собрать кодом — взять разметку из своей CMS, подставить собственные значения слотов или решать тему письма самостоятельно, — остаётся один шов: публичный IEmailMessageComposer. Он получает данные отправки и возвращает готовое тело письма (EmailBodyContent: тема, html-часть, текстовая часть и признак QR-вложения), а провайдер доставки занимается только транспортом.
Program.cs
Регистрация подчиняется общему правилу подмены через DI: своя реализация, зарегистрированная до AddVeriqa*, уже стоит в контейнере и поставляемая не добавляется; после — RemoveAll + Add. Разметку письма задаёт текст варианта в конфигурации выше (её пример — в начале этого раздела); для полного контроля — IEmailMessageComposer. Своя реализация композера берёт на себя всё тело письма целиком: лестницу деградации, локализацию видимых фраз через Natural Key и решение о QR-вложении она реализует сама.

Нормализация адреса

Секция Normalization определяет, какую форму адреса Veriqa считает идентификатором пользователя:
appsettings.json
Домен с символами вне ASCII (IDN) Veriqa переводит в A-label (Punycode) в нижнем регистре: user@почта.рф и user@xn--80a1acny.xn--p1ai — один пользователь, а claim email содержит вторую форму. ProviderSpecificCanonicalization включает провайдер-специфичную канонизацию. Поддержано одно семейство — Gmail (gmail.com и googlemail.com): точки в локальной части отбрасываются, +-тег отсекается, googlemail.com приводится к gmail.com. Так u.ser+shop@googlemail.com и user@gmail.com становятся одним пользователем. Домены вне этого списка не канонизируются никогда — у многих провайдеров + входит в адрес, и общее правило склеило бы разных людей.
Включение на работающей установке меняет идентичность пользователей. Ранее входившие пользователи получат другой sub: адреса, которые считались разными, склеиваются в один. Миграцию ядро не выполняет — это операционное решение, ровно поэтому настройка выключена по умолчанию. Решайте её до первого входа пользователей, а не после.

Вход через аккаунт провайдера

Пользователь входит через свой аккаунт Google, Apple, Huawei, Яндекс, VK ID или другого провайдера из OpenIddict.Client.WebIntegration: сканирует QR-код телефоном, входит у провайдера на телефоне и подтверждает вход там же. Как это выглядит для пользователя и когда помогает, рассказано на странице Вход через аккаунт провайдера.
Вход на компьютере через Google: камера телефона сканирует QR-код, пользователь выбирает аккаунт Google, сдвигает шторку «Slide to answer Yes» на странице подтверждения и видит «Sign-in confirmed».

Что видит пользователь: QR-код, камера телефона, аккаунт Google, сдвиг шторки на странице подтверждения. Интерфейс на английском.

Чата у такого канала нет. Вопрос «Да/Нет», сообщения после входа и итог показывает страница Veriqa на телефоне — в том браузере, который вернулся от провайдера.
Program.cs
Образ self-hosted пакет уже содержит. Одна регистрация клиента у провайдера — один канал. Его секция — Veriqa:Channels:{канал} с подсекцией WebProvider, а имя секции становится типом канала:
appsettings.json
Идентификатор клиента в примере синтетический, а секрет клиента задаётся переменной окружения Veriqa__Channels__google__WebProvider__ClientSecret. Имя канала — строчные латинские буквы, цифры и -; имя канала из поставки (telegram, email и другие) занять нельзя. Два клиента одного провайдера — это два канала с разными именами. Зарегистрируйте у провайдера адрес возврата {PublicBaseUrl}/auth/web-provider/{канал}/callback. Ошибка в секции включённого канала останавливает старт хоста, и сообщение называет ключ. Регистрации читаются при старте: чтобы добавить или изменить канал, перезапустите хост. Задаёт ли страница на телефоне вопрос «Да/Нет», решает Veriqa:LoginConfirmation:Mode и ModeByChannel, как у любого канала. При OnWebPage вопрос задаёт окно входа, а телефон показывает сообщение о том, что подтвердить нужно там. Когда вход завершится, вместо сообщения появится итог.
При None вход завершается без вопроса. Тогда чужой QR-код, который пользователь отсканирует, завершит чужой вход под его аккаунтом. Почему вопрос нужен, разобрано в сценарии Вход через аккаунт провайдера.
Состояние страниц на телефоне по умолчанию хранится в процессе. Если реплик несколько, подключите канальные хранилища в Redis.

Строки статуса на компьютере

Задайте две строки статуса для каждого канала провайдера. Veriqa поставляет их для каналов с чатом, и канал провайдера получает те же формулировки. Пока пользователь выбирает аккаунт у провайдера, окно входа на компьютере пишет Opening Google…. Когда пользователь вернулся от провайдера, окно просит нажать кнопку подтверждения в чате, хотя чата у этого канала нет: вопрос задаёт страница Veriqa на телефоне. Поставить строки для таких каналов ядро не может: имя канала — это имя вашей секции Veriqa:Channels. Страница, открывающая подтверждение, показывает те же строки.
Задайте channel-launched-line и channel-answer-line для каждого канала провайдера по адресу BySurface:core-page:ByChannel:{канал}. Формулировке подтверждения в channel-answer-line нужен свой адрес — под ByType:confirmation. Для канала google из примера выше:
appsettings.json
{channel_name} — имя канала на его вкладке. Каждый текст — ещё и ключ locale-файлов: добавьте русский перевод в ru.json, как описано в разделе «Тексты каналов и писем — те же locale-файлы» страницы Настройка и кастомизация. Без перевода русская страница покажет английский текст. Как ищутся эти строки, описано в разделе Строки канала на страницах Veriqa.

Стартовые провайдеры

Для этих пяти провайдеров известно, какие данные пользователя приходят и что для этого настроить. Подробная таблица со ссылками на документацию провайдеров — в README пакета Veriqa.Core.ChannelAdapter.WebProviders. По умолчанию номер телефона ни один из них в канал не передаёт, и форма добора claims его не запрашивает: входу с обязательным номером такой канал не предлагается, а вход, где номер необязателен, завершается без него. Взять номер у провайдера канал может блоком PhoneNumber. Имени пользователя Apple канал не получает, а адрес почты может быть адресом пересылки Apple. Каналу Apple задайте DisplayName, например Apple. В OpenIddict этот провайдер называется «Sign in with Apple», и без ключа кнопка на странице входа читается «Войти через Sign in with Apple». У остальных четырёх имя по умолчанию — название бренда, менять его не нужно.

Подтверждённый email от провайдера

Яндекс ID и VK ID отдают email, но не сообщают, подтверждён ли он. email_verified остаётся неизвестным, и RP или политика ограничений, которой нужен подтверждённый email, считает такой вход неподтверждённым. Блок Email в канале это меняет:
  • При Proof: Proven email от провайдера получает email_verified: true. Если провайдер сам сообщил рядом с email email_verified: false, claim остаётся false.
  • Proof: NotProven — значение по умолчанию, оно равносильно отсутствию блока: решает только email_verified самого провайдера.
  • Если в ответе провайдера нет email, нет и email_verified.
Любое другое значение Proof останавливает старт хоста, и сообщение называет ключ.
Proven — ваше заявление о том, что вы доверяете адресам этого провайдера: Veriqa их не проверяет. По email_verified RP принимает решения о безопасности, например привязывает существующий аккаунт по email. Поэтому задавайте Proven только для провайдера, адресам которого доверяете в таких решениях.
Адрес Apple может быть адресом пересылки (private relay). Apple его подтвердил, но он только пересылает письма на настоящий адрес и идентификатором пользователя не является: идентифицируйте пользователя по sub.

Номер телефона и другие claims от провайдера

Идентификатор, имя, email, аватар и локаль аккаунта канал берёт сам. Номер телефона и другие данные профиля приходят, только если их сопоставить в секции WebProvider: готового сопоставления ни для одного провайдера в пакете нет. Блок PhoneNumber говорит, где в ответе провайдера номер: Veriqa приводит номер к E.164, а значение, которое не похоже на номер, отбрасывает. Если провайдер номера не вернул (пользователь не разрешил или в аккаунте его нет), вход идёт так же, как в канале без номера. Claims — список записей: Source — путь к значению в ответе, в том же виде, что Claim выше; Claim — claim, который выдаёт Veriqa; Scopes запрашиваются у провайдера ради этого claim. Имя claim — один из стандартных claims профиля birthdate, gender, middle_name, nickname, profile, website или имя, которое начинается с имени канала и _ (yandex_login у канала yandex), и написано оно должно быть ровно так. Любое другое имя, как и имя, указанное дважды, останавливает старт хоста. Объявите claim строкой каталога Veriqa:ScopesClaims под тем scope, который должен его открывать: для birthdate — под profile. Тогда scopes записи запрашиваются у провайдера при каждом входе, где приложение получает этот scope, а claim попадает в оба токена. Без строки каталога они не запрашиваются, а claim, который провайдер всё же вернул, идёт только в access token, как любой claim вне каталога. Исключение — nickname: он входит в стандартный набор scope profile и строки каталога не требует, поэтому scopes записи с nickname запрашиваются при каждом входе, где приложение получает profile. Пример для Яндекс ID. Номер телефона Яндекс возвращает в поле number объекта default_phone, а дату рождения — в birthday в виде ГГГГ-ММ-ДД (Яндекс ID: информация о пользователе). Права доступа из примера, login:default_phone и login:birthday, должны быть среди прав вашего приложения; их список — на странице приложения https://oauth.yandex.ru/client/<client_id>/info. Запрос, в котором названы scopes, получает только названные права, а не выбранные при регистрации (Яндекс ID: получение кода), поэтому основные права перечислены в Scopes:
appsettings.json
Идентификатор клиента синтетический. Указав Proof: Proven, вы доверяете номерам Яндекса как подтверждённым; если не доверяете, оставьте NotProven. Непустой ScopesClaims:Scopes заменяет собственный набор scopes продукта: перечислите все scopes, которые запрашивают ваши клиенты, как описано в справочнике.

Другие провайдеры для входа людей

Канал можно построить и на другом провайдере OpenIddict.Client.WebIntegration. Ниже — те, чьё главное назначение — аккаунт человека, личный или рабочий. Провайдеры, которые дают доступ к данным сервиса, а не аккаунт человека (Strava, Spotify, Calendly и подобные), в перечень не входят. Данные пользователя приходят такими, какими их сводит OpenIddict; что именно отдаёт провайдер и какие scopes для этого нужны, смотрите в его документации. Полный перечень провайдеров — в документации OpenIddict.

Как дать клиенту выбрать канал

Клиент может ограничить конкретный вход определёнными каналами через стандартный OIDC-параметр acr_values, в форме channel:{type}:
Перечислите несколько (channel:telegram channel:whatsapp), чтобы сузить выбор, не фиксируя его. Без параметра предлагается каждый включённый канал.

Чек-лист

1

Адаптер зарегистрирован и включён

AddXxx() вызван и у секции стоит "Enabled": true.
2

Уровень проверки объявлен осознанно

У каждой канальной секции стоит InboundVerification, и значение соответствует режиму, в котором канал реально работает.
3

Вебхук доступен

https://…/api/channels/… публично доступен по HTTPS и не заблокирован вашим прокси.
4

Секреты в хранилище секретов

Ни один токен или пароль не лежит в закоммиченном файле конфигурации.
5

Вход подтверждён от начала до конца

Реальное подтверждение с телефона завершает поток и выдаёт токены.

Дальше

Справочник конфигурации

Все секции, ключи и значения по умолчанию в одном месте.

Настройка и кастомизация

Дизайн страницы входа, локализация, точки расширения.

Подготовка к продакшну

Что проверить перед запуском в продакшн.

Архитектура

Как адаптеры встроены в остальной коннектор.
* Instagram, Messenger и Facebook — продукты компании Meta, признанной в России экстремистской организацией; её деятельность в стране запрещена.