Для AI-агентов: markdown этой страницы — /docs-content/applications/app-login/install.md индекс документации — /llms.txt

Подключение SDK входа

Как поставить SDK входа в приложение на Node.js, подключить его к коду и что SDK отвечает приложению и посетителю. Пакет @bitrix24/vibecode-auth раздаёт сама платформа, в публичном реестре npm его нет.

Перед установкой | Установка | Хранилище входа | Подключение | Маршруты SDK | Переменные окружения | Ошибки старта | Режим разработки

Перед установкой

На сервере платформы SDK стартует только во включённом входе. Включение, вопрос «кто будет пользоваться приложением», первого администратора и статусы входа описывает Вход пользователей приложения. Эта страница — о том, что делают с SDK в коде.

Приложению нужны Node.js 24.15 или новее на Express или node:http и деплой с runtime: node24. На отдельной машине приложение запускает служба платформы: деплой с systemd: true и командой запуска самого приложения.

Установка

  1. Поставьте пакет без скриптов установки. Точную команду для сервера даёт поле sdk.installCommand настройки входа:

    Terminal
    npm install --ignore-scripts https://vibecode.bitrix24.tech/sdk/vibecode-auth-0.4.4.tgz

    Адрес отдаёт архив только выпущенной версии. Неизвестная или отозванная версия отвечает 404.

  2. Сверьте хеш пакета. В package-lock.json у записи node_modules/@bitrix24/vibecode-auth поле integrity должно совпасть с sdk.integrity из настройки входа. Для версии 0.4.4:

    sha512-BW9fu+G3UphtF2LQksS85Mzgexy0FV8P6Fv70TlxvSXHQhQW2eu6ZIJorbg1Vb8UKninvgv8+LiyAlveuSNF+g==

    Хеш не совпал — остановитесь и не запускайте приложение с этим пакетом.

  3. Поставьте драйвер хранилища, если оно не SQLite, — таблица ниже.

SDK проверяет среду до чтения окружения. Node.js ниже 24.15.0 или собранный без crypto.argon2 получает отказ старта. Если на хосте остался старый образ, сделайте деплой на актуальный образ с runtime: node24.

Хранилище входа

Пользователи, сессии, настройки и согласия хранятся в хранилище приложения. Какое хранилище выбрать, зависит от размещения:

Размещение Хранилище Драйвер
РазмещениеGalaxy-приложение ХранилищеФайл SQLite /data/.vauth/vauth.sqlite на постоянном томе /data ДрайверНе нужен, проверка — node -e "require('node:sqlite')"
РазмещениеВиртуальная машина с PostgreSQL ХранилищеPostgreSQL этой машины Драйверnpm install pg@8
РазмещениеВиртуальная машина с MySQL ХранилищеMySQL этой машины Драйверnpm install mysql2@^3.23.1
РазмещениеВиртуальная машина без базы ХранилищеФайл SQLite /var/lib/vauth/vauth.sqlite вне каталога приложения либо внешняя PostgreSQL или MySQL ДрайверДля SQLite не нужен, для базы — её драйвер
  • SQLite. SDK берёт встроенный модуль node:sqlite. Путь к файлу задаёт платформа, когда вход включён: /data/.vauth/vauth.sqlite в галактике и /var/lib/vauth/vauth.sqlite на отдельной машине. Каталог /var/lib/vauth деплой добавляет в dataDirs сам, поэтому файл переживает повторный деплой.
  • PostgreSQL и MySQL машины. Рантайм не выдаёт строку подключения: создайте базу, пользователя и строку подключения сами и передайте пул в createAuth — см. Своя база. Для MySQL нужен рантайм с Node.js 24, например node24-mysql: на node20-* SDK не стартует.

Подключение

Express

javascript
const express = require('express')
const { createAuth } = require('@bitrix24/vibecode-auth')

const app = express()
createAuth().then((auth) => {
  app.use(auth.express())
  app.get('/orders', auth.requireUser(), (req, res) => res.json({ user: req.authUser }))
  app.listen(process.env.PORT || 3000)
})

