Skip to main content
Для не-.NET стеков Veriqa — обычный OpenID Connect провайдер. Пакета Veriqa для Node.js нет и не требуется: вы пишете стандартного OIDC-клиента, а всю специфику (страница входа, QR, подтверждение в мессенджере) Veriqa выполняет на своей стороне.
Один код, любое развёртывание. Приложению не важно, где работает Veriqa — в облаке Veriqa, в вашем контейнере Docker или службой (systemd либо служба Windows) на вашей машине. Варианты различаются только адресом issuer’а и тем, где заведён клиент; код приложения ниже одинаков для всех, а переключение сводится к одной переменной окружения.

1. Установите пакеты

Рекомендуемая OIDC-библиотека — openid-client (сертифицирована OpenID Foundation, актуальная линия 6.x). Ни веб-фреймворка, ни хранилища сессий она не тянет, а коду ниже нужно и то, и другое:
express — фреймворк, под который написаны маршруты; express-session даёт им req.session — то место, где PKCE-code_verifier и state ждут, пока пользователь подтверждает вход. Без любого из пакетов первый же запуск падает на строке импорта с ERR_MODULE_NOT_FOUND, ещё не дойдя до Veriqa.
Требуется Node.js 20 или новее — это минимум, объявленный библиотекой. Линия 6.x — полная переработка API: примеры для 5.x (Issuer.discover, client.callback) к ней не подходят.
Пример — ESM. config.js выполняет discovery через await на верхнем уровне модуля, а CommonJS так не умеет. Пропишите "type": "module" в package.json — иначе node server.js остановится на Cannot use import statement outside a module.

2. Заведите клиента на стороне Veriqa

Veriqa Cloud сейчас недоступен — строки про облако описывают контракт его API. Используйте self-hosted; подробности — в Veriqa Cloud.
У self-hosted две поставки, и для этой страницы они равнозначны. Сервер работает в контейнере Docker — быстрый старт self-hosted — либо ставится из архива юнитом systemd или службой Windows, без Docker и без рантайма .NET на машине — установка службой ОС. Выбор определяет способ поставки сервера, а не регистрацию клиента, адрес issuer’а и код ниже. Что бы вы ни выбрали, у клиента должны быть объявлены разрешённые redirect URI (сверка точным совпадением, wildcard не поддерживаются) и разрешённые scopes — включая channel, если приложению нужны claims канала (шаг 7). redirect_uri сверяется буквально, поэтому регистрируйте ровно тот URL, который обслуживает ваш callback-маршрут. Для сервера из шага 6, запущенного как в шаге 9, это http://127.0.0.1:3000/callback — зарегистрируйте именно его и открывайте приложение в той же форме хоста (127.0.0.1, а не localhost). Секрет не обязателен. Минимальный рабочий набор — issuer, client_id, redirect_uri: public-клиент с PKCE, и это дефолт облака. Confidential-клиент нужен, только если приложение серверное и вы хотите аутентифицировать его секретом; в облаке секрет выпускается отдельным явным действием на экране Applications и показывается один раз — сохраните сразу. Значения кладите в окружение, не в код. Задайте их в той оболочке, из которой будете запускать приложение: первые две — то, что дал шаг 2, две последние — ваши:
SESSION_SECRET Veriqa не выдаёт — это ваша собственная случайная строка, ключ, которым express-session подписывает cookie сессии. Держите его вне системы контроля версий и в каждом окружении задавайте свой. Public-варианту VERIQA_CLIENT_SECRET не нужен вовсе: у public-клиента секрета нет. Пропустите переменную, которую выбранный вариант читает, — запуск упадёт ещё на импорте config.js: new URL(undefined) бросает ERR_INVALID_URL, ни один маршрут обслужен не будет. Файл .env тоже подойдёт, если он вам привычнее: Node.js 20.6 и новее читает его командой node --env-file=.env server.js. Переключение между вариантами — облако, Docker, служба ОС — это правка одного VERIQA_ISSUER.
В облаке issuer производен от slug проекта. Смена slug меняет issuer и ломает существующие интеграции — это отдельное действие владельца в Dangerous zone, а не рутинная правка настроек.

