Для 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 и командой запуска самого приложения.
Установка
Поставьте пакет без скриптов установки. Точную команду для сервера даёт поле
sdk.installCommandнастройки входа:npm install --ignore-scripts https://vibecode.bitrix24.tech/sdk/vibecode-auth-0.4.4.tgzАдрес отдаёт архив только выпущенной версии. Неизвестная или отозванная версия отвечает
404.Сверьте хеш пакета. В
package-lock.jsonу записиnode_modules/@bitrix24/vibecode-authполеintegrityдолжно совпасть сsdk.integrityиз настройки входа. Для версии0.4.4:sha512-BW9fu+G3UphtF2LQksS85Mzgexy0FV8P6Fv70TlxvSXHQhQW2eu6ZIJorbg1Vb8UKninvgv8+LiyAlveuSNF+g==Хеш не совпал — остановитесь и не запускайте приложение с этим пакетом.
Поставьте драйвер хранилища, если оно не 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
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
Первой строкой обработчика:
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 процесс упадёт:
let user
try { user = await auth.getUser(req) } catch { res.statusCode = 503; return res.end() }
Своя база
Пул PostgreSQL:
createAuth({ db: { client: 'pg', pool } })
Пул MySQL — из mysql2/promise, с базой по умолчанию и кодировкой соединения utf8mb4. Это умолчание mysql2, его не меняйте:
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_SECRETSDK берёт временный секрет и хранит всё в памяти: после перезапуска данных нет, - с
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 нет.