auth.express() обслуживает маршруты SDK под /_auth и передаёт остальные запросы приложению. Подключайте его до разбора тела запроса и до обработчика CORS: известный путь SDK, запрошенный другим методом, SDK отвечает сам 405, и до обработчика, подключённого после, такой запрос не доходит. auth.requireUser() пропускает запрос с живой сессией и кладёт пользователя в req.authUser.

Ссылка «Войти» в интерфейсе приложения ведёт на /_auth/login?returnTo=<путь>, ссылка «Мой аккаунт» — на /_auth/account. Дайте её в меню приложения: там человек меняет имя, видит устройства и удаляет свои данные.

Вызывайте createAuth() один раз за процесс. Прочитав окружение, SDK удаляет секреты входа из process.env, и повторный вызов в том же процессе получает отказ старта. Если старт не удался, например база ещё не поднялась, перезапускайте процесс целиком, а не повторяйте createAuth() в цикле.

Ответы requireUser

Ответ зависит от того, как пришёл запрос. Навигация — GET или HEAD с Accept: text/html, то есть переход в браузере. Остальные запросы, например fetch, получают JSON.

Ситуация Навигация Остальные запросы
СитуацияНет сессии Навигация302 на /_auth/login?returnTo=<путь>&h=1 Остальные запросы401 {"error":"unauthenticated"}
СитуацияМастер настроек не пройден Навигация200, экран «Вход скоро откроется» Остальные запросы503 {"error":"setup_pending"}
СитуацияПользователь заблокирован Навигация403, экран «Вы заблокированы» с причиной и сроком Остальные запросы403 {"error":"blocked"}
СитуацияРоль не подходит Навигация403, экран «Нет доступа» Остальные запросы403 {"error":"forbidden"}
СитуацияАдминистратор вошёл больше 12 часов назад Навигация200, экран «Подтвердите вход» со ссылкой на /_auth/reauth Остальные запросы403 {"error":"reauth_required"}
СитуацияЗапрос из фрейма чужого сайта, например портала Битрикс24 Навигация200, экран «Приложение откроется в новой вкладке» Остальные запросы—
СитуацияХранилище недоступно Навигация503 {"error":"unavailable"} Остальные запросы503 {"error":"unavailable"}

Живые сессии продолжают работать и пока мастер не пройден: новые учётные записи в это время не создаются. Экран фрейма — единственная страница SDK, которую можно показать внутри чужого фрейма. По ссылке на нём приложение открывается в новой вкладке.

auth.requireUser({ role: 'admin' }) пропускает только администраторов приложения, auth.requireUser({ role: 'manager' }) — учётные записи с именованной ролью manager и администраторов. Роли описывает Роли и владельцы.

node:http

Первой строкой обработчика:

javascript
if (await auth.handle(req, res)) return

handle возвращает true, если запрос был к маршруту SDK и SDK уже ответил.

Пользователь в коде

auth.getUser(req) возвращает пользователя или null. Те же поля несёт req.authUser:

Поле Тип Описание
Полеid Типstring ОписаниеИдентификатор пользователя приложения, 32 шестнадцатеричных символа
Полеname Типstring ОписаниеИмя, которое человек ввёл при регистрации или в «Моём аккаунте»
Полеrole Типstring Описаниеadmin — администратор, который вошёл не больше 12 часов назад, иначе user
ПолеneedsReauth Типboolean Описаниеtrue — администратор, которому для прав администратора нужно войти заново
ПолеroleName Типstring | null ОписаниеИменованная роль учётной записи из createAuth({ roles })
ПолеisOwner Типboolean ОписаниеВладелец приложения. true только там же, где role равно admin: в несвежей сессии владельца — false
ПолеownerSince Типnumber | null ОписаниеКогда учётная запись стала владельцем, в unix-миллисекундах. null — не владелец
Полеemail Типstring | null ОписаниеПочта, если её запрашивает AUTH_REQUEST_FIELDS и сервис входа её отдал
Полеphone Типstring | null ОписаниеТелефон, если его запрашивает AUTH_REQUEST_FIELDS и сервис входа его отдал
ПолеblockedAt Типnumber | null ОписаниеВремя блокировки в unix-миллисекундах
ПолеcreatedAt Типnumber ОписаниеВремя создания в unix-миллисекундах
ПолеlastLoginAt Типnumber ОписаниеВремя последнего входа в unix-миллисекундах

