Перейти к основному содержанию
Страница входа и поведение Veriqa настраиваются конфигурацией, а ключевые сервисы можно заменить своей реализацией. Ниже описано то, что чаще всего настраивают при интеграции.

Каналы

Каждый канал подключается в AddChannelAdapters и активируется секцией Veriqa:Channels:{Канал} с "Enabled": true. Доступны MAX, Telegram, WhatsApp, Instagram*, Messenger*, WeChat, Viber и Email. Каждый из них поставляется отдельным пакетом. Базовый набор (Telegram, WhatsApp, Email) — метапакет Veriqa.Core.BaseChannels; MAX, Instagram*, Messenger*, WeChat и Viber — отдельные пакеты (Veriqa.Core.ChannelAdapter.Max, Veriqa.Core.ChannelAdapter.Instagram, Veriqa.Core.ChannelAdapter.Messenger, Veriqa.Core.ChannelAdapter.WeChat, Veriqa.Core.ChannelAdapter.Viber). Если нужен один канал, подключите только его пакет. Подробнее — настройка каналов и поддерживаемые каналы.
Program.cs
Email работает в двух режимах: Pull (magic link — пользователь переходит по ссылке из письма) и Push (письмо в один тап — пользователь отправляет готовое письмо). Push по умолчанию выключен и включается флагом Veriqa:Channels:Email:PushEnabled. Эндпоинты Email-канала регистрирует MapVeriqaAuthServer автоматически при включённом канале — см. быстрый старт, шаг 3.
Telegram получает обновления в режиме Webhook (по умолчанию) или Polling — задаётся Veriqa:Channels:Telegram:UpdateMode. Для Webhook укажите WebhookBaseUrl и WebhookSecretToken.
Клиент может ограничить вход конкретным каналом через acr_values=channel:{тип} — см. быстрый старт.

Email: доставка и приём

Email включается двумя независимыми режимами под секцией Veriqa:Channels:Email:
  • Pull (magic link) — Veriqa отправляет письмо со ссылкой, пользователь переходит по ней. Включён по умолчанию (PullEnabled). Вместо ссылки письмо может нести код или и то и другое — см. Ссылка, код или оба.
  • Push (письмо в один тап) — пользователь отправляет готовое письмо на входящий адрес, Veriqa обрабатывает входящее. Выключен по умолчанию (PushEnabled) — включается вместе с настройкой приёма и политикой верификации отправителя. Флаг читается при старте: после его изменения сервис нужно перезапустить.
appsettings.json
  • PublicBaseUrl обязателен при включённом канале — из него строятся magic links и QR-коды.
  • Outbound:Smtp — SMTP для Pull-режима (Port 587 = STARTTLS; UseSsl: true = implicit TLS, порт 465). При заданных учётных данных STARTTLS обязателен, если не указано RequireStartTls: false (по умолчанию true). Пароль храните в хранилище секретов, не в appsettings.json.
  • Inbound — приём для Push-режима: InboundAddress, UsePlusAddressing (вкладывает correlation-токен в адрес вида login+{token}@…), WebhookSecretToken для валидации вебхука провайдера.
  • VerificationPolicy — верификация отправителя: DmarcAlignedPass (по умолчанию), AllowListOnly (по списку AllowedDomains). Значение None в продакшне запрещено.

Дизайн-пресеты и тема

Внешний вид страницы задаётся пресетом Veriqa:AuthPageDesign:Preset: Цветовая схема управляется отдельно — Veriqa:AuthPageDesign:Theme: Явный Theme (Light / Dark) приоритетнее цветовой схемы пресета; при Theme: Auto пресет Dark тоже даёт тёмную страницу. Тема проставляет на <html> атрибут data-theme, пресет — data-preset. Анимации учитывают prefers-reduced-motion. Тема действует на всех страницах, которые генерирует Veriqa, а не только в окне входа: страница подтверждения входа, страница добора недостающих данных, страница истёкшей ссылки и страницы входа по email несут тот же data-theme. При Theme: Auto они следуют системной настройке посетителя, поэтому собственная таблица стилей, рассчитанная на светлые цвета, на устройстве с тёмной темой окажется поверх тёмных цветов — закрепите схему значением Theme: Light, если это недопустимо.
appsettings.json

Видимость QR-кода

Показывать ли QR-код на странице входа, задаёт ключ ShowQrCode секции Veriqa:AuthPageDesign:QrCode — в ней же задаётся разрешение кода (справочник конфигурации):
appsettings.json
Там, где этот раздел говорит о вкладках, ChannelLayout: Grid ставит каналы рядом. Два свойства DesktopOnly, которых не видно по названию:
  • Планшет считается десктопом. QR-код сканируют камерой другого устройства, поэтому на устройстве, тип которого неясен, код остаётся.
  • При промахе определения устройства QR-код показывается. Устройство определяет сама страница, и любой сбой этой проверки — заблокированный скрипт, нераспознанный User-Agent — оставляет QR-код и вкладки на месте. Страница, единственный вход на которой — недоступная пользователю кнопка, хуже, чем QR-код там, где он бесполезен.
Пресет на видимость QR-кода не влияет: Preset и ShowQrCode — независимые настройки.
После обновления. Раньше по умолчанию было Always. Установка, не задающая ShowQrCode, теперь показывает на телефоне кнопки каналов вместо QR-кода и вкладок; планшет и десктоп не меняются. Чтобы сохранить прежнюю страницу, задайте "ShowQrCode": "Always".

Кнопки каналов

На телефоне при DesktopOnly и на любом устройстве при Never полосы вкладок нет: каналы идут списком кнопок, по одной на канал, в порядке набора каналов.
  • Кнопка мессенджера — «Войти через …» при входе, «Подтвердить в …» при подтверждении — ведёт прямо в него.
  • Email с кнопкой почтового клиента сохраняет эту кнопку и ссылку «Войти по ссылке на почту» под ней (у подтверждения — «Подтвердить по ссылке на почту»); подпись ссылки зависит от того, что несёт письмо входа.
  • Email с формой адреса получает свою кнопку, которая раскрывает форму на месте. Страница, где этот канал единственный, показывает форму сразу — выбирать не из чего.
  • Подсказка канала не показывается: она относится к открытому каналу, а здесь открытого канала нет. На странице с одним каналом подсказка остаётся, у Email — и после того, как открыта форма адреса.
При Never эту раскладку рендерит сам сервер, поэтому скрипт ей не нужен. При DesktopOnly страница рендерится с вкладками и переходит на кнопки, распознав телефон.

Видимость кнопок каналов

QR-код ведёт в канал с другого устройства, кнопка — с этого. Такие кнопки — «Войти через …» или «Подтвердить в …», а у Email — «Отправить письмо-подтверждение». Показывать ли такую кнопку, задаёт ключ ShowChannelButton секции Veriqa:AuthPageDesign:ChannelButton — пара к ShowQrCode:
appsettings.json
Пара из примера — то, что нужно экрану, на который смотрят издалека: телевизору, киоску, проектору. На большом экране QR-код, на телефоне кнопки, на каждом устройстве ровно один вход. Что настройка охватывает:
  • Кнопки, ведущие в канал: «Войти через …» или «Подтвердить в …» у каждого канала, включая сторонний, и «Отправить письмо-подтверждение» у Email. Там, где эта кнопка скрыта, скрыты и строка «ИЛИ», и ссылка «Войти по ссылке на почту» под ней (у подтверждения — «Подтвердить по ссылке на почту»), а в панели Email остаётся QR-код.
  • Но не форму адреса у канала Email без кнопки почтового клиента: форма и кнопка, раскрывающая её в списке кнопок каналов, показываются при любом значении: там форма — единственный путь входа.
  • Окно входа и страницу, открывающую подтверждение. Страницы, которые телефон получает после сканирования hop-QR, сохраняют кнопки при любом значении, включая ссылку Email на форму адреса: там кнопка — единственный путь дальше.
Два свойства MobileOnly:
  • Планшет считается не телефоном — так же, как при DesktopOnly: он получает QR-код и не получает кнопок.
  • При промахе определения устройства кнопка остаётся скрытой — в отличие от QR-кода, который в этом случае остаётся на странице. Заблокированный скрипт или нераспознанный User-Agent оставляют телефон без кнопок; входом тогда служит QR-код, который допустимая пара на такой странице сохраняет.
Как и ShowQrCode, ключ задаётся на уровнях владения, и побеждает ближайший заданный: запись ui_config (ChannelButton:ShowChannelButton под Veriqa:UiConfigurations:Records:<код>) → запись клиента (тот же член в его записи Veriqa:OpenIddict:Clients) → глобальная секция. Между двумя последними стоит уровень тенанта; как и для блока в подвале, читатель этого уровня из коробки не зарегистрирован.

Допустимые сочетания двух видимостей

Два ключа резолвятся независимо, и каждый может прийти со своего уровня — например запись клиента скрывает кнопки поверх глобальной секции, скрывающей QR-код. У каждого класса устройств должен остаться вход — QR-код или кнопка: Недопустимая пара не останавливает хост и не ломает страницу: страница рендерится так, как если бы ShowChannelButton был Always, а в лог уходит предупреждение с обоими заданными значениями — при каждом запросе такой страницы, а не один раз на старте. Проверка смотрит только на две настройки, а не на состав каналов страницы.

Инструкция следует обеим настройкам

