> ## 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. # За reverse-proxy > Какие пути должен пропускать reverse-proxy перед Veriqa, что нужно WebSocket страницы входа, и готовая конфигурация NGINX. Self-hosted Veriqa говорит по HTTP и ждёт, что TLS терминируется на прокси перед ней. Эта страница перечисляет, что этот прокси должен пропускать. Доверие к прокси на стороне Veriqa — секция `ForwardedHeaders` — описано в [self-hosted, шаг 6](/docs/ru/quickstart/self-hosted#6-поставьте-за-reverse-proxy). ## Дайте Veriqa собственное имя хоста Самая простая и рекомендуемая раскладка — отдельное имя хоста, `auth.your-domain.com`, все запросы которого уходят в Veriqa. Ничего не нужно перечислять, ничто не пересекается с вашим приложением, а путь, добавленный следующим релизом, заработает без правки прокси. Этот же адрес — `issuer`, по которому ваши приложения проверяют токены: у инстанса один issuer, поэтому приложения на разных доменах — например, тестовый сайт и боевой — указывают на один и тот же адрес, а не проксируют Veriqa каждое под своим доменом. Если вы всё же встраиваете Veriqa в имя хоста своего приложения, способов два. Пропускать все пути из таблицы ниже: Veriqa отдаёт их от корня имени хоста, поэтому `/_content/` и `/hubs/` на нём заняты. Либо оставить корень приложению и убрать всю Veriqa [под префикс пути](#под-префиксом-пути). ## Пути | Префикс пути | Кто обращается | Что это | | - | - | - | | `/.well-known/` | ваше приложение | Discovery-документ и ключи подписи | | `/connect/` | браузер и ваше приложение | OIDC-эндпоинты и страница входа с её действиями | | `/auth/` | браузер | Страницы вне OIDC-пути: страница подтверждения, страница добора недостающего номера телефона, email или поля профиля на устройстве, где подтверждён вход, и страницы Email-канала, на которые ведут ссылки из писем | | `/hubs/` | браузер, WebSocket | Живой статус страницы входа и страницы добора недостающих данных (SignalR) | | `/api/transaction/` | браузер и ваше приложение | Опрос статуса, когда WebSocket недоступен; создание транзакции подтверждения и чтение её результата | | `/_content/` | браузер | Статические файлы страницы входа | | `/api/channels/` | платформы мессенджеров | Вебхуки каналов — в режиме `Webhook` должны быть доступны из интернета | | `/r/` | браузер | Короткие ссылки режима hop — только когда он включён; префикс задаёт `Veriqa:HopMode:HopPath` | | `/api/link-handle/` | ваше приложение | Обмен [handle связки](/docs/ru/scenarios/channel-linking#два-бота-передача-пользователя-вашему-боту) на идентичность вошедшего пользователя — только если кнопка пост-действия несёт `{handle}` | | `/api/collected-claims` | ваше приложение | Удаление собранных claims — только при [хранилище собранных claims](/docs/ru/guides/storage#хранилище-собранных-claims) | `/health/live`, `/health/ready` и `/health/channels` нужны вашему мониторингу, публиковать их не обязательно. Списка из `/.well-known/`, `/connect/`, `/hubs/`, `/api/transaction/` и `/_content/` хватает для простого входа, и он выглядит полным. Хватать перестаёт в день, когда вы запросите номер телефона или email, включите Email-канал или переведёте бота в `Webhook`: эти страницы и вебхуки живут под `/auth/` и `/api/channels/`. ## WebSocket О том, что пользователь подтвердил вход, страница входа узнаёт через хаб `/hubs/auth`. Прокси должен позволить соединению перейти на WebSocket — пробросить заголовки `Upgrade` и `Connection` и ходить в Veriqa по HTTP/1.1 — и не должен рвать простаивающее соединение раньше, чем может длиться вход. Когда переход не проходит, страница переключается на опрос `/api/transaction/{id}/status`: вход всё равно завершается, но с задержкой. ## NGINX ```nginx theme={null} # контекст http map $http_upgrade $connection_upgrade { default upgrade; '' close; } server { listen 443 ssl; http2 on; server_name auth.your-domain.com; ssl_certificate /etc/nginx/certs/server.crt; ssl_certificate_key /etc/nginx/certs/server.key; # Запросы входа несут cookie; при дефолтных 8k на более длинный заголовок прокси отвечает 400 large_client_header_buffers 4 32k; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # WebSocket страницы входа proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_read_timeout 300s; } } ``` Когда Veriqa делит имя хоста с вашим приложением, оставьте тело блока `location` и повторите его для каждого префикса таблицы вместо `/`: ```nginx theme={null} location ~ ^/(\.well-known|connect|auth|hubs|api/transaction|api/channels|_content)/ { # те же директивы proxy_*, что выше } ``` Полная конфигурация с настройками TLS и редиректом с HTTP на HTTPS лежит в репозитории: `samples/docker-compose/nginx.conf` ([примеры](/docs/ru/samples)). ## Под префиксом пути С префиксом пути каждый адрес Veriqa начинается с него — `https://app.your-domain.com/auth/veriqa/connect/token`, — а корневые пути имени хоста остаются вашему приложению. Задайте префикс хосту Veriqa и повторите его во всех публичных адресах, которые вы настраиваете: | Ключ | Значение | | - | - | | `Veriqa:PathBase` | `/auth/veriqa` | | `Veriqa:OpenIddict:Server:Issuer` | `https://app.your-domain.com/auth/veriqa` | | `Veriqa:Channels:Email:PublicBaseUrl`, `WebhookBaseUrl` канала в режиме `Webhook` | тот же адрес, с префиксом | `Veriqa:PathBase` начинается с `/`, не оканчивается на `/` и может состоять из нескольких сегментов. Пишется он обычным текстом: без `?`, `#`, `%`, `\`, пробельных символов и без сегментов `.` и `..`. Значение другой формы останавливает хост на старте; пустое значит корень. Префикс действует при любом способе, которым прокси передаёт путь, — возьмите один из двух блоков: ```nginx theme={null} # Путь передаётся как есть: Veriqa получает /auth/veriqa/connect/token location /auth/veriqa/ { proxy_pass http://127.0.0.1:8080; # те же директивы proxy_*, что выше } # Префикс срезается: Veriqa получает /connect/token location /auth/veriqa/ { proxy_pass http://127.0.0.1:8080/; # те же директивы proxy_*, что выше } ``` После этого `https://app.your-domain.com/auth/veriqa/.well-known/openid-configuration` возвращает `issuer` и все эндпоинты с префиксом. Клиент, читающий метаданные по RFC 8414, запрашивает их от корня имени хоста, дописывая путь issuer в конец. Отобразите этот адрес: ```nginx theme={null} location = /.well-known/oauth-authorization-server/auth/veriqa { proxy_pass http://127.0.0.1:8080/auth/veriqa/.well-known/oauth-authorization-server; proxy_set_header Host $host; proxy_set_header X-Forwarded-Proto $scheme; } ``` Это отображение проверено для прокси, передающего путь как есть. У прокси, срезающего префикс, цель — тот же адрес без `/auth/veriqa`; этот вариант не проверялся. Что учесть: * **Префикс, с которого начинается путь самой Veriqa**, — `/auth`, `/api`, `/connect`, `/hubs`, `/_content`, `/health` или путь hop-ссылок (`/r` по умолчанию, `Veriqa:HopMode:HopPath`) — работает, только когда прокси передаёт путь как есть. За срезающим прокси такой префикс отвечает `404`. `/auth/veriqa` к ним не относится. * **Запросы, приходящие к инстансу напрямую, идут без префикса** — health-проба запрашивает `http://127.0.0.1:8080/health/live`. Отличить такой запрос от запроса, срезанного прокси, Veriqa не может и обслуживает оба, поэтому закрыть корень инстанса снаружи — дело прокси. * **Несколько инстансов.** Прокси должен держать браузер на одном инстансе (привязка сессии, `ip_hash` в NGINX): без неё хаб страницы входа не подключается. У Email-канала своё ограничение — оговорка про multi-instance в [настройке каналов, Email](/docs/ru/guides/channels#email). От префикса не зависит ни то, ни другое. * **Под префиксом проверены:** вход по Email в обоих режимах с его входящим вебхуком, вебхук мессенджера (режим `Webhook`), запрос [номера телефона](/docs/ru/guides/phone-number), подтверждение адреса почты кодом или письмом от пользователя при [доборе claims](/docs/ru/concepts/claim-enrichment), выдача токенов и `userinfo`, форма добора недостающего поля профиля и транзакция подтверждения, созданная вашим сервером. Часть про мессенджеры проверялась только на MAX и Telegram. `Veriqa:PathBase` — настройка поставляемого хоста. Когда Veriqa встроена в ваше приложение ASP.NET Core, префикс — это `UsePathBase` самого приложения, и discovery его несёт. ## Другие прокси Traefik, Caddy и IIS нужны те же три вещи: все пути из таблицы, заголовки `X-Forwarded-Proto` и `X-Forwarded-For` и переход на WebSocket. Traefik и Caddy пропускают его без настройки; в IIS должен быть установлен компонент WebSocket Protocol. Под префиксом пути вместо путей таблицы пропускается один префикс — см. [Под префиксом пути](#под-префиксом-пути). ## Проверка * `https://auth.your-domain.com/.well-known/openid-configuration` возвращает `https`-URL на вашем имени хоста. `http`-URL или `invalid_request` значат, что прокси не доверен — [self-hosted, шаг 6](/docs/ru/quickstart/self-hosted#6-поставьте-за-reverse-proxy). * На странице входа вкладка сети в браузере показывает `/hubs/auth` с ответом `101 Switching Protocols`. * `Request Header Or Cookie Too Large` — поднимите `large_client_header_buffers`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.