Для AI-агентов: markdown этой страницы — /docs-content/applications/app-login/operations.md индекс документации — /llms.txt
Обслуживание входа
Как устроены роли и владельцы приложения, что делают в админке SDK входа, как управлять пользователями из кода, вести данные пользователей, хранить и копировать хранилище SDK.
Роли и владельцы | Админка | Регистрация и приглашения | Функции управления | Сессии и устройства | Данные пользователей | Хранилище входа | Команды | Секрет входа | Журналы
Роли и владельцы
У пользователя приложения роль user или admin. Кроме неё учётной записи можно дать одну именованную роль из объявленных в коде.
Владельцы и администраторы
Владелец — администратор, который вошёл по ссылке установки. Первого владельца создаёт команда create-admin: на сервере платформы её выполняет агент, когда включает вход или когда вы просите «создай админа приложения». Как работает ссылка, её срок и флаг --reset описывает Админ по ссылке установки. Владельцев может быть несколько: каждая открытая ссылка добавляет ещё одного.
Остальных администраторов назначает владелец в админке или код приложения функцией setRole. В админке владелец может то, что администратору недоступно: назначать администраторов, снимать права с других администраторов и владельцев и проходить шаги мастера «Оператор данных», «Способы входа» и «Журнал». Функции управления это разделение не применяют, см. Функции управления.
Права администратора действуют 12 часов после входа через сервис входа. Позже role у пользователя читается как user, isOwner — как false, а needsReauth — как true. requireUser({ role: 'admin' }) показывает такому администратору экран «Подтвердите вход» со ссылкой на повторный вход, а fetch получает 403 {"error":"reauth_required"}. После повторного входа той же учётной записью права возвращаются.
Вне платформы администраторов задаёт и переменная AUTH_ADMINS: <сервис>:<id> через запятую, как yandex:12345. Такие администраторы — не владельцы. На сервере платформы AUTH_ADMINS прав не даёт.
Именованные роли
Роли объявляют при создании:
createAuth({ roles: { manager: { ru: 'Менеджер', en: 'Manager' } } })
Ключ роли — [a-z][a-z0-9_-]{0,31}, кроме user и admin, ролей не больше 50, подпись — до 64 символов. Ошибка в объявлении — AuthConfigError на старте. Роль выдаёт админка или auth.setRoleName(userId, 'manager'), снимает — auth.setRoleName(userId, null). Роль admin она не меняет.
requireUser({ role: 'manager' }) пропускает учётные записи с этой ролью и администраторов. Роль, не объявленная в roles, — исключение при создании обработчика, а не ответ на запрос.
Админка
Админка открывается по адресу <APP_URL>/_auth/admin администратору приложения. Все пути под /_auth/admin обслуживает SDK: свой маршрут на этом пути не заводите. В админке:
- Люди — список учётных записей и карточка человека: роль, именованная роль, блокировка, выход на всех устройствах, выгрузка и удаление данных.
- Журнал — события входа и действий администраторов.
- Приглашения — ссылки для входа новых людей, см. Регистрация и приглашения.
- Мастер настроек — пять шагов: оператор данных, способы входа, регистрация, вид, журнал. Пока шаги «Оператор данных» и «Способы входа» не сохранены, клиенты не входят, а статус входа —
setup_pending.
На сервере платформы способы входа, политику и название приложения задают только в мастере. Переменная с тем же именем в env деплоя запирает поле мастера. Как перейти с переменных на мастер у приложения, которое пришло со входа 0.3, описывает Переход с входа 0.3.
Дайте администраторам ссылку на админку в интерфейсе приложения. Кнопка «Открыть админку» есть и в карточке приложения в кабинете.
Регистрация и приглашения
Новый человек при первом входе видит форму «Как к вам обращаться»: имя и согласие на обработку данных. Учётную запись из ссылки установки регистрация не спрашивает.
В шаге мастера «Регистрация» её можно закрыть — режим «по приглашению». Тогда новые люди входят только по ссылке, которую администратор создаёт в разделе «Приглашения» с ролью user или с именованной ролью. Ссылка живёт 48 часов и показывается один раз. По ней регистрируется тот, кто откроет её первым, поэтому не публикуйте её. Уже зарегистрированные входят как раньше.
Отказы приходят в обработчик onEvent из createAuth событием error с кодом registration_closed — регистрация закрыта, или invite_invalid — приглашение истекло, использовано или отозвано.
Функции управления
Функции вызываются у объекта auth, который возвращает createAuth(). Все возвращают Promise.
| Функция | Что делает |
|---|---|
ФункцияlistUsers({ search, role, blocked, limit, cursor }) |
Что делаетСписок пользователей: { items, nextCursor }. limit — от 1 до 100. Следующая страница — с cursor из nextCursor, nextCursor: null — конец списка |
ФункцияlistEvents({ userId, type, limit, cursor }) |
Что делаетЖурнал событий. Формат ответа и навигация — как у listUsers |
ФункцияgetIdentities(userId) |
Что делаетСпособы входа пользователя: [{ provider, providerUserId }] |
ФункцияcountSessions(userId) |
Что делаетЧисло живых сессий пользователя |
ФункцияsetRole(userId, role, { actorId }) |
Что делаетВыдать или снять роль admin. Понижение владельца снимает и отметку владельца |
ФункцияclearOwner(userId, { actorId }) |
Что делаетСнять отметку владельца, роль admin остаётся |
ФункцияsetRoleName(userId, name, { actorId }) |
Что делаетВыдать именованную роль или снять её значением null |
Функцияblock(userId, { actorId, reason, until }) |
Что делаетЗаблокировать пользователя. reason — причина до 200 символов, её видит заблокированный, в журнал она не пишется. until — время в unix-миллисекундах позже текущего, без него блокировка бессрочна. Сессии перестают действовать на следующем запросе |
Функцияunblock(userId, { actorId }) |
Что делаетСнять блокировку |
ФункцияdeleteUser(userId, { actorId }) |
Что делаетУдалить пользователя, его сессии, способы входа, устройства и согласия |
ФункцияlogoutEverywhere(userId, { actorId }) |
Что делаетЗавершить все сессии пользователя и забыть его устройства. Отказов SELF и ENV_ADMIN у неё нет: из кода она завершает сессии кого угодно, в том числе свои и администратора из AUTH_ADMINS |
ФункцияexportUser(userId, { actorId }) |
Что делаетВыгрузить всё о пользователе: учётную запись, способы входа, согласия, устройства и события |
actorId — id администратора, который выполняет действие. Он попадает в журнал событий и защищает от действия над собой. Права этого администратора функция не проверяет: код приложения действует от имени владельца, с actorId и без него. Кто может вызвать функцию, решает обработчик приложения — пропускайте к ней только requireUser({ role: 'admin' }) и проверяйте сами, что администратор вправе это сделать, например что он не меняет владельца.
Выгрузку exportUser отдаёт с событиями потоком, JSON.stringify на ней бросает INVALID_ARGUMENT. Записывайте её функцией exportChunks из пакета:
const { exportChunks } = require('@bitrix24/vibecode-auth')
const data = await auth.exportUser(userId, { actorId: req.authUser.id })
res.setHeader('Content-Type', 'application/json')
for await (const chunk of exportChunks(data)) res.write(chunk)
res.end()
Блокировку со сроком снимает следующий вход пользователя после срока, в журнал пишется событие unblock. Код с исчерпывающим switch по type события держит ветку default: список типов расширяется.
Ошибки — исключение AuthError с полем code:
code |
Когда |
|---|---|
codeINVALID_ARGUMENT |
КогдаuserId не в формате идентификатора пользователя — 32 шестнадцатеричных символа, роль не admin и не user, именованная роль не объявлена, until не позже текущего момента, limit вне диапазона от 1 до 100 |
codeNOT_FOUND |
КогдаПользователя с таким userId нет |
codeSELF |
КогдаПонизить, заблокировать, удалить себя или снять отметку владельца с себя: actorId совпадает с userId |
codeENV_ADMIN |
КогдаВне платформы: понизить, заблокировать или удалить администратора из AUTH_ADMINS |
codeLAST_ADMIN |
КогдаПонизить последнего незаблокированного администратора. Запрет действует и для кода без actorId |
Каждое изменение пользователя SDK решает и записывает под блокировкой администраторов в хранилище. Если блокировку не удалось взять за 5 секунд, функция бросает StorageError с reason: 'busy' — повторите позже.
Сессии и устройства
- Сессия хранится в хранилище, в браузере — только её токен в куке
vauth_sid:HttpOnly,SameSite=Lax, а вне режима разработки ещёSecureи префикс__Host-. - Сессия гаснет после 14 дней без активности и в любом случае через 30 дней после входа.
- У пользователя не больше 50 живых сессий. Новая сессия сверх лимита завершает самую старую.
- Кука
vauth_devметит браузер, живёт 400 дней и выходом не стирается. По ней учётная запись помнит до 10 своих устройств, самое старое вытесняется. НиUser-Agent, ни IP-адрес SDK не хранит. - Блокировка и выход на всех устройствах действуют на следующем запросе: кеша сессий в памяти у SDK нет.
Если в уведомлении приложения о куках есть перечень, внесите в него vauth_sid, vauth_dev, vauth_lang — язык экранов SDK, и временные куки vauth_tx, vauth_pending и vauth_once, которые живут от 60 секунд до 10 минут.
Данные пользователей
Оператор персональных данных посетителей — автор приложения. Политику обработки данных он публикует сам или задаёт в мастере реквизиты оператора.
- До регистрации профиль от сервиса входа хранится только в зашифрованной куке браузера. Отказ на экране регистрации стирает куку, в хранилище ничего не записывается.
- Согласие запоминается вместе с версией и ссылкой политики и набором полей. Новое согласие запрашивается после смены версии политики и после добавления полей в
AUTH_REQUEST_FIELDS. Поле, убранное изAUTH_REQUEST_FIELDS, очищается у всех пользователей. - «Мой аккаунт»
/_auth/accountпоказывает человеку его имя, способы входа и устройства. Там он меняет имя, привязывает и отвязывает способы входа, завершает сессию на устройстве, выгружает свои данные и удаляет учётную запись. Привязка, выгрузка и удаление требуют входа не старше 10 минут: иначе SDK сначала проводит человека через повторный вход. - Удаление себя стирает сессии, способы входа, устройства, согласия и самого пользователя одной транзакцией. Последний администратор удалить себя не может, SDK отвечает
409 LAST_ADMIN: сначала назначьте другого. Ведите человека на «Мой аккаунт» ссылкой, а не вызовомfetchиз своей кнопки. - Резервные копии содержат персональные данные, в том числе пользователей, удалённых после создания копии.
Хранилище входа
Таблицы vauth_* и каталог /data/.vauth/ принадлежат SDK:
- не удаляйте и не очищайте их,
- исключите таблицы
vauth_*из синхронизации схемы, которую ведёт ORM приложения — библиотека, строящая таблицы базы по моделям кода, - не отдавайте содержимое
/dataкак статические файлы. Файлы пользователей кладите в/data/uploads/под сгенерированными именами.
На SQLite каждое удаление учётной записи дописывает её идентификатор и время в журнал удалений рядом с базой, например /data/.vauth/deleted.log. Персональных данных в нём нет. По нему восстановление копии на месте снова удаляет тех, кто был удалён после её создания.
Хранилище помечено подписью, вычисленной из секрета входа. Приложение не стартует с хранилищем, которое создано под другим секретом:
- the store mark does not match VIBE_AUTH_SECRET (store_id 23e999b75da5dbbcf6d3e295802c1347): this store was created under none of this app's system secrets (current, previous or revoked). …
Базу в этом случае не пересоздавайте: выясните, откуда она взялась, например не указывает ли AUTH_SQLITE_PATH или DATABASE_URL на базу другого приложения.
Копии PostgreSQL и MySQL делают средствами базы — pg_dump, mysqldump: таблицы vauth_* — часть базы приложения. Приложение со входом восстанавливается из резервной копии сервера только на месте, см. Перенос и восстановление.
Команды
Команды запускают в каталоге приложения через npx --no-install vibecode-auth. Они читают те же секреты, что и приложение: на сервере платформы — VIBE_AUTH_SECRET, вне платформы — AUTH_SECRET.
create-admin
npx --no-install vibecode-auth create-admin
Печатает одну строку — ссылку установки администратора <APP_URL>/_auth/setup-admin#vauth:t=…. Параметры: --env-file <путь> — файл с переменными, --url <APP_URL> — адрес приложения, --reset — оставить владельцем одного того, кто откроет ссылку. Не запускайте команду в фоне с записью вывода в журнал: кто откроет ссылку первым, тот и владелец. На сервере платформы команду выполняет агент синхронным exec, на отдельной машине — с --env-file /var/lib/vibe/app-login/<служба>.env.
migrate
При старте SDK сам создаёт и обновляет схему. С AUTH_MIGRATIONS=off схему обновляет команда:
npx --no-install vibecode-auth migrate
vibecode-auth: schema is up to date (store_id 23e999b75da5dbbcf6d3e295802c1347, sqlite /data/.vauth/vauth.sqlite)
Хранилище команда выбирает в таком порядке: параметр --database-url, затем AUTH_SQLITE_PATH, затем DATABASE_URL, если он начинается с postgres://, postgresql:// или mysql://, иначе файл SQLite по умолчанию. Строка успеха называет, какое хранилище она тронула. Значение --database-url видно в списке процессов и истории оболочки.
backup
Копия SQLite — командой SDK, а не копированием живого файла:
npx --no-install vibecode-auth backup --to /data/.vauth/backup.sqlite
vibecode-auth: backup of sqlite /data/.vauth/vauth.sqlite written to /data/.vauth/backup.sqlite
Если файл копии уже существует, команда отказывает с the backup target already exists. Если файла SQLite по пути AUTH_SQLITE_PATH нет, команда отказывает и называет путь. Из кода то же делает await auth.backup('/data/.vauth/backup.sqlite'). Журнал удалений в копию не входит.
Секрет входа
На сервере платформы секретом входа управляет платформа: VIBE_AUTH_SECRET появляется при включении входа и доставляется приложению как системный секрет. Его значение не показывают ни кабинет, ни API. Задать, заменить или удалить системный секрет через API нельзя, см. Секреты автора и системные секреты.
Секрет подписывает сессии, ссылки установки и метку хранилища. SDK читает его один раз при старте и удаляет из process.env, поэтому код приложения секрета не видит.
Журналы
- Исключите строку запроса
/_auth/callback/*из журнала запросов приложения: в ней одноразовый код сервиса входа. - SDK не пишет секрет, токены, коды и куки ни в события, ни в консоль, ни в текст исключений. Исключения — токен входа в режиме разработки, который SDK печатает в консоль, и ссылка установки, которую печатает
create-admin. - Имя, почта и телефон пользователя — недоверенные данные. Экранируйте их при выводе и не сопоставляйте учётные записи по почте.