Встроенная инструкция под заголовком называет только то, что страница показывает. В разметку она попадает тремя редакциями — для страницы с QR-кодом и кнопкой, только с QR-кодом и только с кнопкой, — а таблица стилей страницы показывает ровно одну из них, по тем же атрибутам корневого элемента, которые показывают и скрывают QR-код и кнопки (data-qr-visibility, data-channel-button-visibility, data-device). Каждая редакция есть для входа и для подтверждения: вход читается как в таблице, любая другая транзакция — той же редакцией с to confirm in {0} вместо to sign in with {0} и to confirm вместо to sign in, например Choose a channel and tap its button to confirm. Поэтому телевизор при ShowChannelButton: MobileOnly читает редакцию без обещания кнопки, а телефон при ShowQrCode: DesktopOnly — без обещания QR-кода: переписывать формулировку руками не нужно. Браузер, в котором определение устройства не сработало, получает редакцию десктопа — так же, как получает его QR-код и кнопки. Какой столбец действует, решает раскладка каналов страницы:
  • Один канал — первый столбец, канал назван: его значок и название.
  • Несколько каналов на вкладках — редакция выбранной вкладки: вкладка канала, с одним QR-кодом и одной кнопкой, берёт первый столбец с названием этого канала. «Только кнопку» — это телефон без QR-кода, где вкладки становятся кнопками, поэтому эта строка берётся из второго столбца.
  • Несколько каналов на экране сразу — сетка, кнопки, которые раскладывает сервер, — второй столбец.
  • Один QR-код на несколько каналов — его страница показывает в hop-режиме. При QrMode: Unified вкладок нет, и страница говорит редакциями последнего столбца. При QrMode: UnifiedWithChannels QR-код стоит на вкладке «Любой канал», за ней — по вкладке на канал: вкладка канала берёт первый столбец, а вкладка «Любой канал», где пользователь выбирает один из нескольких мессенджеров, вместо первой строки последнего столбца читает Scan the QR code or tap your messaging app's button to sign in (… to confirm). При ShowChannelButtonsOnAnyChannelTab = false эта вкладка показывает только QR-код и читает Scan the QR code to sign in. На телефоне, который скрывает QR-код, вкладки становятся кнопками, и страница читает Tap a channel button to sign in.
Редакция, которая называет канал, следует тому, что лежит на панели этого канала: QR-код она упоминает, только если панель его показывает, кнопку — только если панель показывает кнопку. Панель без своего QR-кода берёт строку «только кнопка» везде, где её кнопка видна, даже когда страница показывает QR-код. Панель Email в режиме Pull без QR-кода рядом держит одну форму адреса, поэтому на ней написано Enter your email to get a link — у входа и у подтверждения одинаково. Когда письмо несёт код, на панели написано Enter your email to get a code или Enter your email to get a link and a code. Если QR-код канала не удалось нарисовать, а страница скрывает кнопки каналов, на панели не остаётся ни того, ни другого, и инструкции у неё нет. При смене вкладки скрипт подменяет текст. Блок держит высоту самого длинного варианта, поэтому ничего под ним не сдвигается, а экранному чтецу смена не объявляется — он и так называет выбранную вкладку. Браузер с выключенными скриптами показывает редакцию вкладки, выбранной при загрузке, — «Любой канал», если он есть, иначе первого канала. Инструкция, заданная настройкой (Instruction), заменяет собственную: это одна формулировка, и вкладки её не меняют. Вкладки страницы с вкладкой «Любой канал». «Любой канал» занимает строку полосы вкладок целиком; вкладки каналов идут под ней по две в строке, а последняя из нечётного числа растягивается на всю строку. От пяти вкладок каналов они идут по три в строке, как и на странице без вкладки «Любой канал», а вкладки неполной последней строки делят её ширину поровну: пять вкладок дают строки из трёх и двух, семь — из трёх, трёх и одной. Вкладка канала, на панели которой показан собственный QR-код этого канала, подписана встроенным текстом {0} ▦: в {0} — имя канала, а метка ▦ рисуется значком QR-кода цветом текста вкладки — так видно, на каких вкладках есть QR-код. Вкладка, на панели которой QR-кода её канала нет, — Email со входом по ссылке из письма, — подписана одним именем. Подпись переформулируется как любой другой текст: замена сохраняет {0}, каждая ▦ в ней становится значком, а замена без метки показывается без значка. Страница одного канала называет канал. В слот {0} страница подставляет значок канала и за ним его имя — ту же пару, что стояла бы на его вкладке; канал без значка называется одним именем. Страница нескольких каналов канал не называет. Каждая из десяти редакций — встроенный текст, и своя формулировка задаётся ей как любому другому: для одного приложения — в его словаре AuthPage.Texts, для всей установки — в locale-файлах. У трёх текстов со слотом две особенности:
  • замена в AuthPage.Texts обязана нести {0}, как любая замена текста со слотом; перевод в locale-файле, который слот потерял, выводится как есть — канал тогда остаётся неназванным;
  • {0} стоит в тексте, а не внутри тега. Формулировка, где слот попал в значение атрибута, — <a href="https://your-domain.com/help?c={0}" target="_blank"> — выводится обычным текстом, с предупреждением в логе (см. Разметка в заголовке, инструкции и подсказке канала).
Запись ui_config может заменить инструкцию своим текстом — отдельным полем на каждую редакцию:
appsettings.json
Каждая редакция выбирается отдельно: её поле, иначе Instruction, иначе встроенная формулировка с учётом вашей замены в AuthPage.Texts. Запись, в которой задан только InstructionWithoutQr, меняет текст на телефоне, а на компьютере остаётся встроенная инструкция. В записи из внешнего хранилища поля называются instruction, instruction_without_qr и instruction_without_button. Ваш текст не называет канал и не меняется при переключении вкладок. Страница, единственный канал которой — Email с формой адреса, не показывает ни QR-кода, ни кнопки канала, но получает редакцию страницы одного канала; такой странице задайте свой Instruction.

Текст страницы следует за фактом показа QR-кода

Строки, называющие код или кнопку, попадают в разметку всеми редакциями сразу: инструкция — тремя из таблицы выше, ссылка «вернуться к QR-коду» панели Email — парой «с QR-кодом» и «без QR-кода». Переключаются они теми же условиями, что и блоки, которые они описывают: правилами по атрибутам data-qr-visibility, data-channel-button-visibility и data-device корневого элемента — у пары это классы .veriqa-if-qr / .veriqa-if-no-qr. Скрипт страницы в выборе не участвует. Так страница не обещает ни QR-кода, ни кнопки, которых не показывает. Для интегратора это ограничение на свой CSS (CustomCssPath) и скрипт (CustomJsPath): правило, перебивающее display этих редакций, рассогласует текст с картинкой — например оставит «отсканируйте код» на странице без кода. Скрывая или показывая QR-код или кнопки своими средствами, переключайте редакции текста теми же условиями.
QR-код генерируется сервером всегда, даже когда страница его не показывает: PNG попадает в разметку как data-URI и остаётся скрытым. При Never это только увеличивает вес ответа.

Раскладка каналов

Там, где страница показывает несколько каналов и у каждого свой QR-код, каналы делят её вкладками — на экране один канал за раз. Ключ ChannelLayout секции Veriqa:AuthPageDesign выводит их все сразу:
appsettings.json
При Grid:
  • Карточка растёт с числом каналов. Её ширина — обычная одна колонка (420px) плюс колонка на каждый следующий канал, но не больше окна за вычетом полей, которые карточка держит всегда. Панели, не поместившиеся в ряд, переносятся на следующую строку — вплоть до одной в строке на узком окне.
  • В панели то же, что показала бы её вкладка: QR-код, кнопка канала (с учётом ShowChannelButton), форма Email, подсказка канала.
  • Вкладок в разметке нет. Каждая панель — группа, подписанная видимым именем своего канала, поэтому экранный чтец объявляет каналы, а не «вкладка 1 из 3».
Ключ раскладывает то, что иначе лежало бы во вкладках, и больше ничего. Страница, на которой раскладывать нечего, одинакова при любом значении:
  • страница с одним каналом;
  • страница, разложенная кнопками каналов, — любое устройство при ShowQrCode: Never, телефон при DesktopOnly;
  • в hop-режиме — страница, которая показывает один QR-код на все свои каналы, в том числе когда он стоит на вкладке «Любой канал» перед вкладками каналов (QrMode: UnifiedWithChannels): её вкладки остаются вкладками.
Состав каналов страницы — другая настройка: ChannelDisplay:Mode и набор каналов. Раскладка действует в окне входа и на странице, открывающей подтверждение. Задаётся она на тех же уровнях, что ShowChannelButton: запись ui_config (ChannelLayout под Veriqa:UiConfigurations:Records:<код>) → запись клиента (ChannelLayout в его записи Veriqa:OpenIddict:Clients) → глобальная секция.
Своя таблица стилей. Правило из CustomCssPath, задающее ширину .veriqa-container, сужает карточку раскладки Grid обратно до одной колонки, и ряд превращается в столбец. Пишите его только для одноколоночной карточки: .veriqa-container:not(.veriqa-container--grid).

Запоминание канала входа

Страница входа может запомнить, через какой канал пользователь входит на этом устройстве, чтобы ему не приходилось выбирать канал заново. В секции RememberChannel раздела Veriqa:AuthPageDesign два ключа, оба по умолчанию выключены:
appsettings.json
Страница запоминает только тип канала — telegram, whatsapp и т. п., — но не аккаунт пользователя в этом канале. Хранит его скрипт страницы в cookie на хосте Veriqa, сервер её не читает. Cookie с каналом, которого на странице нет, не учитывается: если приложение прислало acr_values=channel:telegram, а в cookie записан WhatsApp, страница будет такой же, как без cookie. Страница, открывающая подтверждение, ведёт себя так же, различаются только слова, называющие действие: «Запомнить способ подтверждения на этом устройстве», «Всегда подтверждать в Telegram на этом устройстве». В браузере с выключенными скриптами нет ни подсказки, ни флажка.

Подсказка

Страница записывает канал, когда пользователь действительно им воспользовался:
  • в окне входа и на странице, открывающей подтверждение, — когда ответил бот канала; у Email — когда пользователь открыл ссылку из письма или письмо пришло;
  • на странице, которую телефон открывает по единому QR-коду hop-режима, — когда пользователь нажал кнопку канала.