3. Выполните discovery

Клиент собирается один раз при старте процесса: библиотека сама читает /.well-known/openid-configuration и запоминает эндпоинты.
Первый аргумент — объект URL, а не строка. Если discovery отдаёт http-адреса эндпоинтов при доступе по https, дело не в клиенте: self-hosted сервер стоит за прокси без доверенных заголовков — см. шаг 6 self-hosted quickstart.

4. Начните вход

PKCE обязателен, state — защита от CSRF. Оба значения нужно сохранить в сессии до возврата пользователя: они понадобятся в callback.
login.js
Дальше работает Veriqa: пользователь видит страницу входа с QR и списком каналов, подтверждает вход в мессенджере на телефоне, после чего браузер возвращается на ваш redirect_uri с кодом.

5. Обработайте возврат

callback.js
authorizationCodeGrant сам обменивает код на токены и валидирует ответ; сверка state — через expectedState, повторно проверять его руками не нужно. Метод claims() возвращает разобранный id_token либо undefined, если сервер его не выдал. / — то, куда callback в итоге приводит браузер: этот маршрут добавляет шаг 6.

6. Соберите сервер

Три модуля выше — обработчики, а не приложение: кто-то должен дать им req.session, повесить их на маршруты и слушать порт. Это тот самый файл, который вы и запускаете.
server.js
Пути маршрутов здесь — контракт страницы: на /callback указывает APP_REDIRECT_URI, и его же вы зарегистрировали в шаге 2, а / показывает результат входа — пока в сессии пусто, он отправляет на /login, а после завершённого входа отдаёт сохранённые claims как JSON, так что итог виден без шаблонов.

7. Прочитайте claims

Базовый набор Veriqa кладёт в токены сама: Claims канала выдаются только по scope channel: Без запрошенного scope channel эти два claim не попадают ни в один токен — и, следовательно, не появляются в ответе userinfo, который зеркалит access_token. Именно по ним приложение различает привязанные каналы, поэтому для сценария привязки аккаунта scope обязателен.
Третий аргумент — ожидаемый sub: библиотека сверяет его с ответом и не даст подменить субъекта.

8. Ограничьте вход конкретным каналом

Стандартный OIDC-параметр acr_values формата channel:{тип} сужает выбор на странице входа:
Несколько значений через пробел (channel:telegram channel:whatsapp) — пользователь выбирает из перечисленных. Без параметра доступны все включённые на сервере каналы.

9. Контрольная точка

Запустите приложение из каталога с server.js, в той оболочке, где экспортированы переменные шага 2:
Оно поднимается на http://127.0.0.1:3000 — том адресе, из которого собран APP_REDIRECT_URI.
1

Проверьте discovery

curl $VERIQA_ISSUER/.well-known/openid-configuration возвращает метаданные с https-URL.
2

Запустите вход

Откройте http://127.0.0.1:3000/login — браузер должен уйти на страницу Veriqa с QR и каналами.
3

Подтвердите на телефоне

Подтвердите запрос в доверенном канале; браузер вернётся на /callback, а тот перенаправит его на /.
4

Проверьте claims

/ отдаёт сессию как JSON: sub заполнен, а channel_type несёт канал, которым подтверждён вход, — его не будет, если scope channel не запрашивался.

Дальше

Сценарии интеграции

Привязка канала, повторное подтверждение и подтверждение действия — на уровне HTTP.

Быстрый старт: self-hosted

Развернуть свой issuer в Docker.

Установка службой ОС

Тот же issuer без Docker — systemd или служба Windows, из архива.

OIDC + Veriqa: разбор

Где Veriqa встаёт в стандартный поток.

Hardening к продакшну

Что проверить перед выпуском.