> ## Documentation Index
> Fetch the complete documentation index at: https://veriqa.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

Вход в Veriqa обычно начинается на десктопе, а подтверждается в доверенном канале на телефоне.
Чтобы пользователь понимал, что подтверждает **именно свой** вход (а не чужую попытку), Veriqa
добавляет в сообщение подтверждения **контекст инициатора** — краткую сводку о том, кто и откуда
запустил транзакцию.

<Note>
  Контекст инициатора — это подсказка для пользователя перед подтверждением, а не решение о
  доступе. Он не заменяет проверки безопасности: транзакция всё равно ограничена TTL, one-time
  использованием и rate limiting.
</Note>

## Что показывается

Набор полей задаётся `DisplayFields`. Доступные поля:

| Поле | Значение |
| - | - |
| `application` | Имя клиентского приложения, инициировавшего вход (`DisplayName` OIDC-клиента) |
| `browser` | Браузер инициатора (из User-Agent) |
| `os` | ОС / платформа инициатора (из User-Agent) |
| `region` | Приблизительный регион (город, страна) по IP |

По умолчанию показываются все четыре поля.

## Откуда берутся данные

Снимок контекста формируется на старте транзакции (`/connect/authorize`) из данных запроса:

* **IP-адрес** — из соединения (best-effort; учитывает forwarded-заголовки за доверенным прокси).
* **Браузер и ОС** — разбором `User-Agent`.
* **Регион** — геолокацией по IP через **офлайн**-базу (без обращения к онлайн-сервисам в
  trust-path).

<Note>
  Геолокация требует двух вещей, которых нет в базовой поставке: сателлитного пакета
  `Veriqa.Core.AuthServer.MaxMind` и локальной GeoIP-базы (MaxMind `.mmdb` или совместимой). Если
  пакет не подключён или база не задана — геополя остаются пустыми, остальной контекст показывается
  как обычно (graceful degradation). Сырой `User-Agent` по умолчанию не сохраняется.
</Note>

<Note>
  **Сбор включён по умолчанию.** `Enabled`, `CollectIpAddress`, `CollectUserAgent` и
  `CollectGeoLocation` поставляются как `true`. Что это значит на практике — где каждое значение
  лежит, сколько живёт и как сбор выключить — в
  [Безопасности и обработке данных](/docs/ru/guides/data-handling#умолчания-сбора).
</Note>

## Конфигурация

Секция `Veriqa:InitiatorContext`:

```json appsettings.json theme={null}
{
  "Veriqa": {
    "InitiatorContext": {
      "Enabled": true,
      "CollectIpAddress": true,
      "CollectUserAgent": true,
      "CollectGeoLocation": true,
      "StoreRawUserAgent": false,
      "DisplayFields": [ "application", "browser", "os", "region" ],
      "GeoIp": {
        "Provider": "OfflineDatabase",
        "DatabasePath": "/data/geoip/GeoLite2-City.mmdb"
      }
    }
  }
}
```

* `Enabled` (по умолчанию `true`) — глобальный включатель. При `false` снимок не формируется, и
  поведение системы не меняется.
* `CollectIpAddress` / `CollectUserAgent` / `CollectGeoLocation` — что собирать (все по умолчанию `true`).
* `StoreRawUserAgent` — хранить ли сырой User-Agent (по умолчанию `false`).
* `GeoIp.Provider` — `OfflineDatabase` (офлайн `.mmdb`); `GeoIp.DatabasePath` — путь к базе.

Сами ключи `GeoIp` ничего не включают, пока в приложении нет провайдера, который читает базу. Он
приезжает сателлитным пакетом — ядро не тащит GeoIP-библиотеку транзитивно:

```bash theme={null}
dotnet add package Veriqa.Core.AuthServer.MaxMind
```

```csharp theme={null}
builder.Services.AddMaxMindGeoIp();
```

Без него хост стартует как обычно, а при `CollectGeoLocation: true` пишет в лог старта
предупреждение с кодом `initiator_context_geoip_unavailable`.

## Настройка на уровне клиента

Показ контекста настраивается **на конкретный OIDC-клиент** — полями клиента в конфигурации.
Значение `null` означает «наследовать глобальный дефолт». Приложение может только **сузить**
набор полей верхнего уровня, но не расширить его.

```json appsettings.json theme={null}
{
  "Veriqa": {
    "OpenIddict": {
      "Clients": [
        {
          "ClientId": "my-app",
          "DisplayName": "My Application",
          "InitiatorContextEnabled": true,
          "InitiatorContextDisplayFields": [ "application", "region" ]
        }
      ]
    }
  }
}
```

* `InitiatorContextEnabled` — показывать ли контекст в подтверждении для этого клиента
  (управляет именно **отображением**; сбор снимка регулируется глобально).
* `InitiatorContextDisplayFields` — суженный набор полей для этого клиента.

## Дальше

<CardGroup cols={2}>
  <Card title="Как работает auth-поток" icon="diagram-project" href="/docs/ru/concepts/auth-flow">
    Где в потоке формируется контекст инициатора.
  </Card>

  <Card title="Hardening к продакшну" icon="shield-check" href="/docs/ru/guides/hardening">
    Чек-лист перед выпуском в продакшн.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.