Канал без такого события в окне входа не запоминается. Окно входа, перешедшее на опрос до ответа канала, ответа не слышит и канал тоже не записывает. На странице с флажком подсказка ничего не записывает: канал там сохраняет только флажок. Но подсказку такая страница читает, поэтому при обоих включённых ключах пометка «В прошлый раз» на ней называет канал, которым входили в этом же браузере со страницы без флажка: до того, как флажок включили, или в другом приложении на том же хосте. Входы на этой странице без отметки флажка пометку не меняют. При следующем визите:
  • Вкладки (QrMode: PerChannel): страница открывается на вкладке запомненного канала, а не на первой.
  • Вкладка «Любой канал» (QrMode: UnifiedWithChannels): страница по-прежнему открывается на ней, а вкладка запомненного канала получает пометку «В прошлый раз».
  • Кнопки каналов — на телефоне, на странице, которую телефон открывает по единому QR-коду, и рядом с единым QR-кодом на компьютере: кнопка запомненного канала стоит первой, с пометкой «В прошлый раз». Первой она стоит и в разметке, поэтому фокус клавиатуры и экранный чтец сначала попадают на неё.
  • ChannelLayout: Grid на компьютере: ничего не меняется — все каналы и так на экране.

Флажок

Флажок показывается на компьютере, когда страница показывает один QR-код на несколько каналов (QrMode: Unified или UnifiedWithChannels), в окне входа и на странице, открывающей подтверждение. Он стоит под кнопкой отмены, а если её нет — под строкой статуса. На телефоне флажка нет, даже при ShowQrCode: Always.
  • Первый визит. Страница выглядит как обычно, флажок «Запомнить способ входа на этом устройстве» не отмечен.
  • Пользователь отметил флажок. Страница сохраняет канал, который ответил, в тот же момент, что и подсказка. Если канал ответил до отметки, страница сохраняет его сразу при отметке. Пока флажок не отмечен, страница ничего не сохраняет, в том числе cookie подсказки.
  • Следующий визит. Страница показывает только запомненный канал: его собственный QR-код, его кнопку и его инструкцию, без полосы вкладок и единого QR-кода. Этот QR-код ведёт сразу на страницу запуска канала, минуя страницу с кнопками каналов. Флажок отмечен, текст — «Всегда входить через Telegram на этом устройстве». Ссылка «Выбрать другой канал» под инструкцией, после разделителя «ИЛИ», возвращает единый QR-код и все каналы без перезагрузки страницы, вход остаётся тем же. Когда канал ответил, ссылка исчезает.
  • Пользователь снял флажок. Страница сразу удаляет cookie, и следующий визит — снова первый.
При включённом Checkbox страница QrMode: Unified несёт ещё и QR-код каждого канала, скрытый, пока страница не показывает этот канал один, поэтому ответ растёт с числом каналов. При выключенном ключе разметка страницы не меняется. У обеих cookie атрибуты Path=/; Max-Age=15552000; SameSite=Lax; Secure: они живут 180 дней с последней записи. Safari удаляет cookie, записанные скриптом, если семь дней пользователь не взаимодействовал с сайтом (защита от отслеживания WebKit), поэтому в Safari канал, которым не пользовались неделю, забывается раньше. Оба ключа задаются в записи клиента (RememberChannel:Hint и RememberChannel:Checkbox в его записи Veriqa:OpenIddict:Clients) и в глобальной секции, и побеждает ближайший уровень, задавший ключ. Между ними стоит уровень тенанта, как и для ShowChannelButton. В записи ui_config эти ключи не задаются. Статья 5(3) Директивы ePrivacy распространяется на любую информацию, которую сайт хранит на устройстве пользователя, — персональные это данные или нет (EDPB Guidelines 2/2023, пункты 10–12). Тип канала никого не идентифицирует, но правило действует и для cookie с ним. Заключение 04/2012 Рабочей группы по статье 29 об исключениях из согласия на cookie (WP194, раздел 3.6) освобождает cookie настройки интерфейса от согласия, только если пользователь сам попросил сайт запомнить выбор, и только на время сессии браузера или на несколько часов дольше. Чтобы хранить выбор дольше, нужно согласие пользователя.
  • Флажок и есть способ получить это согласие: пока пользователь его не отметил, ничего не сохраняется. WP194 (раздел 3.2) называет подходящим способом флажок с короткой пометкой вроде «remember me (uses cookies)». Встроенный текст флажка cookie не упоминает — решите, достаточно ли он сообщает вашим пользователям. Пометку можно добавить, переписав текст в словаре AuthPage.Texts.
  • Подсказка хранит канал 180 дней, хотя пользователь об этом не просил, поэтому исключение на неё не распространяется. В ЕС включайте Hint, только если ваш собственный механизм согласия, например баннер cookie, охватывает veriqa_last_channel. Veriqa это согласие не запрашивает и не проверяет.
Раздел описывает только право ЕС и не касается правил других юрисдикций.

Кнопка отмены

В окне входа есть кнопка «Отменить вход» (Cancel sign-in) — путь назад в приложение для пользователя, который передумал. Она стоит под каналами, строкой статуса и отсчётом, над блоком в подвале. Кнопка включена по умолчанию; выключает её ключ Enabled секции Veriqa:AuthPageDesign:Cancel:
appsettings.json
Что делает нажатие при входе:
  • Вход завершается как отклонённый пользователем — транзакция закрывается отказом с причиной declined_by_user, той же, что у «Нет» на веб-странице подтверждения.
  • Браузер возвращается в ваше приложение — на redirect_uri запроса, со стандартным error=access_denied, тем state, с которым пришёл запрос, и идентификатором издателя iss (RFC 9207), в запрошенном режиме ответа (query, fragment или form_post). Приложение обрабатывает это как любой отклонённый вход. Клиенту ASP.NET Core на AddOpenIdConnect нужно сказать, куда отправить пользователя: без AccessDeniedPath обработчик выбрасывает на access_denied исключение, и возврат заканчивается HTTP 500 — см. шаг 5 .NET quickstart.
  • «Да», уже данное в канале, остаётся в силе: если канал принял ответ и вход уже завершается, кнопка его не отменяет. Браузер дожидается завершения, и пользователь входит в приложение.
  • Чат, где ждёт вопрос, узнаёт об отмене: если вход ждал ответа пользователя на вопрос, уже показанный в чате мессенджера, в этот чат приходит та же квитанция «Вход отклонён», что и по нажатию кнопки отказа. Где платформа умеет править отправленное сообщение — в MAX и Telegram, — квитанция встаёт на место вопроса и его кнопки исчезают; в остальных — Instagram*, Messenger*, WhatsApp и подобных — она приходит новым сообщением, а кнопки вопроса остаются, и на позднее нажатие бот отвечает той же квитанцией. Если вопрос задан не в чате — в Email или на веб-странице, — ничего не отправляется. Что бы ни случилось с квитанцией, приложение получает access_denied.
При подтверждении. На странице, открывающей подтверждение, на том же месте стоит такая же кнопка с текстом «Отменить подтверждение». Приложения, в которое можно вернуться, здесь нет, поэтому нажатие делает следующее:
  • Подтверждение завершается как отклонённое пользователем — транзакция закрывается отказом с причиной declined_by_user, а ваш бэкенд видит исход declined в результате транзакции и в её событиях.
  • Браузер получает квитанцию отказа — текст «отклонено» из раздела «Что пользователь читает по завершении». Если время уже истекло, браузер получает квитанцию «истекло».
  • «Да», уже данное в канале, остаётся в силе: если канал принял ответ, кнопка исход не меняет. Исход — confirmed, отказ страница не показывает.
  • Чат, где ждёт вопрос, узнаёт об отмене так же, как при входе, — квитанцией с формулировкой для подтверждения.
Кнопка — обычная форма, поэтому работает и на странице, скрипт которой не выполнился. Она уходит со страницы, когда отменять больше нечего: транзакция истекла, отклонена, завершилась ошибкой или подтверждение уже состоялось. Где показывается. В окне входа и на странице, открывающей подтверждение, в том числе после того, как бот канала ответил. Телефон, отсканировавший hop-QR, получает кнопку на двух страницах, при входе и при подтверждении: на странице QR-кода, общего для всех каналов, и на странице Email с кнопкой почтового клиента и формой адреса. Нажатие там завершает вход или подтверждение так же. Телефон получает квитанцию отказа (Sign-in declined ❌ при входе), окно входа на другом устройстве возвращается в ваше приложение с error=access_denied, а чат, где ждёт вопрос, узнаёт об отмене. На странице запуска, которую получает любой канал, кнопки нет, что бы ни стояло в настройке. Уровни. Побеждает ближайший уровень, задавший ключ: запись ui_config (Cancel:Enabled под Veriqa:UiConfigurations:Records:<код>) → запись клиента → глобальная секция. Чтобы оставить без кнопки одно приложение, задайте ключ в записи этого клиента:
appsettings.json
Текст — Natural Key Cancel sign-in: тот же ключ, что у отмены на шаге добора claims, поэтому уже имеющиеся у вас переводы действуют и на кнопку. На странице, открывающей подтверждение, ключ — Cancel confirmation. Чтобы переформулировать кнопку для одного приложения, назовите нужный ключ в его словаре AuthPage.Texts.
После обновления. Кнопка включена по умолчанию: она появится в окне входа и на странице, открывающей подтверждение, в каждой установке, которая не задала "Enabled": false. Настраивать для этого ничего не нужно. Теперь кнопка есть и на перечисленных выше страницах телефона, открытых по hop-QR. Если вы добавляли свой элемент отмены через CustomJsPath, уберите его или выключите встроенную кнопку. Свой рендерер кнопку не покажет, пока сам не выведет её форму.
Что кнопка меняет в ответе окна входа. Директива form-action его Content-Security-Policy называет рядом с 'self' источник redirect_uri клиента (для адреса с собственной схемой — эту схему): браузер применяет директиву ко всей цепочке редиректов после отправки формы, а отправка кнопки заканчивается на redirect_uri. Ответ также ставит antiforgery-cookie. При выключенной кнопке в ответе нет ни cookie, ни расширенной form-action; Cache-Control: no-cache, no-store он несёт в обоих случаях.

Брендирование

