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

​

Каналы

authServer.AddChannelAdapters(adapters =>
{
    adapters.AddTelegram();
    adapters.AddWhatsApp();
    adapters.AddMax();
    adapters.AddEmail();
});

​

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

• Pull (magic link) — Veriqa отправляет письмо со ссылкой, пользователь переходит по ней. Включён по умолчанию (PullEnabled).
• Push (письмо в один тап) — пользователь отправляет готовое письмо на входящий адрес, Veriqa обрабатывает входящее. Выключен по умолчанию (PushEnabled) — включается вместе с настройкой приёма и политикой верификации отправителя. Флаг читается при старте: после его изменения сервис нужно перезапустить.

{
  "Veriqa": {
    "Channels": {
      "Email": {
        "Enabled": true,
        "InboundVerification": "shared_secret",
        "PublicBaseUrl": "https://your-domain.com",
        "PreferredMode": "Push",
        "PullEnabled": true,
        "PushEnabled": false,
        "Outbound": {
          "Smtp": {
            "Host": "smtp.your-provider.com",
            "Port": 587,
            "UseSsl": false,
            "Username": "…",
            "Password": "…"
          }
        },
        "Inbound": {
          "Provider": "Webhook",
          "InboundAddress": "login@your-domain.com",
          "UsePlusAddressing": true,
          "VerificationPolicy": "DmarcAlignedPass",
          "WebhookSecretToken": "…"
        }
      }
    }
  }
}

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

​

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

{
  "Veriqa": {
    "AuthPageDesign": {
      "Preset": "Default",
      "Theme": "Auto"
    }
  }
}

​

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

{
  "Veriqa": {
    "AuthPageDesign": {
      "QrCode": {
        "ShowQrCode": "DesktopOnly"
      }
    }
  }
}

• Планшет считается десктопом. QR сканируют камерой другого устройства, поэтому сомнительное устройство код сохраняет, а не теряет.
• При промахе определения устройства QR показывается. Устройство определяет сама страница, и любой сбой этой проверки — заблокированный скрипт, нераспознанный User-Agent — оставляет QR и вкладки на месте. Страница, единственный вход на которой — недоступная пользователю кнопка, хуже, чем QR там, где он бесполезен.

​

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

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

​

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

​

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

{
  "Veriqa": {
    "AuthPageDesign": {
      "Preset": "Branded",
      "PrimaryColor": "#FF5500",
      "LogoUrl": "https://your-domain.com/logo.png",
      "BrandName": "Acme",
      "PrimaryColorByTheme": { "dark": "#FF8A3D" },
      "LogoUrlByTheme": { "dark": "https://your-domain.com/logo-dark.png" }
    }
  }
}

• PrimaryColor — строго формат #RRGGBB; невалидное значение откатывается на нейтральный дефолт. Красит только общие элементы (основную кнопку, фокус-рамки, спиннер).
• LogoUrl и BrandName вместе заменяют собственный знак продукта. Если ни один уровень не задал ни того, ни другого, строка бренда показывает красный ромб и Veriqa. Заданное любое одно значение заменяет этот знак целиком: одно имя — без ромба, один логотип — без Veriqa. Поэтому незаданный логотип не означает «без строки бренда» — страница без неё задаётся пресетом Minimal. Страницы, кроме окна входа (веб-подтверждение, истёкший вход, страницы писем), строки бренда не выводят вовсе.
• BrandName — имя рядом с логотипом, вместо собственной подписи продукта. Логотип и имя резолвятся независимо: задайте любое одно, и страница покажет то, что есть, — только имя, только логотип или оба. В отличие от логотипа имя по теме не режется (картинка не может перекраситься под тёмную страницу, а текст берёт цвет страницы), поэтому BrandNameByTheme не существует. Пустое значение не задаёт ничего: имя тогда берётся с уровня ниже. Значение — обычный текст (выводится экранированным) и ключ локализации (см. Локализацию).
• PrimaryColorByTheme и LogoUrlByTheme задают значение для конкретной темы (light, dark). Тема без своего значения берёт соседний общий ключ (PrimaryColor, LogoUrl). При Theme: Auto тему выбирает браузер, и на страницу уезжают оба значения — светлое и тёмное.
• Фирменные цвета каналов (Telegram, WhatsApp, MAX) не перекрашиваются ни в одном пресете.

