Skip to main content
A Veriqa sign-in usually starts on the desktop and is confirmed in a trusted channel on the phone. So that the user can tell they are confirming their own sign-in (and not someone else’s attempt), Veriqa adds an initiator context to the confirmation message — a short summary of who started the transaction and from where.
Initiator context is a hint for the user before confirming, not an access decision. It does not replace security checks: the transaction is still bounded by TTL, one-time use and rate limiting.

​
What is shown

The set of fields is defined by DisplayFields. Available fields: All four fields are shown by default.

​
Where the data comes from

The context snapshot is built when the transaction starts (/connect/authorize) from the request:
  • IP address — from the connection (best-effort; honors forwarded headers behind a trusted proxy).
  • Browser and OS — by parsing the User-Agent.
  • Region — by IP geolocation via an offline database (no calls to online services on the trust path).
Geolocation requires two things the base packages do not carry: the satellite package Veriqa.Core.AuthServer.MaxMind and a local GeoIP database (MaxMind .mmdb or compatible). With the package missing or no database configured, the geo fields stay empty and the rest of the context is shown as usual (graceful degradation). The standalone image already carries the package; the database is always yours to mount. The raw User-Agent is not stored by default.
Collection is on by default. Enabled, CollectIpAddress, CollectUserAgent and CollectGeoLocation all ship as true. What that means in practice — where each value is stored, for how long, and how to switch the collection off — is in Security and data handling.

​
Configuration

The Veriqa:InitiatorContext section:
appsettings.json
  • Enabled (default true) — the global switch. When false, no snapshot is built and behavior is unchanged.
  • CollectIpAddress / CollectUserAgent / CollectGeoLocation — what to collect (all default true).
  • StoreRawUserAgent — whether to keep the raw User-Agent (default false).
  • GeoIp.Provider — OfflineDatabase (offline .mmdb); GeoIp.DatabasePath — path to the database.
The GeoIp keys switch nothing on until the application has a provider that reads the database. It arrives as a satellite package — the core pulls no GeoIP library transitively:
Without it the host starts as usual and, with CollectGeoLocation: true, writes a startup warning carrying the code initiator_context_geoip_unavailable. On the standalone image the package is already included and switched on by GeoIp.DatabasePath. The database is not part of the image — MaxMind’s EULA covers the data, so you download it yourself and mount it read-only:
A path to a missing or unreadable file does not stop the container: the provider logs GeoIP database is not open and the geo fields stay empty.

​
Per-client configuration

Display is configured per OIDC client through the client’s fields in configuration. A value of null means “inherit the global default”. An application can only narrow the top-level field set, never widen it.
appsettings.json
  • InitiatorContextEnabled — whether to show the context in the confirmation for this client (controls display; snapshot collection is governed globally).
  • InitiatorContextDisplayFields — the narrowed field set for this client.

​
Next steps

How the auth flow works

Where the initiator context is built in the flow.

Preparing for production

The pre-production checklist.