Логотип и имя бренда клиента заполняют строку бренда вверху карточки входа в любом пресете, кроме Minimal; основной цвет применяется только в пресете Branded:
appsettings.json
  • PrimaryColor — строго формат #RRGGBB; недопустимое значение заменяется нейтральным цветом по умолчанию. Красит только общие элементы (основную кнопку, фокус-рамки, спиннер).
  • LogoUrl и BrandName вместе заменяют собственный знак продукта. Если ни один уровень не задал ни того, ни другого, строка бренда показывает красный ромб и Veriqa. Заданное любое одно значение заменяет этот знак целиком: одно имя — без ромба, один логотип — без Veriqa. Поэтому незаданный логотип не означает «без строки бренда» — страница без неё задаётся пресетом Minimal. Страницы, кроме окна входа (веб-подтверждение, истёкший вход, страницы писем), строки бренда не выводят вовсе.
  • BrandName — имя рядом с логотипом, вместо собственной подписи продукта. Логотип и имя резолвятся независимо: задайте любое одно, и страница покажет то, что есть, — только имя, только логотип или оба. В отличие от логотипа имя не задаётся отдельно для каждой темы (картинка не может перекраситься под тёмную страницу, а текст берёт цвет страницы), поэтому BrandNameByTheme не существует. Пустое значение не задаёт ничего: имя тогда берётся с уровня ниже. Значение — обычный текст (выводится экранированным) и ключ локализации (см. Локализацию).
  • PrimaryColorByTheme и LogoUrlByTheme задают значение для конкретной темы (light, dark). Тема без своего значения берёт соседний общий ключ (PrimaryColor, LogoUrl). При Theme: Auto тему выбирает браузер, и на страницу попадают оба значения — светлое и тёмное.
  • Раздавайте логотип с того же сервера, что отдаёт страницу входа. Политика безопасности содержимого (CSP) страницы разрешает изображения только с её собственного источника (origin): img-src 'self' data:. Логотип с другого домена, например с CDN, браузер заблокирует, и он не появится. Укажите путь на этом сервере (/branding/logo.png) или полный адрес https:// того же источника. Адрес data: в LogoUrl не принимается: страница его отбрасывает.
  • Кнопки мессенджеров (MAX, Telegram, WhatsApp) сохраняют фирменные цвета в любом пресете. Чтобы перекрасить кнопку и значок отдельного канала, задайте ChannelButtonColors.
После обновления. Логотип или имя бренда, заданные при пресете, отличном от Branded, раньше игнорировались, а теперь выводятся. Страница Branded без того и другого раньше обходилась без строки бренда, а теперь показывает собственный знак продукта. В Minimal строки бренда нет в разметке, и своя таблица стилей или скрипт, искавшие её, ничего не найдут.

Цвета кнопок каналов

ChannelButtonColors задаёт цвет кнопки, которая ведёт в отдельный канал: карта «тип канала → #RRGGBB».
appsettings.json
  • Ключ — тип канала: telegram, whatsapp, email, тип вашего SPI-канала. Канал, которого нет в карте, сохраняет свой цвет: фирменный у мессенджера, основной у Email и SPI-канала.
  • В отличие от PrimaryColor, карта действует в любом пресете, включая Minimal.
  • Текст на перекрашенной кнопке остаётся белым, как на фирменных цветах, поэтому выбирайте цвет, на котором белый текст читается.
  • Цвет действует везде, где есть кнопка этого канала: в окне входа, включая кнопку «Copy and open», и на страницах телефона при входе по QR-коду.
  • Тем же цветом окрашивается значок канала: на его вкладке, в заголовке его панели при раскладке Grid, в инструкции страницы с этим одним каналом и в заголовке страницы запуска на телефоне. Значок стороннего канала, глиф которого задаёт свою заливку, сохраняет её.
  • Приложение задаёт свою карту в записи клиента, запись ui_config — в поле ChannelButtonColors (channel_button_colors в записи из внешнего хранилища). Запись главнее приложения, приложение главнее глобальной секции. Цвет каждого канала определяется отдельно: приложение, задавшее цвет только telegram, сохраняет глобальный цвет email.
  • Значение не в формате #RRGGBB не применяется, и цвет берётся с уровня ниже.
Кнопку встроенного канала адресует её собственный класс (veriqa-btn-telegram, veriqa-btn-email и т. д.), у кнопки SPI-канала есть ещё класс veriqa-btn-of-<тип канала>. Через эти классы кнопку можно перекрасить и своей таблицей стилей — селектором не слабее .veriqa-btn.veriqa-btn-telegram.

Блок в подвале страницы входа

FooterHtml ставит вашу собственную разметку внизу карточки входа — ссылки на политику конфиденциальности и условия использования, короткую правовую сноску, контакт поддержки. Блок показывается во всех пресетах, включая Minimal и режим со своей таблицей стилей, и на обеих страницах, где рисуется окно входа: на самом входе и на странице, открывающей подтверждение. Остальные страницы, которые генерирует Veriqa, его не несут — ни страницы подтверждения, ни страница истёкшей ссылки, ни страницы входа по почте.
appsettings.json
Блок задаётся этой глобальной секцией и записью клиента (Veriqa:OpenIddict:Clients), где приложение задаёт свой блок вместо глобального. Запись ui_config его не задаёт: запись выбирается параметром запроса, а запрос может выбирать оформление страницы, но не разметку на ней.
Уровень Tenant. Настройка стоит и на уровне тенанта, но читатель этого уровня из коробки не зарегистрирован — его пишет интегратор. Без него резолюция идёт к записи клиента и к этой секции.
Пустое значение не задаёт ничего — одинаково на любом уровне. Поэтому приложение, в записи которого FooterHtml пуст, покажет блок глобальной секции: нижний уровень не гасит блок верхнего, а только заменяет его. Чтобы одно приложение осталось без блока, задавайте блок в записях тех приложений, которым он нужен, а не глобально.

Что может содержать разметка

Значение проверяется на строгий формат и при выходе за него отвергается целиком — ничего не вырезается и не чинится:
  • текст — любые символы, кроме < и >. Голый & допустим, голый > — нет, пишите &gt;;
  • теги a, span, div, p, strong, em и пустой br (<br>, <br/>, <br /> — закрывающего </br> нет). Имена тегов и атрибутов регистронезависимы;
  • атрибуты href, target, rel и class, каждый не более раза в теге, значение — в двойных кавычках и без ", <, >. Всё прочее — style, id, любой обработчик on* — отвергается, как и значения в одинарных кавычках или без кавычек;
  • никаких классов самой страницы: class отвергается, если одно из его имён — veriqa или начинается с veriqa-, в любом регистре букв и после декодирования символьных ссылок. Имя, лишь начинающееся с этого слова, — veriqable — допустимо, как и пустой class;
  • у каждой ссылки есть href и target="_blank". Адрес проверяется в том виде, в каком его читает браузер, — после декодирования символьных ссылок — и должен быть https://…, http://… либо корневым путём /path. Протокол-относительный //host, адрес javascript: или mailto:, обратный слеш и управляющий символ внутри адреса отвергаются;
  • теги сбалансированы: закрывающий закрывает последний незакрытый, к концу незакрытых нет;
  • комментарии, <!DOCTYPE и любой тег вне списка отвергаются.
target="_blank" здесь не вопрос вкуса. Уход со страницы в той же вкладке обрывает идущий на ней вход, а возврат заново запрашивает GET /connect/authorize и создаёт новую транзакцию — ссылка, открывающаяся на месте, стоит пользователю начатого входа.
Блок выводится как есть — он не очищается. Проверка выше решает, пустить ли значение на страницу, но не чистит его. За то, что блок говорит, куда ведут его ссылки и что они сделают с тем, кто по ним перешёл, отвечаете вы. Своего rel Veriqa тоже не добавляет: атрибуты ваших ссылок задаёте вы.
Почему классы veriqa- отвергаются. Они принадлежат разметке страницы: её скрипт достаёт свои элементы по классу (.veriqa-tab, .veriqa-panel, .veriqa-tooltip-host, .veriqa-tooltip), и блок с таким классом вмешивался бы в поведение страницы, на которой стоит, — class="veriqa-panel" внутри блока погасил бы вкладки каналов. Называйте свои классы своим префиксом и оформляйте их из своей таблицы стилей (CustomCssPath).
Обновление, когда такой класс уже задан. Прежние версии пропускали класс veriqa- в этом блоке; теперь значение недопустимо. Заданное в глобальной секции, оно не даёт хосту стартовать; заданное в записи клиента — выбрасывает эту запись (см. таблицу ниже). Переименуйте класс до обновления.

Что делает недопустимое значение

Перевод блока

Значение — такой же Natural Key, как любой другой текст страницы (см. Локализацию): страница ищет его в locale-файлах хоста, а значение, которого там нет, выводится как есть. Перевод проверяется на тот же формат, что и значение, — перевод вне формата оставляет страницу без блока. Контекстный суффикс работает и здесь, и с разметкой его стоит использовать: блок — длинная строка, и метка страхует её от совпадений.
appsettings.json
ru.json
Учтите, что | зарезервирован под эту метку: всё после последнего | отрезается от текста, который увидит пользователь. Разметка, которая сама должна содержать |, такой способ не подходит — используйте сущность &#124; или другой разделитель.

Разметка в заголовке, инструкции и подсказке канала

Три текста окна входа принимают вашу строчную разметку — слово полужирным, ссылку, span со своим классом:
  • заголовок — Title записи ui_config либо ваша формулировка встроенного заголовка в AuthPage.Texts или в locale-файле;
  • инструкция под ним — Instruction, InstructionWithoutQr или InstructionWithoutButton записи либо ваша формулировка встроенной инструкции;
  • подсказка канала — запись Veriqa:ChannelDisplay:Hints.
appsettings.json
Значение проходит ту же проверку, что и блок в подвале, но набор тегов у́же — только строчные:
  • теги span, strong, em, a и пустой br. div и p здесь отвергаются: текст уже стоит внутри заголовка или абзаца;
  • атрибуты href, target, rel и class — по правилам блока в подвале: двойные кавычки, не более раза в теге, ничего сверх списка;
  • у каждой ссылки есть href и target="_blank" — по той же причине: ссылка, открывающаяся на месте, обрывает идущий на странице вход;
  • никаких классов самой страницы — veriqa и всё, что начинается с veriqa-, отвергается;
  • ни img, ни svg. Значок — это span со своим классом, который рисует ваша таблица стилей (CustomCssPath): <span class="acme-mark"></span>. Подключение своей таблицы стилей отключает дизайн-пресет — см. Внешний CSS.
