Один код, любое развёртывание. Приложению не важно, где работает 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.
Пример — 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.
3. Выполните discovery
Клиент собирается один раз при старте процесса: библиотека сама читает/.well-known/openid-configuration и запоминает эндпоинты.
Первый аргумент — объект
URL, а не строка. Если discovery отдаёт http-адреса эндпоинтов при
доступе по https, дело не в клиенте: self-hosted сервер стоит за прокси без доверенных
заголовков — см. шаг 6 self-hosted quickstart.4. Начните вход
PKCE обязателен,state — защита от CSRF. Оба значения нужно сохранить в сессии до возврата
пользователя: они понадобятся в callback.
login.js
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 к продакшну
Что проверить перед выпуском.