Configuration & customization

​

Channels

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

​

Email: sending and receiving

• Pull (magic link) — Veriqa sends an email with a link, the user follows it. On by default (PullEnabled).
• Push (the one-tap email) — the user sends a pre-filled message to the inbound address, Veriqa processes the incoming message. Off by default (PushEnabled) — enable it together with the inbound setup and a sender verification policy. The flag is read at startup: restart the service after changing it.

{
  "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 is required when the channel is enabled — magic links and QR codes are built from it.
• Outbound:Smtp — SMTP for Pull mode (Port 587 = STARTTLS; UseSsl: true = implicit TLS, port 465). With credentials set, STARTTLS is mandatory unless RequireStartTls: false (default true). Keep the password in a secret store, not in appsettings.json.
• Inbound — inbound email for Push mode: InboundAddress, UsePlusAddressing (embeds the correlation token into an address like login+{token}@…), WebhookSecretToken to validate the provider webhook.
• VerificationPolicy — sender verification: DmarcAlignedPass (default), AllowListOnly (only the domains in AllowedDomains). The None value is forbidden in production.

​

Design presets and theme

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

​

QR code visibility

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

• A tablet counts as a desktop. The QR code is scanned by another device’s camera, so a device of uncertain type keeps the code rather than losing it.
• When device detection fails, the QR code is shown. The device is determined by the page itself, and any failure of that check — a blocked script, an unrecognized User-Agent — leaves the QR code and the tabs in place. A page whose only way in is a button the user cannot reach is worse than a QR code shown where it is useless.

​

Channel buttons

• The button for a messaging app — “Sign in with …” on a sign-in, “Confirm in …” on a confirmation — leads straight into it.
• Email with a mail-client button keeps that button, and the “Sign in via email link” link under it.
• Email with an address form gets a button of its own that reveals the form in place. A page whose only channel is this one shows the form straight away — there is nothing to choose.
• A channel hint appears under the button of its own channel.

​

Channel button visibility

{
  "Veriqa": {
    "AuthPageDesign": {
      "QrCode": {
        "ShowQrCode": "DesktopOnly"
      },
      "ChannelButton": {
        "ShowChannelButton": "MobileOnly"
      }
    }
  }
}

• The buttons that lead into a channel: “Sign in with …” or “Confirm in …” of every channel, a third-party one included, and Email’s “Send confirmation email”. With that one hidden, the Email panel keeps its QR code and the “Sign in via email link” link.
• Not the controls that stay on the page: the address form of Email, the button that reveals that form among the channel buttons and the links switching the two Email sections are shown whatever the value.
• The sign-in window and the page that opens a confirmation. The pages a phone gets after scanning a hop QR code keep their buttons whatever the value: there the button is the only way forward.

• A tablet does not count as a phone, exactly as under DesktopOnly: it gets the QR code and no button.
• When device detection fails, the button stays hidden — the opposite of the QR code, which stays shown. A blocked script or an unrecognized User-Agent leaves a phone without the buttons; the QR code, which every allowed pair keeps on such a page, is then the way in.

​

Allowed combinations of the two visibilities

​

The instruction follows both settings

• One channel — the first column; the channel is named by its icon and name.
• Several channels behind tabs — the wording of the selected tab: a channel tab, with one QR code and one button, takes the first column with that channel named. The button alone is a phone without the QR code, where the tabs turn into buttons, so that row comes from the second column.
• Several channels on screen at once — the grid, the buttons the server lays out — the second column.
• One QR code for several channels, which a page shows in hop mode. Under QrMode: Unified the page has no tabs and takes the last column. Under QrMode: UnifiedWithChannels the QR code sits on the “Any channel” tab, followed by a tab for each channel: a channel tab takes the first column, and the “Any channel” tab, where the user picks one of several messaging apps, reads Scan the QR code or tap your messaging app's button to sign in (… to confirm) in place of the first row of the last column. With ShowChannelButtonsOnAnyChannelTab set to false, that tab shows the QR code alone and reads Scan the QR code to sign in. On a phone that hides the QR code, the tabs turn into buttons and the page reads Tap a channel button to sign in.

• a replacement in AuthPage.Texts has to carry {0}, as every replacement of a text with a slot does; a translation in a locale file that drops it is shown as is, and the channel then goes unnamed;
• {0} goes in the text, never inside a tag. A wording that puts it into an attribute value — <a href="https://your-domain.com/help?c={0}" target="_blank"> — is shown as plain text, with a warning in the log (see Markup in the title, the instruction and a channel hint).

​

The page wording follows whether the QR code is shown

​

Channel layout

{
  "Veriqa": {
    "AuthPageDesign": {
      "ChannelLayout": "Grid"
    }
  }
}

• The card grows with the number of channels. Its width is the usual one column (420px) plus a column for every further channel, and never more than the window less the margins the card always keeps. Panels that do not fit a row wrap onto the next line — down to one per line on a narrow window.
• A panel holds what its tab would show: the QR code, the channel button (subject to ShowChannelButton), the Email form, the channel hint.
• There are no tabs in the markup. Each panel is a group labeled by the visible name of its channel, so a screen reader announces the channels rather than “tab 1 of 3”.

• a page of one channel;
• a page laid out as channel buttons — any device under ShowQrCode: Never, a phone under DesktopOnly;
• in hop mode, a page that shows one QR code for all its channels — also where that QR code sits on the “Any channel” tab before the channel tabs (QrMode: UnifiedWithChannels): its tabs stay tabs.

​

Cancel button

{
  "Veriqa": {
    "AuthPageDesign": {
      "Cancel": {
        "Enabled": false
      }
    }
  }
}

• The sign-in ends as declined by the user — the transaction fails with the reason declined_by_user, the same as a “No” on the web confirmation page.
• The browser returns to your application — to the redirect_uri of the request, with the standard error=access_denied, the state the request carried and the issuer identifier iss (RFC 9207), in the response mode it asked for (query, fragment or form_post). Your application handles it like any other declined sign-in. An ASP.NET Core client on AddOpenIdConnect has to be told where to send the user: without AccessDeniedPath the handler throws on access_denied and the return ends in an HTTP 500 — see step 5 of the .NET quickstart.
• A confirmation arriving from the channel at the same moment does not win: no authorization code is issued, and the application still receives access_denied.
• The chat where the question waits is told: when the sign-in was waiting for the user’s answer to a question already shown in a messaging app chat, that chat gets the same “Sign-in declined” receipt a press of the decline button gives. Where the platform can edit a sent message — Telegram, for one — the receipt replaces the question and its buttons go away; elsewhere — Instagram, Messenger, WhatsApp and the like — it arrives as a new message and the buttons of the question stay, a later press being answered with the same receipt. Nothing is sent when the question is not in a chat: with Email, or when it is asked on the web page. Whatever happens to the receipt, the application receives access_denied.

{
  "Veriqa": {
    "OpenIddict": {
      "Clients": [
        {
          "ClientId": "my-app",
          "Cancel": {
            "Enabled": false
          }
        }
      ]
    }
  }
}

​

Branding

{
  "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 — strictly #RRGGBB; an invalid value falls back to a neutral default. It only colors shared elements (the primary button, focus rings, the spinner).
• LogoUrl and BrandName together replace the product’s own mark. With neither of them set at any level, the brand row shows the red diamond and Veriqa. Setting either one replaces that mark as a whole: a name alone shows no diamond, a logo alone shows no Veriqa. An unset logo therefore does not mean “no brand row” — for a page without one, use the Minimal preset. Pages other than the sign-in window (web confirmation, an expired sign-in, the email pages) show no brand row at all.
• BrandName — the name beside the logo, in place of the product’s own wordmark. The two are resolved independently: set either one alone and the page shows what there is — the name alone, the logo alone, or both. Unlike the logo the name has no per-theme variant (an image cannot repaint itself for a dark page, text takes the page’s color), so BrandNameByTheme does not exist. A blank value sets nothing: the name then comes from the level below. The value is plain text — it is encoded on output — and a localization key (see Texts set in configuration).
• PrimaryColorByTheme and LogoUrlByTheme set the value for a single theme (light, dark). A theme without a value of its own takes the neighboring shared key (PrimaryColor, LogoUrl). With Theme: Auto the browser picks the theme, and both values — the light one and the dark one — travel to the page.
• Messenger brand colors are never recolored, in any preset.

​

Footer block of the sign-in page

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

​

What the markup may contain

• text — any characters except < and >. A bare & is fine; a bare > is not, write it as >;
• tags a, span, div, p, strong, em, and the void br (<br>, <br/>, <br /> — there is no </br>). Names of tags and attributes are case-insensitive;
• attributes href, target, rel and class, each at most once per tag, with the value in double quotes and free of ", <, >. Anything else — style, id, any on* handler — is refused, and so are single-quoted and unquoted values;
• no class name of the page itself: a class is refused when one of its names is veriqa or begins with veriqa-, in any letter case and after character references are decoded. A name that merely starts with the word — veriqable — is fine, and so is an empty class;
• every link carries href and target="_blank". The address is judged in the form the browser reads it — after character references are decoded — and must be https://…, http://… or a root-relative /path. A protocol-relative //host, a javascript: or mailto: address, a backslash or a control character inside the address are refused;
• the tags are balanced: a closing tag closes the innermost open one, and none stays open at the end;
• comments, <!DOCTYPE and any tag outside the list are refused.

​

What an invalid value does

​

Translating the block

{
  "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>"
}

​

Markup in the title, the instruction and a channel hint

• the title — the Title of a ui_config record, or your wording of the built-in title in AuthPage.Texts or in a locale file;
• the instruction under it — the Instruction of a record, or your wording of a built-in instruction;
• a channel hint — an entry of Veriqa:ChannelDisplay:Hints.

{
  "Veriqa": {
    "UiConfigurations": {
      "Records": {
        "brandA": {
          "Title": "Sign in to <em>Acme</em>",
          "Instruction": "Confirm the sign-in to <strong>Acme</strong>"
        }
      }
    },
    "ChannelDisplay": {
      "Hints": {
        "whatsapp": "Send the message <strong>as it is</strong>"
      }
    }
  }
}

• tags span, strong, em, a and the void br. div and p are refused here: the text already sits inside a heading or a paragraph;
• attributes href, target, rel and class, under the rules of the footer block — double quotes, at most once per tag, nothing else;
• every link carries href and target="_blank", for the same reason: a link that opens in place ends the sign-in running on the page;
• no class name of the page itself — veriqa and anything beginning with veriqa- are refused;
• no img and no svg. An icon is a span with a class of yours, drawn by your own stylesheet (CustomCssPath): <span class="acme-mark"></span>. Attaching a stylesheet switches the design preset off — see External CSS.

​

Instruction after the scan

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

​

CSS variables

:root {
  /* Primary — neutral canon per theme (light: #111827, dark: #f9fafb);
     the client color applies only in the Branded preset */
  --veriqa-primary: #111827;
  --veriqa-on-primary: #ffffff;
  /* Surfaces and background (light theme) */
  --veriqa-bg: #ffffff;
  --veriqa-surface: #f9f9fa;
  --veriqa-surface-variant: #e2e2e3;
  --veriqa-surface-container: #eeeeef;
  /* Text */
  --veriqa-text: #1a1c1d;
  --veriqa-muted: #4c4546;
  --veriqa-soft: #767071;
  /* Semantic colors */
  --veriqa-success: #16a34a;
  --veriqa-error: #dc2626;
  --veriqa-warning: #eab308;
  /* Radii, typography, animation */
  --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;
}

​

External CSS

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

​

Per-client UI configurations (ui_config)

{
  "Veriqa": {
    "UiConfigurations": {
      "Records": {
        "brandA": {
          "Preset": "Branded",
          "PrimaryColor": "#FF5500",
          "LogoUrl": "https://your-domain.com/logo.png",
          "BrandName": "Acme",
          "Title": "Sign in",
          "TtlSeconds": 300
        }
      }
    },
    "OpenIddict": {
      "Clients": [
        {
          "ClientId": "my-app",
          "DefaultUiConfig": "brandA",
          "AllowedUiConfigs": [ "brandA" ]
        }
      ]
    }
  }
}

• DefaultUiConfig — the record code applied by default for the client.
• AllowedUiConfigs — codes the client is allowed to request. A code from this list is valid even without a catalog record — the global look is then used.

​

Localization

​

Ready-made translations

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

• copy the files you need out of veriqa-channel-locales/ into your own locales directory. They are yours from then on, and you are free to edit any wording in them;
• point at it: set Veriqa:Channels:Localization:LocalesPath to the directory the package lays down. A relative path is resolved from the host’s content root, so set a path that is right for the way you run the application — or an absolute one. Nothing there is yours to edit: the next version of the package replaces those files entirely.

​

Which language a user gets

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

​

Channel and email texts — the same locale files

​

One phrase, two translations: the context suffix

{
  "Sign-in declined ❌": "Вход отклонён ❌",
  "Sign-in declined ❌ | telegram": "Вход в Telegram отклонён ❌"
}

• the label is metadata — the user never sees it. With no translation available, the part of the key before the last | is shown, i.e. the clean English text, not … | telegram;
• never map a key to itself ("X | telegram": "X | telegram") — that is the one way to put the label in front of a user;
• | is reserved for the label: ordinary UI text must not contain it;
• add a context only on a real divergence. By default one phrase is one key with no suffix; there is no value in contexts whose translations coincide.

​

Texts set in configuration are localization keys too

• a value with no locale entry is shown as is. The key IS the text, so a miss breaks nothing: the user sees exactly the string you set, merely untranslated. The base language needs no entry at all;
• to have the text translated, add its key to your locale files — the same wwwroot/locales/{lang}.json as every other text. The locales directory is a host asset, and the host is you: the keys of your ui_config records go in there alongside the product ones.

{
  "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": "Выберите канал"
}

• the label is metadata: everything after the last | is invisible to the user. The value Privacy | Terms renders as Privacy — a setting whose own text has to contain | does not fit this convention;
• a miss is not a failure: with no locale entry the user sees Sign in to the portal — the right text, merely untranslated. No label, no blank, no error;
• you choose the base text: the value Политика | authpage with no English translation shows an English-speaking user Russian. The behavior is predictable, but the base text is best written in the base language (en);
• the label is not always needed. A text of yours that is already unique can be translated with no suffix — the value itself is the key. The label guards against colliding with a product key and separates one phrase across different ui_config records.

​

Rewording a page element for one application

{
  "Veriqa": {
    "OpenIddict": {
      "Clients": [
        {
          "ClientId": "site-feedback",
          "AuthPage": {
            "Texts": {
              "Confirm in WhatsApp": "Send in WhatsApp | feedback",
              "Sign in with Email": { "en": "Confirm via Email", "ru": "Подтвердить через Email" }
            }
          }
        }
      ]
    }
  }
}

{
  "Send in WhatsApp | feedback": "Отправить в WhatsApp"
}

• a string is a replacement key. It goes through the locale files exactly like a text set in configuration: the page looks the replacement up in the locale file of its language, and with no translation shows it as is. The context suffix | is allowed and advisable — above, feedback keeps the replacement from colliding with a product key;
• an object holds ready-made texts by language. They bypass the locale files: the page shows the text of the language it renders in as is. Name the languages the way your locale files are named (en, ru, zh); the page renders in the language of the request when your locale files translate it, and in English otherwise. A language the object does not name gets the regular translation of the built-in text, not another language of the object — in the example above a user reading Chinese gets the Chinese translation of “Sign in with Email” from your locale files.

1. an entry for the phrase;
2. an entry for the template;
3. a translation of the phrase in the locale files;
4. a translation of the template.

• the sign-in window — on both pages that render it, the sign-in itself and the page that opens a confirmation — including the status lines its script shows;
• the launch page of hop mode on the phone (its heading “Sign in via …”, its instruction, the status line once the transition has started and the line that sends the user back to the sign-in window) and the lines the window shows on a phone that opened a sign-in by its QR code — the outcome and the way back to the sign-in window;
• the email pages: the page the magic link opens — the request of a sign-in and the line it turns into after “Continue signing in”, the “Continue” page of a confirmation and the line of the fast link — the page that opens the mail app for a sign-in by email, the form that requests a sign-in link, and the page of the link that confirms an email address during claims completion.

​

Extension points

​

Sign-in page renderer

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

// Registration
authServer.UseAuthPageRenderer<MyAuthPageRenderer>();

• ChannelButtonVisibility — the visibility of the channel buttons, already reconciled with QrVisibility: a pair that would leave a device with neither arrives as Always;
• ChannelLayout — Tabs or Grid;
• CancelForm — the form behind “Cancel sign-in”, or null when this page offers no such button. Render it as a POST form to PathBase + CancelForm.ActionUrl with two hidden fields: session_id carrying SessionId, and CancelForm.AntiforgeryFieldName carrying CancelForm.AntiforgeryToken.

​

Claims mapper

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)
        };

        // Extra channel claims live in the resolvedIdentity.Claims dictionary
        if (resolvedIdentity.Claims?.TryGetValue("name", out var name) is true)
        {
            claims.Add(new(ClaimTypes.Name, name));
        }

        // The mapping runs on the request thread, so enriching the claims from your own
        // database or directory is a plain await — no sync-over-async is needed
        var profile = await directory.LoadAsync(resolvedIdentity.Subject, cancellationToken);
        claims.Add(new(ClaimTypes.Role, profile.Role));

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

// Registration
authServer.UseClaimsMapper<MyClaimsMapper>();

​

Transaction event handler

authServer.AddTransactionEventHandler<MyTransactionEventHandler>();

​

Idempotent transaction creation

​

Next steps