Значение, не прошедшее проверку, выводится обычным текстом. В отличие от блока в подвале, хост не останавливается и запись не отбрасывается: значение проверяется при выводе страницы на её языке, а перевод из locale-файла — уже переведённым. Значение, вышедшее за формат, попадает на страницу целиком, текстом — теги видны как символы, — а в лог уходит предупреждение. Оно называет элемент и язык (для подсказки — тип канала); само значение в лог не пишется. Обычный текст читается как текст HTML. Значение без тегов проходит как есть, и символьные ссылки в нём читает браузер: Terms &amp; Conditions показывает «Terms & Conditions». Буквальные < и > пишите как &lt; и &gt;: голый символ проверку не проходит, и значение выводится так, как написано, с предупреждением выше. Вкладка браузера получает заголовок без тегов. В <title> документа уходит только текст заголовка, <br> заменяется пробелом. То же действует на обеих страницах, которые рендерят окно, — сам вход и страница, открывающая подтверждение. Свой рендерер получает эти значения сырыми — см. Рендерер страницы входа.

Инструкция после скана

В hop-режиме страница узнаёт, что пользователь продолжил на телефоне, ещё до прихода подтверждения: QR-код отсканирован, страница открылась на телефоне, начат переход в мессенджер — страница на телефоне начинает его сама, а её кнопка — повторно, по нажатию. Последний шаг значит, что браузер начал открывать приложение, а не что оно открылось. Каждый такой шаг называет строка статуса. Скан называет, что дальше на телефоне: «QR-код отсканирован. Продолжайте в Telegram.» — у мессенджера, «QR-код отсканирован. Продолжите на телефоне, чтобы подтвердить по почте.» — у Email и «QR-код отсканирован. Продолжайте на телефоне.» — у QR-кода, общего для всех каналов. Строки, которые называют канал, — сообщения, их можно сформулировать для каждого канала: см. строки канала. Когда страница на телефоне открывает приложение сама, два последних шага приходят вместе, и строка статуса показывает только «Открывается …», не мигая обоими. На первом из них страница убирает выбор канала: вкладки, QR-коды и кнопки каналов вместе с инструкцией под заголовком. На их месте она показывает другую инструкцию — по умолчанию «Продолжите на телефоне и подтвердите вход в открывшемся приложении.» Предмет подтверждения, строка статуса и обратный отсчёт остаются. Под инструкцией стоит кнопка «Выбрать другой способ»: она возвращает выбор канала на той же странице, с тем же входом — для пользователя, который отсканировал не тем устройством или передумал. Следующий шаг, о котором сообщит телефон, в том числе прежний, снова покажет инструкцию. Как только канал ответил на старт — его бот отправил вопрос в чат, — кнопка уходит со страницы насовсем: вход с этого момента привязан к аккаунту в этом канале, и другой канал привёл бы только к отказу. Там, где строка статуса после этого говорит «Вы перешли в …», — у входа и у подтверждения одинаково, — вместе с выбором канала уходит и инструкция: на странице остаются заголовок, строка статуса, обратный отсчёт и кнопка отмены — «Отменить вход» или «Отменить подтверждение». Страница, перешедшая на опрос, ответа не слышит и кнопку оставляет. Перезагрузка страницы тоже возвращает выбор канала; когда вход истекает, уходит и инструкция, а показывается ссылка перезапуска. HopInstructionHtml заменяет текст ядра вашей разметкой:
appsettings.json
Настройка следует блоку в подвале во всех правилах, кроме одного: те же уровни (эта глобальная секция, запись клиента, тенант — не запись ui_config), пустое значение ничего не задаёт, тот же допустимый формат и тот же исход недопустимого значения, значение — Natural Key. Исключение — перевод вне формата: страница тогда показывает собственный текст ядра, а не пустоту, потому что блок стоит на месте выбора канала и пустой оставил бы пользователя без слова о том, что делать дальше. В лог уходит предупреждение с именем настройки и языком. Кнопка «Выбрать другой способ» в настройку не входит: она стоит рядом с вашей разметкой, а не внутри неё, и её подпись — такой же текст окна входа, как остальные. Собственного стиля у настройки нет. Оформляйте блок своей таблицей стилей (CustomCssPath) через его класс veriqa-hop-instruction; правила самой страницы задают только цвет текста, размер и отступы.

CSS-переменные

Страницы стилизуются через CSS-переменные с префиксом --veriqa-*. Их можно переопределить своим CSS. Ниже — основные имена; полный набор объявлен в таблице стилей пакета и включает, помимо перечисленных, шкалу отступов --veriqa-spacing-* и цвета служебных плашек:

Внешний CSS

Подключите свой файл стилей через CustomCssPath — он загружается после базовых стилей, и в нём можно переопределить любую переменную. При заданном CustomCssPath пресет игнорируется: оформление полностью определяет ваш CSS. Стили подключаются ко всем страницам, которые генерирует Veriqa: к окну входа, к странице подтверждения входа, к странице истёкшей ссылки и к страницам входа по email. Ваш CSS красит их одинаково — отдельной настройки для служебных страниц нет. Страница истёкшей ссылки всегда предлагает одно действие. Если у приложения задан InitiateLoginUri — его собственный адрес начала входа (ключ Client.InitiateLoginUri справочника конфигурации), — страница ведёт на него ссылкой «Начать вход заново»; адрес должен быть абсолютным https-URL. Без него страница показывает кнопку «Закрыть». Тексты этой страницы заменяются так же, как тексты окна входа, — см. Своя формулировка элемента страницы для одного приложения. Страница относится только ко входу: ссылка сценария входа, называющая подтверждение действия, ведёт на нейтральную страницу «Ссылка больше недоступна».
appsettings.json
Задавайте CssSriHash (Subresource Integrity), если стили подключаются с внешнего адреса — внешний ресурс на странице входа по умолчанию под запретом.

Конфигурации UI по клиенту (ui_config)

Помимо глобального оформления, можно задать именованные конфигурации UI и привязать их к конкретному OIDC-клиенту. Каталог записей — словарь Records секции Veriqa:UiConfigurations («код записи → оформление»), то есть полный путь записи — Veriqa:UiConfigurations:Records:<код>; запись переопределяет глобальное оформление для своего кода.
appsettings.json
  • DefaultUiConfig — код записи, применяемой по умолчанию для клиента.
  • AllowedUiConfigs — коды, которые клиенту разрешено запрашивать. Код из этого списка валиден и без записи в каталоге — тогда берётся глобальное оформление.

Локализация

Страница входа использует подход Natural Keys: ключ локализации — английский текст, базовый язык — en (перевод для него не нужен). Реестр поддерживаемых языков строится из locale-файлов, которые поставляет ваш хост: JSON-словари {язык}.json в wwwroot/locales (путь настраивается через Veriqa:Channels:Localization:LocalesPath) плюс базовый en. Из коробки страница отображается на английском; чтобы добавить язык, положите его {язык}.json в каталог локалей — изменения кода не требуются. Русский и китайский переводить не нужно вовсе: они уже есть в поставке — см. Готовые переводы ниже. Сам каталог необязателен: хост без него пишет на старте Locale files directory not found — channel messages are sent in the base language., и это предупреждение ожидаемо.

Готовые переводы

Весь каталог — всё, что пользователь читает при аутентификации, — публикуется отдельным пакетом без сборок: Veriqa.Core.ChannelLocales. В нём лежат en.json, ru.json, zh.json и pseudo.json (это локаль для проверки вёрстки, а не язык для продакшна: её можно получить явным Accept-Language, но как DefaultLanguage она отклоняется).
PackageReference
Сам по себе пакет язык не включает. Его targets кладут файлы рядом с вашей входной сборкой, в каталог veriqa-channel-locales/, и намеренно не в wwwroot/locales: каталог ядра не должен затирать ваш — их сравнивают, а не сливают. Пока не сделан один из двух шагов ниже, хост по-прежнему отвечает на базовом языке.
Использовать можно двумя способами:
  • скопировать нужные файлы из veriqa-channel-locales/ в свой каталог локалей. Дальше это ваши файлы, и любую формулировку в них можно править;
  • указать на него: задать в Veriqa:Channels:Localization:LocalesPath тот каталог, который разложил пакет. Относительный путь отсчитывается от content root хоста, поэтому указывайте путь, верный для вашего способа запуска, — или абсолютный. Править там нечего: следующая версия пакета заменит эти файлы целиком.
Тот же пакет служит списком ключей для хоста со своим каталогом: en.json задаёт полный набор ключей, а ключ, которого в ваших файлах нет, пользователь молча видит по-английски.

Какой язык получит пользователь

У страницы входа и у сообщений в канале разные источники языка, и различаться они могут вполне законно. Язык страницы входа определяет запрос: сначала OIDC-параметр ui_locales — явный выбор, сделанный на стороне доверяющей стороны, — затем Accept-Language браузера. Значение, не совпавшее ни с одним языком реестра, заменяется языком по умолчанию:
appsettings.json
DefaultLanguage валидируется при старте: значение должно входить в реестр (locale-файлы хоста + en), иначе приложение не стартует. Например, "DefaultLanguage": "ru" требует, чтобы хост поставлял wwwroot/locales/ru.json. Язык, на котором отрисована страница, сохраняется в транзакции, и его берёт каждая следующая страница и каждое сообщение этого входа. В том числе страница автопоста form_post, которой доставляется ответ авторизации: она отображается на нём, а не определяет язык по заголовку браузера заново. Accept-Language с языком по умолчанию остаётся запасным вариантом для ответов, у которых транзакции не было, — например, для ошибок, применяемых к redirect_uri. У подтверждения, созданного сервер-сервер, страницы нет вовсе — там язык задаёт поле locale запроса. Язык сообщения внутри канала, наоборот, определяет получатель. Канал, который знает язык профиля пользователя, сообщает его с каждым событием, и он приоритетнее языка браузера: пользователь с русским Telegram получит русский запрос со страницы, отрисованной по-английски. Канал, который ничего не сообщает, откатывается к локали транзакции, а при её отсутствии — к базовому языку. Email — третий случай, потому что его тексты читают не в мессенджере. Письмо входа уходит до того, как кто-либо ответил, поэтому профиля, у которого можно спросить язык, ещё нет: письмо формулируется на языке запроса, по которому его отправляли (Accept-Language того браузера), с откатом на локаль транзакции. А страница подтверждения, которую открывает magic link, поступает наоборот: она предпочитает локаль транзакции заголовку Accept-Language браузера почтового клиента — чтобы совпасть с окном входа, в котором пользователь начал. Так что одна установка вполне может говорить за один вход на двух языках, и это штатное поведение, а не ошибка настройки. Требуется от неё одно: чтобы каждый задействованный язык был в locale-файлах — язык, который никто не перевёл, молча заменяется базовым.