​

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

{
  "Veriqa": {
    "AuthPageDesign": {
      "FooterHtml": "<a href=\"https://your-domain.com/privacy\" target=\"_blank\">Privacy</a> · <a href=\"/terms\" target=\"_blank\" rel=\"noopener\">Terms</a>"
    }
  }
}

​

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

• текст — любые символы, кроме < и >. Голый & допустим, голый > — нет, пишите >;
• теги 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 и любой тег вне списка отвергаются.

​

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

​

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

{
  "Veriqa": {
    "AuthPageDesign": {
      "FooterHtml": "<a href=\"/privacy\" target=\"_blank\">Privacy</a> | authpage"
    }
  }
}

{
  "<a href=\"/privacy\" target=\"_blank\">Privacy</a> | authpage": "<a href=\"/privacy\" target=\"_blank\">Конфиденциальность</a>"
}

​

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

{
  "Veriqa": {
    "AuthPageDesign": {
      "HopInstructionHtml": "<p>Check your phone: <strong>confirm in the messenger</strong> that has just opened.</p>"
    }
  }
}

​

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

:root {
  /* Primary — нейтральный канон по теме (светлая: #111827, тёмная: #f9fafb);
     клиентский цвет применяется только в пресете Branded */
  --veriqa-primary: #111827;
  --veriqa-on-primary: #ffffff;
  /* Поверхности и фон (светлая тема) */
  --veriqa-bg: #ffffff;
  --veriqa-surface: #f9f9fa;
  --veriqa-surface-variant: #e2e2e3;
  --veriqa-surface-container: #eeeeef;
  /* Текст */
  --veriqa-text: #1a1c1d;
  --veriqa-muted: #4c4546;
  --veriqa-soft: #767071;
  /* Семантические цвета */
  --veriqa-success: #16a34a;
  --veriqa-error: #dc2626;
  --veriqa-warning: #eab308;
  /* Скругления, типографика, анимации */
  --veriqa-radius: 8px;
  --veriqa-radius-lg: 12px;
  --veriqa-font-family: system-ui, -apple-system, "Segoe UI", Roboto, Arial, sans-serif;
  --veriqa-font-mono: "JetBrains Mono", Consolas, monospace;
  --veriqa-transition-fast: 160ms ease;
}

​

Внешний CSS

{
  "Veriqa": {
    "AuthPageDesign": {
      "CustomCssPath": "/css/veriqa-custom.css",
      "CssSriHash": "sha384-..."
    }
  }
}

​

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

{
  "Veriqa": {
    "UiConfigurations": {
      "Records": {
        "brandA": {
          "Preset": "Branded",
          "PrimaryColor": "#FF5500",
          "LogoUrl": "https://your-domain.com/logo.png",
          "BrandName": "Acme",
          "Title": "Вход в кабинет",
          "TtlSeconds": 300
        }
      }
    },
    "OpenIddict": {
      "Clients": [
        {
          "ClientId": "my-app",
          "DefaultUiConfig": "brandA",
          "AllowedUiConfigs": [ "brandA" ]
        }
      ]
    }
  }
}

• DefaultUiConfig — код записи, применяемой по умолчанию для клиента.
• AllowedUiConfigs — коды, которые клиенту разрешено запрашивать. Код из этого списка валиден и без записи в каталоге — тогда берётся глобальное оформление.

​

Локализация

​

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

<PackageReference Include="Veriqa.Core.ChannelLocales" Version="0.6.0" />