Код, который сам сравнивает role === 'admin' или проверяет isOwner, учитывает и needsReauth: администратор с needsReauth: true получает права после повторного входа. Ведите его на requireUser({ role: 'admin' }), а не сравнивайте поля вручную.

При недоступном хранилище getUser бросает исключение, а не возвращает null. В async-обработчике без try/catch процесс упадёт:

javascript
let user
try { user = await auth.getUser(req) } catch { res.statusCode = 503; return res.end() }

Своя база

Пул PostgreSQL:

javascript
createAuth({ db: { client: 'pg', pool } })

Пул MySQL — из mysql2/promise, с базой по умолчанию и кодировкой соединения utf8mb4. Это умолчание mysql2, его не меняйте:

javascript
const mysql = require('mysql2/promise')
const pool = mysql.createPool({ uri: process.env.DATABASE_URL }) // mysql://user:password@host:3306/app
createAuth({ db: { client: 'mysql', pool } })

База MySQL на другой машине — включите TLS с проверкой имени сервера: без него mysql2 передаёт данные открытым текстом. В адресе — ?ssl={"verifyIdentity":true}, со своим центром сертификации — опцией пула ssl: { ca, verifyIdentity: true }. Без verifyIdentity: true посредник с любым доверенным сертификатом получит пароль базы. Хост в адресе — DNS-имя из сертификата, а не IP-адрес.

Отдайте SDK отдельную базу или схему и не давайте другим учётным записям прав на неё.

Маршруты SDK

SDK обслуживает маршруты под префиксом /_auth и все пути админки /_auth/admin. Свои маршруты на этих путях не заводите: приложение их не получит. Путь под /_auth/, которого нет в таблице, передаётся приложению.