Тексты каналов и писем — те же locale-файлы

Через тот же каталог задаются не только тексты страницы входа, но и почти всё, что пользователь видит в мессенджере и в письме: подписи кнопок, статусы после ответа, видимые строки письма. Правило одно: ключ — английский текст, значение — то, что увидит пользователь. Чтобы изменить формулировку, добавьте ключ со своим значением в locale-файл нужного языка — код трогать не нужно. Основные ключи:
Какой из двух текстов подтверждения получит пользователь, решает шаблон сообщения, а не locale-файл. Квитанция входа — вид сообщения outcome-receipt-confirmed, и его шаблон сужается по устройству, на котором начат вход, — группой ByDevice со значениями desktop, mobile, tablet и unknown. Поставка объявляет короткий текст для любого устройства и текст с подсказкой возврата под ByDevice:mobile и ByDevice:tablet. Locale-файл только переводит каждый из них. Если вы объявляете квитанцию входа в конфигурации хоста без ByDevice, телефоны и планшеты всё равно получат поставляемый текст с подсказкой возврата — объявите и свои ступени ByDevice. Формулировка, заданная для одного приложения, тенанта или записи ui_config, отвечает за все устройства сама. Адреса и пример — Справочник конфигурации.
Это значения по умолчанию для всей установки: locale-файлы принадлежат хосту, один комплект на процесс. Текст «как у конкретного тенанта» задаётся не здесь: тексты страниц, которые рендерит Veriqa, для одного приложения или тенанта переформулирует его собственный словарь.
Каждая видимая фраза поставляемого письма входа — ключ локализации. Тело письма — и HTML, и текстовая часть — собственных формулировок не содержит: каждая фраза — слот локализованного текста, поэтому письмо целиком написано на языке получателя, а перевести письмо — значит поправить locale-файл. Подстановки внутри фразы нет: значение стоит рядом с подписью — The link is valid until: и время, The request came from: и браузер, система, регион, — а имя приложения идёт отдельной строкой под заголовком. Тема Sign in to {app} — единственный текст, который переводится целиком. То же верно для писем добора claims, включая claim-code-link-mail.Переведённая фраза ограничена 128 символами, как любое значение, пришедшее в продукт извне; более длинная обрезается. Значения, которые Veriqa вычисляет сама, — ссылка, код, срок действия — подставляются полностью, какой бы длины они ни были. Если вы задаёте своё тело письма, длинное предложение раскладывайте на несколько слотов, а не на один.

Разные переводы одной фразы: контекстный суффикс

Ключ — это английский текст, поэтому одна фраза даёт один перевод на язык. Если одну и ту же английскую фразу нужно перевести по-разному в разных местах (например, для одного канала — иначе, чем для остальных), к ключу добавляется контекстная метка через |:
ru.json
Что нужно знать:
  • метка — служебная, пользователь её не видит. Если перевода нет, показывается часть ключа до последнего | — то есть чистый английский текст, а не … | telegram;
  • не записывайте ключ сам в себя ("X | telegram": "X | telegram") — это единственный способ показать метку пользователю;
  • | зарезервирован под метку: обычный текст интерфейса не должен его содержать;
  • заводите контекст только при реальном расхождении. По умолчанию одна фраза — один ключ без суффикса; плодить контексты там, где перевод совпадает, не нужно.

Тексты, заданные настройкой, — тоже ключи локализации

Тексты, которые задаёт запись ui_config, проходят ту же резолюцию, что и встроенные: заданное значение и есть Natural Key. Отдельного «нелокализуемого» текста в продукте нет.
Текст подтверждения задаётся не полем записи, а шаблоном сообщения. Формулировка запроса подтверждения — это сообщение, и задаётся она лестницей его шаблона: Veriqa:MessageTemplates:confirmation-prompt:Templates (устройство ключа и его уровни — в Справочнике конфигурации). Правило этой секции на неё распространяется полностью: заданный текст — такой же Natural Key, локализацию он не обходит. Если формулировка нужна своя у конкретного приложения, задайте её в записи клиента (уровень Application), а не глобально.Поставляемая формулировка заканчивается советом If it was not you, decline the request. («Если это не вы — отклоните запрос.»), и вы вправе его переопределить. Заданная вами лестница заменяет текст целиком вместе с этой фразой, поэтому сформулируйте совет по-своему или уберите его. Подробнее — в Veriqa:MessageTemplates.То же сообщение — вопрос страницы Veriqa с кнопками «Да» и «Нет»: при входе страница спрашивает то же, что спросил бы чат, с теми же значениями в слотах. Чтобы страница спрашивала иначе, задайте лестницу по адресу confirmation-prompt:BySurface:core-page:Templates — формулировка в чате останется прежней. При подтверждении страница задаёт вопрос, с которым ваш сервер создал подтверждение. Заголовок страницы и обе кнопки переформулирует словарь текстов.
Что это значит на практике:
  • значение без записи в locale-файлах выводится как есть. Ключ — это и есть текст, поэтому промах ничего не ломает: пользователь видит ровно ту строку, которую вы задали, просто непереведённую. Для базового языка запись не нужна вообще;
  • чтобы текст перевёлся, заведите его ключ в своих locale-файлах — тех же wwwroot/locales/{язык}.json, что и остальные тексты. Каталог локалей принадлежит хосту, а хост — это вы: ключи ваших записей ui_config заводятся там наравне с продуктовыми.
Как задать значение, которое заведомо переводится. Отдельного маркера для этого нет — используется штатный контекстный суффикс (см. выше): значением настройки задаётся строка <текст> | <метка>, а перевод кладётся в locale-файлы.
appsettings.json
ru.json
Что нужно знать:
  • метка — служебная: всё после последнего | пользователь не видит. Значение Privacy | Terms выведется как Privacy — настройка, текст которой сам должен содержать |, такой способ не подходит;
  • промах не даёт отказа: без записи в locale-файле пользователь увидит Sign in to the portal — правильный текст, просто непереведённый. Ни метки, ни пустой строки, ни ошибки;
  • базовый текст выбираете вы: значение Политика | authpage без перевода на английский покажет англоязычному пользователю русский. Поведение предсказуемое, но базовым текстом разумно делать формулировку на базовом языке (en);
  • метка нужна не всегда. Если ваш текст и так уникален, переводите его без суффикса — ключом будет само значение. Метка страхует от совпадения с продуктовым ключом и разводит одну и ту же фразу по разным записям ui_config.
Заданное значение ищется в locale-файлах. Если оно случайно совпало с ключом продуктового текста — например, Title задан ровно как встроенный заголовок окна входа, — на неанглийских языках подставится продуктовый перевод, а не ваша строка. Если такой текст должен оставаться вашим, добавьте к значению контекстный суффикс: ключ перестанет совпадать с продуктовым, а пользователь увидит ту же строку до последнего |.

Своя формулировка элемента страницы для одного приложения

Locale-файл меняет текст для всей установки. Если одному приложению нужна своя формулировка встроенного элемента — например, форма обратной связи подтверждает обращение, а не вход, и вместо «Confirm in WhatsApp» ей нужно «Send in WhatsApp», — задайте её в словаре AuthPage.Texts этого приложения. Ключ записи — встроенный текст элемента: его английский текст, та же строка, что служит ему ключом в locale-файлах, в написании из перечня ниже. Значение — что показать вместо него.
appsettings.json
ru.json
Уровни. Словарь стоит на трёх уровнях: тенант (AuthPage:Texts в его записи), приложение (AuthPage:Texts в его записи Veriqa:OpenIddict:Clients) и запись ui_config (член texts; в appsettings.json — Veriqa:UiConfigurations:Records:<код>:Texts). Уровня всей установки нет: для этого есть locale-файлы. Уровни сливаются по записям: для каждого текста побеждает самый частный уровень, который заявил запись, а записи нижних уровней для других текстов остаются в силе. Тенант может переименовать одну кнопку, приложение — другую, и видны будут обе замены.
Уровень Tenant. Как и у блока в подвале, читатель записи тенанта из коробки не зарегистрирован — его пишет интегратор. Без него словарь берётся из записи клиента и записи ui_config.
Две формы записи:
  • строка — это ключ-замена. Она проходит через locale-файлы так же, как текст, заданный настройкой (раздел выше): страница ищет замену в locale-файле своего языка, а без перевода показывает её как есть. Контекстный суффикс | допустим и уместен — в примере метка feedback не даёт замене совпасть с продуктовым ключом;
  • объект — это готовые тексты по языкам. Мимо locale-файлов: страница показывает текст языка, на котором она выводится, как есть. Языки называйте так, как названы ваши locale-файлы (en, ru, zh); страница выводится на языке запроса, если ваши locale-файлы её переводят, и по-английски иначе. Язык, которого в объекте нет, получает штатный перевод встроенного текста, а не другой язык объекта: в примере выше пользователь с китайским языком увидит китайский перевод «Sign in with Email» из ваших locale-файлов.