• скопировать нужные файлы из veriqa-channel-locales/ в свой каталог локалей. Дальше это ваши файлы, и любую формулировку в них можно править;
• указать на него: задать в Veriqa:Channels:Localization:LocalesPath тот каталог, который разложил пакет. Относительный путь отсчитывается от content root хоста, поэтому указывайте путь, верный для вашего способа запуска, — или абсолютный. Править там нечего: следующая версия пакета заменит эти файлы целиком.

​

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

{
  "Veriqa": {
    "Localization": {
      "DefaultLanguage": "en"
    }
  }
}

​

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

​

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

{
  "Sign-in confirmed ✅": "Вход подтверждён ✅",
  "Sign-in confirmed ✅ | telegram": "Вход в Telegram подтверждён ✅"
}

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

​

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

• значение без записи в locale-файлах выводится как есть. Ключ — это и есть текст, поэтому промах ничего не ломает: пользователь видит ровно ту строку, которую вы задали, просто непереведённую. Для базового языка запись не нужна вообще;
• чтобы текст перевёлся, заведите его ключ в своих locale-файлах — тех же wwwroot/locales/{язык}.json, что и остальные тексты. Каталог локалей — ассет хоста, а хост это вы: ключи ваших записей ui_config заводятся там наравне с продуктовыми.

{
  "Veriqa": {
    "UiConfigurations": {
      "Records": {
        "brandA": {
          "Title": "Sign in to the portal | brandA",
          "Instruction": "Choose a channel | brandA"
        }
      }
    }
  }
}

{
  "Sign in to the portal | brandA": "Вход в портал",
  "Choose a channel | brandA": "Выберите канал"
}

• метка — служебная: всё после последнего | пользователь не видит. Значение Privacy | Terms выведется как Privacy — настройка, текст которой сам должен содержать |, этой идиоме не подходит;
• промах не даёт отказа: без записи в locale-файле пользователь увидит Sign in to the portal — правильный текст, просто непереведённый. Ни метки, ни пустой строки, ни ошибки;
• базовый текст выбираете вы: значение Политика | authpage без перевода на английский покажет англоязычному пользователю русский. Поведение предсказуемое, но базовым текстом разумно делать формулировку на базовом языке (en);
• метка нужна не всегда. Если ваш текст и так уникален, переводите его без суффикса — ключом будет само значение. Метка страхует от совпадения с продуктовым ключом и разводит одну и ту же фразу по разным записям ui_config.

​

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

​

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

public sealed class MyAuthPageRenderer : IAuthPageRenderer
{
    public string RenderAuthPage(AuthPageRenderContext context) => "<html>...</html>";
}

// Регистрация
authServer.UseAuthPageRenderer<MyAuthPageRenderer>();

​

Claims-маппер

public sealed class MyClaimsMapper(IMyDirectory directory) : IClaimsMapper
{
    public async Task<Result<IReadOnlyList<Claim>>> MapToClaimsAsync(
        ResolvedIdentitySnapshot resolvedIdentity,
        CompletionSnapshot completion,
        ClaimsMappingContext context,
        CancellationToken cancellationToken = default)
    {
        var claims = new List<Claim>
        {
            new(ClaimTypes.NameIdentifier, resolvedIdentity.Subject)
        };

        // Дополнительные claims канала лежат в словаре resolvedIdentity.Claims
        if (resolvedIdentity.Claims?.TryGetValue("name", out var name) is true)
        {
            claims.Add(new(ClaimTypes.Name, name));
        }

        // Маппинг идёт на потоке запроса, поэтому обогащение claims из своей БД или каталога —
        // обычный await, без sync-over-async
        var profile = await directory.LoadAsync(resolvedIdentity.Subject, cancellationToken);
        claims.Add(new(ClaimTypes.Role, profile.Role));

        return Result<IReadOnlyList<Claim>>.Success(claims.AsReadOnly());
    }
}

// Регистрация
authServer.UseClaimsMapper<MyClaimsMapper>();

​

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

authServer.AddTransactionEventHandler<MyTransactionEventHandler>();

​

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

​

Дальше