Метод и путь Назначение
Метод и путьGET /_auth/login НазначениеВход: страница выбора способа или переход к единственному способу. Пока мастер не пройден — экран «Вход скоро откроется»
Метод и путьGET /_auth/login/:provider НазначениеВход через указанный способ
Метод и путьGET /_auth/callback/:provider НазначениеВозврат от сервиса входа
Метод и путьGET /_auth/register, POST /_auth/register НазначениеРегистрация при первом входе: имя и согласие на обработку данных
Метод и путьGET /_auth/consent, POST /_auth/consent НазначениеНовое согласие после смены версии политики
Метод и путьGET /_auth/invite, POST /_auth/invite НазначениеВход по приглашению из админки
Метод и путьGET /_auth/setup-admin, POST /_auth/setup-admin НазначениеВход по ссылке установки администратора
Метод и путьGET /_auth/reauth, POST /_auth/reauth НазначениеПовторный вход той же учётной записью для прав администратора и действий в «Моём аккаунте»
Метод и путьGET /_auth/account Назначение«Мой аккаунт»: имя, способы входа, устройства, согласие, выгрузка и удаление данных. Без сессии — переход на вход
Метод и путьPOST /_auth/account/* НазначениеДействия «Моего аккаунта»: name, link/:provider, unlink/:provider, devices/:id/end, export, delete
Метод и путьPOST /_auth/logout НазначениеВыход на этом устройстве, затем переход на APP_URL/
Метод и путьPOST /_auth/logout-all НазначениеВыход на всех устройствах
Метод и путьGET /_auth/me НазначениеТекущий пользователь: {"user": {...}} или {"user": null}
Метод и путьGET /_auth/status, HEAD /_auth/status НазначениеСостояние входа: {"providers": [...], "setup": true, "admin": true}
Метод и путьGET /_auth/icon, HEAD /_auth/icon НазначениеИконка приложения из карточки. Иконки нет — 404
Метод и путь/_auth/admin и пути под ним НазначениеАдминка: люди, журнал, приглашения, мастер настроек. Открывается администратору приложения
Метод и путьGET /_auth/dev, POST /_auth/dev НазначениеВход администратором по токену из консоли. Только в режиме разработки, см. Режим разработки

В ответе /_auth/status поле providers — включённые способы входа, setup — есть разрешённый способ входа и политика, то есть мастер пройден, admin — у приложения есть хотя бы один незаблокированный администратор. По этому маршруту платформа определяет статус входа.

POST-маршруты принимают запрос только со страниц самого приложения: запрос с чужим Origin получает 403. GET /_auth/me и GET /_auth/status отвечают с Cache-Control: no-store и без заголовков CORS.

Переменные окружения

На сервере платформы способы входа, политику обработки персональных данных и название приложения задаёт владелец в мастере настроек админки, а не переменные. Не передавайте их в env деплоя: переменная запирает поле мастера, оно становится «только для чтения». Исключение — идентификатор клиента AUTH_VK_CLIENT_ID или AUTH_YANDEX_CLIENT_ID, который называет блок env настройки входа, пока вход через Битрикс24 приложению недоступен. Его не убирайте: по нему ссылка установки администратора предлагает способ входа. Подробнее — Админ по ссылке установки.

Автор передаёт в env деплоя только эти настройки:

Переменная Обяз. По умолч. Описание
ПеременнаяAUTH_REQUEST_FIELDS Обяз.нет По умолч.пусто ОписаниеКакие поля запрашивать у сервиса входа сверх имени: email, phone через запятую
ПеременнаяAUTH_MIGRATIONS Обяз.нет По умолч.auto Описаниеoff — не менять схему при старте, миграции запускаются командой — см. Хранилище
ПеременнаяAUTH_EVENTS_RETENTION_DAYS Обяз.нет По умолч.365 ОписаниеСрок хранения журнала событий, от 30 до 3650 дней

Лимиты обмена кода входа на сессию задают AUTH_EXCHANGE_PER_CLIENT_PER_MIN — от 1 до 600, по умолчанию 5, AUTH_EXCHANGE_PER_DAY — от 10 до 100 000, по умолчанию 2000, AUTH_EXCHANGE_FAIL_PER_DAY — от 10 до 100 000, по умолчанию 300, и AUTH_EXCHANGE_TRICKLE_SEC — от 1 до 600, по умолчанию 10.

Остальное задаёт платформа, пока вход включён: APP_URL, AUTH_SQLITE_PATH, AUTH_TRUST_PROXY, AUTH_DB_ADMINS, системные секреты и переменные VIBE_*. Деплой убирает эти имена из env, кроме AUTH_SQLITE_PATH, и сообщает о каждом в warnings. AUTH_SECRET и AUTH_SECRET_PREVIOUS SDK на сервере платформы не читает.

При деплое платформа заменяет все переменные приложения разом. Храните полный набор своих переменных вне каталога проекта и передавайте его целиком.

Вне платформы, например на своём сервере или локально, способы входа и политику задают и переменными: APP_URL, AUTH_SECRET — создайте его командой openssl rand -base64 32 и храните вне каталога проекта, AUTH_VK_CLIENT_ID, AUTH_YANDEX_CLIENT_ID, AUTH_PRIVACY_URL — ссылка https на политику, AUTH_PRIVACY_VERSION — её версия, AUTH_APP_NAME — название на экранах SDK.

Ошибки старта

Ошибка конфигурации останавливает старт и перечисляет все проблемы сразу, по именам переменных и без значений:

AuthConfigError: vibecode-auth: configuration is invalid:
- VIBE_AUTH_SECRET is missing: turn sign-in on in the dashboard
Строка ошибки Причина
Строка ошибкиVIBE_AUTH_SECRET is missing: turn sign-in on in the dashboard ПричинаПриложение на сервере платформы, а вход не включён. Включите вход и повторите деплой
Строка ошибкиAPP_URL points to this machine while VIBE_RUNTIME is set ПричинаНа сервере платформы в APP_URL адрес этой машины, например localhost
Строка ошибкиAPP_URL is required: the public origin of the app, like https://host ПричинаНе задан APP_URL. Вне платформы
Строка ошибкиAPP_URL must use https (http is allowed only for localhost, 127.0.0.1 and [::1]) ПричинаAPP_URL начинается с http://, а хост не локальный
Строка ошибкиAPP_URL uses http while NODE_ENV=production: development mode is not allowed in production ПричинаАдрес http://localhost при NODE_ENV=production
Строка ошибкиAUTH_SECRET is required (create it with: openssl rand -base64 32) ПричинаВне платформы и вне режима разработки не задан AUTH_SECRET
Строка ошибкиAUTH_SECRET must be at least 43 characters (create it with: openssl rand -base64 32) ПричинаСекрет короче 43 символов
Строка ошибкиAUTH_SECRET has too little variety of characters (create it with: openssl rand -base64 32) ПричинаСекрет нужной длины, но из повторяющихся символов
Строка ошибкиAUTH_PRIVACY_VERSION must not contain control characters ПричинаВ версии политики табуляция или перевод строки
Строка ошибкиAUTH_ADMINS must list <provider>:<id> keys of this build's providers, comma-separated ПричинаВ AUTH_ADMINS неизвестный сервис входа или неверный формат
Строка ошибкиAUTH_SQLITE_PATH needs AUTH_SECRET: without a secret development mode keeps the store in memory ПричинаВ режиме разработки задан путь к файлу SQLite без AUTH_SECRET
Строка ошибкиcreateAuth() already read the secrets and removed them from process.env: call it once per process, or pass env ПричинаcreateAuth() вызван второй раз в том же процессе
Строка ошибкиthe store mark does not match VIBE_AUTH_SECRET (store_id …) ПричинаХранилище создано не под секретом этого приложения — см. Хранилище

Пока мастер не пройден, приложение стартует без ошибки. Вне платформы SDK печатает в консоль строку vibecode-auth: sign-in is not open yet (no sign-in method or no privacy policy) и имена переменных, которые открывают вход.

Режим разработки

Локально APP_URL может быть http://localhost:<порт>, http://127.0.0.1:<порт> или http://[::1]:<порт>. Режим включается, когда NODE_ENV не равен production и в окружении нет VIBE_RUNTIME и переменных платформы VIBE_*. Свои переменные с префиксом VIBE_, например VIBE_API_KEY, режим не выключают. В этом режиме:

  • без AUTH_SECRET SDK берёт временный секрет и хранит всё в памяти: после перезапуска данных нет,
  • с AUTH_SECRET и без AUTH_SQLITE_PATH файл SQLite создаётся в ~/.vauth/ под именем из первых 12 шестнадцатеричных символов SHA-256 от пути проекта, поэтому у каждого проекта на машине своё хранилище,
  • куки ставятся без префикса __Host- и без Secure,
  • работает вход администратором без сервиса входа.

Для входа администратором SDK печатает в консоль одноразовый токен:

vibecode-auth dev sign-in token: <токен>

Откройте <APP_URL>/_auth/dev и вставьте токен в форму — SDK создаст учётную запись «Разработчик» со способом входа dev:local и правами администратора. Пока мастер не пройден, SDK ведёт её в мастер настроек /_auth/admin/settings, после — на APP_URL/. Каждый токен работает один раз, после входа SDK печатает новый. Неверный токен получает 404.

Открывайте APP_URL напрямую: запрос через туннель или прокси, с другой машины или с другим Host получает 404. Прокси фронтенда в режиме разработки, который добавляет заголовки X-Forwarded-*, тоже получает 404. Вне режима разработки маршрута /_auth/dev нет.

Смотрите также