Пустая строка, пустой объект и объект из одних пустых текстов ничего не заявляют — запись тогда берётся с уровня ниже. Слоты должны совпадать. Часть встроенных текстов несёт значения, которые подставляет страница: Link sent to {0}. Check your inbox., Confirm the address {address} to sign in to {brand_name}. Замена — строка или каждый текст объекта — обязана нести ровно те же слоты. Замена, которая теряет или добавляет слот, не применяется: страница показывает встроенный текст штатно. Исключение — название вашего приложения на Email-страницах. Они заполняют два слота: {brand_name} — бренд, которым приложение названо в письмах (BrandName; если его не задаёт ни один уровень — название приложения), и {app} — название приложения. В четырёх текстах ниже замена может нести любой из этих слотов, оба или ни одного, а остальные слоты по-прежнему должны совпадать: A sign-in to {brand_name} was requested. If it was not you, close this page., A confirmation was requested. If it was not you, close this page., Confirm the address {address} to sign in to {brand_name}. и If you did not sign in to {brand_name}, do not confirm the address. Запись под прежней формулировкой этих текстов со слотом {app} не совпадает ни с одним из них и не применяется. Кнопка мессенджера: фраза одного канала важнее шаблона. Кнопка — это шаблон Sign in with {0} при входе и Confirm in {0} при подтверждении. В слот подставляется название канала, одно на кнопке, на вкладке и в инструкции. Это встроенный текст <Name> | channel: у встроенного мессенджера <Name> — его бренд (Telegram | channel, WeChat | channel …), у стороннего канала — имя, которое он сообщает (Acme Chat | channel). Без перевода и без записи имя стороннего канала показывается так, как он его сообщает. Страница подставляет в шаблон английское название (Confirm in WhatsApp) и сначала ищет эту фразу:
  1. запись для фразы;
  2. запись для шаблона;
  3. перевод фразы в locale-файлах;
  4. перевод шаблона.
Запись для Confirm in {0} меняет кнопку всех каналов, запись для Confirm in WhatsApp — только этого канала. Так же locale-файл решает грамматику языка, которую шаблон не вмещает: турецкий файл переводит Confirm in {0} как {0} üzerinden onayla и точечно добавляет "Confirm in Viber": "Viber'de onayla". Запись для фразы действует у любого канала, кроме Email, в том числе у стороннего (Sign in with Acme Chat); название или фразу с : можно только перевести в locale-файле. В ответе API создания подтверждения название канала остаётся без перевода. Какие тексты открыты. Словарь действует на страницах, которые Veriqa показывает пользователю во время входа или подтверждения:
  • окно входа — на обеих страницах, которые его рендерят: сам вход и страница, открывающая подтверждение, — включая строки статуса, которые показывает его скрипт;
  • страница запуска hop-режима на телефоне (её заголовок «Sign in via …», инструкция и строка, возвращающая пользователя к окну входа) и строки, которые окно показывает на телефоне, открывшем вход по QR-коду, — исход и возврат к окну входа;
  • страница, которая спрашивает «Да» или «Нет» о входе или подтверждении, — её заголовок и обе кнопки (вопрос — сообщение, его формулировку задаёт шаблон confirmation-prompt);
  • страница входа через аккаунт провайдера на телефоне — строка под заголовком, кнопки ответа, строки ожидания и завершения, сообщения об ошибках и кнопка Close;
  • форма добора claims — её заголовок и пояснение над полями;
  • Email-страницы: страница, которую открывает magic link, — запрос входа или подтверждения, строка, в которую запрос входа превращается после «Продолжить вход», и строка быстрой ссылки, — страница, открывающая почтовое приложение для входа по письму, форма запроса письма входа и страница ссылки, подтверждающей адрес почты при доборе claims.
Окно входа: Sign in via trusted channel · Confirm via trusted channel · Scan the QR code or tap the button to sign in with {0} · Scan the QR code to sign in with {0} · Tap the button to sign in with {0} · Scan the QR code or tap the button to confirm in {0} · Scan the QR code to confirm in {0} · Tap the button to confirm in {0} · Enter your email to get a link · Enter your email to get a code · Enter your email to get a link and a code · Choose a channel, then scan its QR code or tap its button to sign in · Choose a channel, then scan its QR code to sign in · Choose a channel and tap its button to sign in · Choose a channel, then scan its QR code or tap its button to confirm · Choose a channel, then scan its QR code to confirm · Choose a channel and tap its button to confirm · Scan the QR code or tap a channel button to sign in · Scan the QR code to sign in · Tap a channel button to sign in · Scan the QR code or tap a channel button to confirm · Scan the QR code to confirm · Tap a channel button to confirm · Scan the QR code or tap your messaging app's button to sign in · Scan the QR code or tap your messaging app's button to confirm · Sign-in QR code · Any channel · {0} ▦ · Last used · Sign in with {0} · Confirm in {0} · Telegram | channel · WhatsApp | channel · Instagram | channel · Messenger | channel · WeChat | channel · Viber | channel · MAX | channel · фраза каждого из этих каналов в Sign in with {0} и Confirm in {0} (Sign in with Telegram … Confirm in MAX) · те же три текста каждого другого адаптера канала на хосте, кроме Email, — <имя> | channel, Sign in with <имя> и Confirm in <имя>, где <имя> — название, которое сообщает адаптер · Sign in with Email · Confirm with Email · Send confirmation email · Sign in via email link · Confirm via email link · Sign in with a code from email · Confirm with a code from email · Sign in via email · Confirm via email · OR · ← Back to QR code · ← Back · Email address · Get a link · Get a code · Send email · Send again · Link sent to {0}. Check your inbox. · Failed to send the link. Please try again. · Failed to send the mail. Try again later. · The code has been sent to {address} · Code from the email · Confirm · Failed to check the code. Please try again. · Email link opened. Confirm the sign-in. · Email link opened. Continue the confirmation. · If you have already sent the email, wait for the confirmation. It usually takes a few seconds. · Email received. Verifying the sender… · Sender verified. Completing sign-in… · Sender verified. Continuing the confirmation… · Sign-in has already started in another channel. · Confirmation has already started in another channel. · QR code scanned. Continue on your phone. · The page is open on your phone. · Continue on your phone and confirm in the app that has opened. · Choose another way · Remember how I sign in on this device · Remember how I confirm on this device · Always sign in with {0} on this device · Always confirm in {0} on this device · Choose another channel · Back to channel selection · Problem signing in · Problem confirming · This QR code was also scanned on another device. If that wasn't you, start over. · Complete the form on your phone · Waiting for confirmation… · Confirmed. Processing… · Sign-in successful! · This sign-in request has expired · Start the sign-in again · Cancel sign-in · Cancel confirmation · Sign-in declined · Authentication error · Send the code in the chat with the bot {0} if the bot has not sent you a confirmation · Send the code in the chat with the bot if the bot has not sent you a confirmation · Copy and open {0} · Copy · CopiedСтраница истёкшей сессии входа: Sign-in session expired · This sign-in link has expired or was already used. Please start the sign-in again from the application. · Close · You can close this tab. (её ссылка — Start the sign-in again, названа выше)Страница возврата в приложение (режим ответа form_post): Completing sign-in · Returning you to the application. If nothing happens, use the button below. · Continue. После успешного входа страница читает записи тенанта и приложения; запись ui_config до неё не доходит.Страницы телефона при входе по QR-коду: Sign in via {0} · Continue in {0} · The app should open by itself. If it does not, tap the button below. · The {0} app should open by itself. If it does not, tap the button below. · (общие с окном входа: Problem signing in, Problem confirming, Copy and open {0} — ссылка и кнопка запасного кода — и Continue in {0} — заголовок окна входа, открытого телефоном по QR-коду нескольких каналов, после нажатия канала) · Sign-in confirmed. Continue on the device where you started. · This sign-in is no longer active here. Check the device where you started. · Return to the sign-in window and confirm the sign-in there. (общая с Email-страницами: запись меняет её и на страницах телефона, и на странице magic link)Страница вопроса «Да/Нет»: Confirm your sign-in · Confirmation required · Yes · NoФорма добора claims: Complete your sign-in · Fill in the missing details to finish signing in.Страница входа через аккаунт провайдера: via {0} (строка под названием приложения, в слоте — имя канала) · Yes · No · Slide to answer Yes (ползунок, которым отвечают «Да») · Release to answer Yes (ползунок дотянут до конца, но ещё не отпущен) · Please wait a moment. · This request has ended. · This request was not found or has expired. · Your account was not confirmed by the provider. Open the link again to try once more. · This page is not available in this browser. · Something went wrong. Open the link again to try once more. · Close · You can close this tab.Кнопка под исходом — в окне входа, которое телефон открыл по QR-коду, на странице запуска hop-режима на телефоне и на страницах, которые показывают, чем закончились подтверждение и форма добора claims на устройстве, где подтверждали: Close · Return to {0} · You can close this tab. ({0} — название приложения; Close и You can close this tab. — общие со страницей истёкшей сессии входа, Email-страницами и страницей входа через аккаунт провайдера). Кнопка только закрывает вкладку. Подпись Return to {0} — когда страница открыта на устройстве того же типа, что и устройство, где начат вход (телефон, планшет или компьютер), и название приложения известно. В остальных случаях — Close. Подтверждение создаёт ваш сервер, тип устройства у него неизвестен, поэтому на его страницах всегда Close.Email-страницы: Sign-in request · A sign-in to {brand_name} was requested. If it was not you, close this page. · Continue signing in · Return to the sign-in window and confirm the sign-in there. · Cancel · Approve sign-in · Continue · Sign-in confirmed. Continue on the device where you started. · The link has expired. Request a new one. · The link has already been used. Request a new one. · The link is invalid or has expired. Request a new one. · Something went wrong. Try requesting a new link. · Confirmation required · A confirmation was requested. If it was not you, close this page. · Continue to confirmation · The sign-in link has been sent to {email_masked} · The confirmation link has been sent to {email_masked} · Send again · Failed to send the link. Check the address and try again. · The Email adapter Pull mode is disabled. · Sign in via email link · Sign in with a link · Enter your email — we will send you a sign-in link. · Sign in with a code from email · Sign in via email · Sign in with a code · Enter your email — we will send you a sign-in code. · Enter your email — we will send you a sign-in link and a code. · Confirm via email link · Confirm with a link · Enter your email — we will send you a confirmation link. · Confirm with a code from email · Confirm via email · Confirm with a code · Enter your email — we will send you a confirmation code. · Enter your email — we will send you a confirmation link and a code. · Session not found. Return to the sign-in page. · Email address · Get a link · Get a code · Send email · Failed to send the mail. Try again later. · The code has been sent to {address} · Code from the email · Confirm · Failed to check the code. Please try again. · Confirm your email address · Confirm the address {address} to sign in to {brand_name}. · If you did not sign in to {brand_name}, do not confirm the address. · Confirm the address · The address is confirmed. Return to the sign-in page. · This link no longer works. Request a new one on the sign-in page. · Close · You can close this tab.
Остальное сохраняет встроенные тексты: служебные страницы (страница ответа, которая отправляет результат в ваше приложение, и страница недоступной ссылки), страницы, которые показывают, чем закончилось подтверждение, и остальные тексты формы добора claims (поля, кнопки и строки статуса; и там и там переопределяется только кнопка под исходом из списка выше), подсказка адреса your@email.com и письма — формулировку письма задаёт его шаблон сообщения. Строки канала — сообщения, а не записи словаря. То, что окно и страница запуска говорят о канале, — «Вы перешли в Telegram…», «Открывается Telegram…», «QR-код отсканирован. Продолжайте в Telegram.», их формулировки для Email и подсказка под инструкцией hop-режима («На iPhone сначала может открыться страница браузера с двумя кнопками…»), — задают виды сообщений channel-answer-line, channel-launched-line, qr-scanned-line и hop-channel-hint. Формулируйте их, в том числе для отдельного канала, в MessageTemplates хоста, записи клиента, тенанта или ui_config. Запись этого словаря до них не доходит: о записи для их прежнего текста хост сообщает, как о любом тексте вне перечня. Один текст — один элемент везде. Запись меняет текст везде, где его показывает открытая страница: Sign in with {0} — кнопка и окна входа, и страницы запуска на телефоне, а Sign in via email link — и вкладка окна, и заголовок формы запроса ссылки. На неоткрытой странице тот же текст остаётся встроенным: запись для Confirmation required меняет страницу, которую открывает Email-ссылка подтверждения, страницу ошибки, которой эта ссылка отвечает, и страницу вопроса подтверждения, но не страницу с тем же заголовком, которая показывает, чем закончилось подтверждение. Выделенная настройка главнее словаря. Где текст задан собственной настройкой — Title, Instruction, BrandName, FooterHtml, HopInstructionHtml, — страница показывает его, а запись для встроенного текста, который он заменяет, не применяется. Словарь действует только там, где страница берёт свой встроенный текст. Неприменимая запись называется один раз. Запись для текста вне перечня выше и замена с несовпадающими слотами попадают в отчёт снимка конфигурации предупреждением с уровнем, записью и ключом конфигурации — при старте и снова при перезагрузке источника конфигурации, а не на каждой странице. Хост при этом стартует, и остальные записи этого клиента применяются. В этом же отчёте видны и переформулированные встроенные тексты: ключ — это английский текст, поэтому текст, который продукт переформулировал, получает новый ключ, а запись для старого ничего не находит. После обновления сверьтесь с отчётом и перенесите такие записи — и значения своих файлов локализации — на новые ключи. Из недавно переформулированного: кнопка письма в один тап (Send confirmation email), строка скана (QR code scanned. Continue on your phone.) и отказ по лимиту писем на адрес в форме добора claims. Страница magic link больше не спрашивает Do you confirm the sign-in? с Yes и No, а у страницы запуска на телефоне больше нет отдельной кнопки, которая только копирует запасной код. Если словарь не удалось разрешить вовсе (хранилище ui_config недоступно), страница рендерится со встроенными текстами, а в лог пишется предупреждение.

