Для 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 прав не даёт.

Именованные роли

Роли объявляют при создании:

javascript
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 из пакета:

javascript
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

Terminal
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 схему обновляет команда:

Terminal
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, а не копированием живого файла:

Terminal
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.
  • Имя, почта и телефон пользователя — недоверенные данные. Экранируйте их при выводе и не сопоставляйте учётные записи по почте.

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