Точки расширения

Ключевые сервисы заменяются своей реализацией — регистрируйте их в блоке AddVeriqaAuthServer.

Рендерер страницы входа

Реализуйте IAuthPageRenderer для полного контроля над HTML страницы входа:
Свой рендерер получает окно входа и страницу, открывающую подтверждение. Страницу сканера режима hop, которую телефон открывает по hop-QR-коду, всегда рендерит встроенный рендерер: дизайн страницы и CSS-переменные на ней действуют, ваша разметка — нет. AuthPageRenderContext приходит с уже вычисленными значениями: Design — эффективный дизайн страницы (глобальная секция, переопределённая уровнями владения по полям), Title и Instruction — тексты, если их задал какой-то уровень (иначе null, и текст ваш), QrVisibility — эффективная видимость QR-кода. Свой рендерер ничего не складывает сам и потому не может потерять переопределение. Так же вычисленными приходят ещё пять членов, и свой рендерер должен исполнить каждый сам — встроенный это делает:
  • ChannelButtonVisibility — видимость кнопок каналов, уже согласованная с QrVisibility: пара, которая оставила бы устройство без того и другого, приходит как Always;
  • ChannelLayout — Tabs или Grid;
  • CancelForm — форма за кнопкой отмены («Отменить вход» в окне входа, «Отменить подтверждение» на странице, открывающей подтверждение) либо null, когда на этой странице кнопки нет. Выводите её формой POST на PathBase + CancelForm.ActionUrl с двумя скрытыми полями: session_id со значением SessionId и CancelForm.AntiforgeryFieldName со значением CancelForm.AntiforgeryToken;
  • OffersOutcomeClose и OutcomeCloseApplicationName — кнопка под исходом в окне входа, которое телефон открыл по QR-коду. При OffersOutcomeClose = true выводите скрытую кнопку, которая только закрывает вкладку, и показывайте её, когда транзакция закончилась успехом, отказом, сбоем или истечением. Подпись — Return to {0} с OutcomeCloseApplicationName на месте {0}, при null — Close. Если браузер оставил вкладку открытой, покажите строку You can close this tab.. Тексты берите через Texts, как остальные тексты страницы.
Ещё несколько членов работают на страницах, кроме окна входа:
  • NavigatesAway — false на странице подтверждения, которое создал ваш бэкенд: callback, на котором можно продолжить, там нет. Покажите исход на месте текстами TerminalConfirmedText, TerminalDeclinedText, TerminalExpiredText и TerminalErrorText, если они заданы, а переходите только на ConfirmationQuestionUrl, если он задан;
  • TransactionType — тип транзакции; свои тексты пишите о входе или о подтверждении по нему;
  • SubjectText — что подтверждается, простым текстом. Если значение задано, экранируйте его как HTML и покажите;
  • UnifiedQrCodeBase64 — один hop-QR-код на все каналы страницы. Показывайте его вместо QR-кодов каналов и заменяйте, когда наступит UnifiedQrExpiresAt; UnifiedQrWithChannelQrCodes и AnyChannelTabShowsChannelButtons говорят, оставить ли вкладки каналов и кнопки рядом с ним.
Title и Instruction приходят ключами локализации, а не готовым текстом (см. «Тексты, заданные настройкой, — тоже ключи локализации»). Встроенный рендерер прогоняет их через locale-файлы; свой рендерер делает то же вызовом IConfirmationPromptLocalizer.ResolveOrBaseText(значение, язык) — иначе заданный уровнем текст перестанет переводиться, а значение с контекстным суффиксом покажет метку. Приходят они ещё и сырыми, как и Hint канала: значение может нести разметку, и его никто не проверял. Встроенный рендерер проверяет каждое значение и откатывается к обычному тексту; свой рендерер либо HTML-кодирует значение перед выводом, либо проверяет его собственными правилами. Выведенное как есть, оно положит на вашу страницу всё, что задано настройкой.

Claims-маппер

Реализуйте IClaimsMapper чтобы самостоятельно сопоставлять разрешённую идентичность с OIDC claims:
UseClaimsMapper<T>() регистрирует маппер как scoped — по экземпляру на запрос авторизации. Поэтому scoped-зависимость (DbContext, unit of work, любой сервис со временем жизни на запрос) берётся прямо в конструктор, как IMyDirectory выше: IServiceScopeFactory не нужен. Встроенный маппер остаётся singleton — он без состояния и без зависимостей. ClaimsMappingContext говорит, для кого строятся claims: Атрибуция — это то, что нужно pairwise-субъекту (OIDC Core 1.0 §8.1): один и тот же пользователь получает разный sub для разных RP. Встроенный маппер её не использует — выдаваемый им sub глобален по всем RP.

Обработчик событий транзакции

Реализуйте ITransactionEventHandler, чтобы реагировать на события транзакций (например, подключать канал уведомлений при входе):
Обработчик добавляется рядом со встроенными, а не вместо них: порт потребляется как IEnumerable<ITransactionEventHandler>, поэтому каждое событие получают все зарегистрированные обработчики. Встроенные продолжают работать — окно входа по-прежнему получает событие завершения, журнал аудита — свои записи.

Идемпотентность создания транзакции

CreateTransactionRequest принимает пару IdempotencyKey + IdempotencyScope: повтор запроса с той же парой возвращает уже созданную транзакцию, а не заводит вторую (при расхождении параметров создания — отказ idempotency_key_conflict). Из встроенных точек входа пару заполняет POST /api/transaction/confirmation — создание транзакции подтверждения по client credentials: ключ берётся из поля idempotency_key тела запроса, а область — из аутентифицированного client_id, поэтому одинаковый ключ двух приложений означает два разных запроса. Повтор с тем же ключом отвечает той же транзакцией и заново собранной точкой входа. Браузерный authorization endpoint пару не заполняет: там повторный запрос означает новый вход, а не повтор прежнего. Если вы управляете движком напрямую, пару заполняете вы.

Дальше

Хранилища

Хранилище транзакций и база OpenIddict: InMemory / EF Core / Redis, PostgreSQL.

Контекст инициатора

Что показывается в подтверждении: кто и откуда инициировал вход.

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

Чек-лист перед выпуском в продакшн.

Быстрый старт .NET

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