Гости и боты в identity

Актуально для: identity после 0.35 (создание рабочих ботов — после 0.40, messaging после 0.155), координатор и messaging в режиме platform_token: identity · Проверено: 01.10.2026

Всё, что описано здесь, работает, когда платформа переключена на токен identity (platform_token: identity, решение ADR-0047 §8a). В режиме hmac — по умолчанию — гости и боты живут на координаторе, как описано в разделе Гости, подрядчики и члены семьи, и ничего из этой страницы не меняется.

В режиме identity гость и бот — такие же учётные записи identity, как сотрудники, и у каждой есть человек, который за неё отвечает: у гостя — пригласивший, у бота и ассистента — владелец. Входят они через тот же эмитент, и их токен отзывается тем же журналом отзывов.

Гости

Приглашение

Приложения по-прежнему приглашают через координатор — POST /v1/guests, право guests:invite проверяет координатор. В режиме identity он не создаёт гостя сам, а передаёт приглашение в identity, указав вызвавшего как пригласившего. Ответ identity (код и текст отказа) приходит к приложению без изменений.

Правила приглашения теперь хранит identity — консоль identity → Гости:

Параметр	По умолчанию	Смысл
Самое долгое приглашение	365 дней	срок больше урезается до него
Приглашение без срока	30 дней	срок без срока не бывает
Действующих гостей на пригласившего	0 — без ограничения	при достижении новое приглашение получает 409

Настройка координатора guest-max-days в режиме identity не действует: её место заняли эти параметры.

Приглашение несёт функции гостя (см. Доступ к SimpleTwo): по умолчанию — только чат и звонки. Такой гость входит в модель доступа наравне с сотрудниками; гости, приглашённые раньше на координаторе, остаются вне модели и попадают во все сервисы, как прежде.

Проверка: в консоли identity → Гости у гостя виден пригласивший, срок и состояние входа «ждёт карточку».

Карточка и первый вход

Гость получает не пароль, а одноразовый код карточки: 72 часа, не дольше срока приглашения. Приложение гасит его через POST /v1/auth/enroll/confirm на координаторе, тот передаёт в identity; пароль гость выбирает сам по политике паролей identity. Новая карточка выдаётся, только пока гость ни разу не входил.

Код восстановления

Как и раньше, доступ возвращает пригласивший: в приложении «Мои гости» → Помочь войти выдаёт шестизначный код, пригласивший диктует его гостю. Код выдаёт identity и хранит только его ключевой хеш. Правила те же: 10 минут, один раз, пять неверных попыток на запись — повторная выдача попытки не добавляет, после исчерпания новый код можно получить только после истечения старого. Гость гасит код своим телефоном через POST /v1/auth/recover/confirm; новый пароль завершает все прежние сессии.

Заявка гостя «Не могу войти» (POST /v1/auth/recover) остаётся на координаторе: он отмечает её в списке пригласившего и пишет ему от бота поддержки, но собственного кода больше не выпускает.

Администратор выдаёт код любому гостю в консоли координатора (как раньше) или в консоли identity → Гости → Код восстановления.

Продление, отзыв, проверка

Продлить — +30 дней от текущего срока (или от сегодня, если срок прошёл), не дальше самого долгого приглашения.
Отозвать — обратимо: учётная запись отключается, все её сессии в identity завершаются.
Проверка доступа — политика «Проверять гостей старше» в консоли identity → Проверки доступа: пригласивший отвечает «оставить» или «отозвать», молчание отзывает.

Истёкший, отозванный или не прошедший проверку гость попадает в журнал отзывов событием account: каждый сервис отказывает его токену сразу, не дожидаясь срока.

Токен гостя

Гость входит на странице identity, как все, и получает токен платформы с отметкой knd: guest. Ограничения гостя остаются прежними: каталог по политике роли, только разговоры, в которые его пригласили, без ящика почты. Сессия гостя, выпущенная координатором, в режиме identity не принимается — гость входит заново.

Боты и ассистенты

Владелец

У каждого бота и ассистента есть владелец — сотрудник, который отвечает за него. Консоль identity → Боты показывает всех ботов, их владельцев и учётные данные.

Владелец ушёл (отключён, удалён, срок истёк) — его боты и ассистенты отключаются вместе с ним, каждый с событием account в журнале отзывов. Системные боты организации (поддержка, объявления) не отключаются: в списке у них появляется отметка «владелец неактивен».
Передать — назначить нового владельца (действующего сотрудника) и сразу включить бота; Отключить — оставить выключенным.
Проверка владельцем — политика «Проверять ботов у владельца каждые, дней» в консоли identity → Проверки доступа; молчание отключает бота.

Новый рабочий бот

В режиме identity рабочие боты создаются в консоли identity → Боты → Новый рабочий бот. Консоль координатора их больше не создаёт и не меняет им токен: вместо кнопки New bot там ссылка на консоль identity. В режиме hmac всё наоборот — боты создаются на координаторе, как раньше, а кнопки в identity нет.

Поля формы:

Поле	Смысл
Логин	2–64 символа: строчная латинская буква, затем буквы, цифры, `.`, `_`, `-`; занятый логин (в том числе удалённой учётной записи) не подходит
Отображаемое имя	имя в каталоге и в беседах
Владелец	логин действующего сотрудника, который отвечает за бота
Области доступа	хотя бы одна из `read`, `send`, `react`, `manage-conv`; пустой набор (прежний «полный доступ») консоль не выдаёт
Беседы	id бесед через запятую; пусто — все беседы, в которые бота добавили
Вебхук и его секрет	необязательно: куда messaging присылает события и чем подписывает доставку
Учётные данные	пара ключей, созданная identity (закрытая половина показывается один раз), собственный открытый ключ бота или секрет клиента (показывается один раз)

Что происходит при создании:

identity просит координатор создать запись бота в messaging — области, беседы, вебхук, credential: platform (токена bot_… нет). У identity нет пути к управляющему API messaging: оно слушает только loopback на хосте messaging, и единственный его клиент — координатор через агента хоста. Поэтому identity обращается к двери координатора /v1/service/bots как svc:identity.
identity создаёт учётную запись бота (вид — служебная, владелец из формы) и выдаёт учётные данные. Если учётную запись создать не удалось, запись в messaging удаляется.
Координатор забирает учётную запись из ленты identity в течение минуты; бот появляется в каталоге и на его карточке Bots.

Проверка: в списке консоли identity → Боты у бота видны владелец, ключ или секрет и колонка Что может — области и беседы из записи messaging. Если колонка показывает «?», записи messaging не прочитались через координатор — причина написана над таблицей.

Изменение, отключение и удаление

Кнопки в строке бота держат запись messaging в согласии с identity:

Изменить — области доступа, беседы (пустое поле снимает ограничение), вебхук, имя. Учётные данные не меняются; открытые соединения бота сбрасываются, чтобы новые права действовали сразу.
Отключить — сначала учётная запись в identity (бот сразу не может войти), затем запись в messaging. Если messaging недоступен, консоль так и говорит; повторное нажатие повторяет только вторую половину.
Включить и Передать с включением — сначала запись в messaging; если она не включилась, бот остаётся отключённым.
Удалить — сначала запись в messaging, затем учётная запись, её учётные данные и все токены. Если messaging недоступен, учётная запись остаётся. Логин после удаления занят навсегда. Системные боты (поддержка, приветствие) удаляются вместе с тем, что их создало, на координаторе.

Когда владелец уходит, его боты отключаются в identity, а их записи в messaging — следом.

Рабочий бот: client_credentials

Рабочий бот (поддержка, объявления, интеграция) получает токен платформы в identity:

client_id — bot: и логин бота, например bot:announcer;
ключ (предпочтительно, private_key_jwt) — Новый ключ в консоли выдаёт пару, закрытая половина показывается один раз; можно передать и свою открытую половину (POST /control/bots/{логин}/keys с полем public). Сменить ключ заменяет все прежние;
секрет — Новый секрет, показывается один раз, заменяет прежний.

Запрос с ключом — подписанное утверждение (алгоритм набора, по умолчанию EdDSA; iss и sub — client_id, aud — адрес /oauth/token, exp не дальше пяти минут, jti одноразовый):

curl -fsS -X POST "https://id.<домен>/oauth/token" \
  -d grant_type=client_credentials \
  -d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
  -d client_assertion="$ASSERTION"

С секретом:

curl -fsS -X POST "https://id.<домен>/oauth/token" -u "bot:announcer:$SECRET" \
  -d grant_type=client_credentials

Ответ — токен платформы на час: sub — бот, knd: bot, у каждого токена своя сессия, токена обновления нет — бот просит новый.

Ассистент: обмен токена владельца

Мозг ассистента работает на устройстве владельца, поэтому своих учётных данных у ассистента нет. Приложение владельца обменивает его токен (RFC 8693):

curl -fsS -X POST "https://id.<домен>/oauth/token" \
  -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
  -d client_id=simpletwo \
  -d subject_token="$OWNER_TOKEN" \
  -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
  -d requested_subject=ivan.assistant

Ассистент должен принадлежать этому человеку. Ответ: sub — ассистент, knd: bot, act: {sub: владелец}, сессия владельца (его выход завершает и этот токен), сервисы и срок не шире, чем у токена владельца. Токен с act обменять повторно нельзя: ассистент не действует за ассистента.

Права ассистента — пересечение: сервис проверяет разрешение и у ассистента, и у владельца по RBAC координатора. Выход владельца отовсюду, его отключение или удаление отзывают и токены ассистента. Что ассистент делает — черновик или полный режим, в каких разговорах, квота модели — по-прежнему решает messaging.

«Мои агенты» (POST /v1/me/agents) в режиме identity создают учётную запись ассистента в identity (владелец — нажавший) и его поведение в messaging без собственного токена; в ответе вместо token — поле token_exchange с адресом и параметрами обмена.

Перенос существующих ботов

В режиме identity messaging не принимает прежние токены bot_… — принимается только токен платформы. Поэтому до переключения:

Проверьте, что у каждого бота есть учётная запись в identity: консоль identity → Боты (координатор записывает туда ботов с момента появления identity). У бота без владельца назначьте его кнопкой Передать.
Для каждого рабочего бота выдайте ключ (или секрет) и передайте его в среду бота вместе с client_id и адресом /oauth/token.
Переведите бота на получение токена в identity; до переключения этот токен сервисы не принимают, поэтому достаточно проверить, что identity его выдаёт.
Ассистентам ничего не нужно: приложение владельца после обновления получает их токен обменом.
Переключите платформу на identity. Записи ботов в messaging — область, права, разговоры — остаются прежними; прежний токен bot_… можно убрать повторным созданием бота с credential: platform (так создаются новые ассистенты).

Типовые отказы

Симптом	Вероятная причина
`404` на `/control/guests…` в identity	эмитент identity выключен: гости пока на координаторе
`409` на приглашение: гостей на пригласившего не больше N	достигнут лимит политики гостей
`400 a guest is invited by an active person`	пригласивший не действующий сотрудник (гость, бот, отключён)
`429` при выдаче кода восстановления	исчерпаны пять попыток; подождите десять минут с прошлой выдачи
`401 invalid_client` у бота	неверные ключ, секрет или `client_id` без `bot:`; утверждение уже использовано
`400 invalid_grant` у бота	учётная запись бота отключена (например, ушёл владелец)
`400 invalid_grant: no assistant of yours by that name`	ассистент принадлежит другому человеку
messaging отвечает `invalid_token` на `bot_…`	в режиме identity прежние токены ботов не принимаются
`409 hmac_mode` на «Новый рабочий бот»	токен платформы на координаторе ещё `hmac`: бот создаётся в консоли координатора
`409 managed_on_identity` на New bot в консоли координатора	режим identity: бот создаётся в консоли identity
`409 name_taken`	логин занят учётной записью на координаторе или записью-сиротой в messaging (её видно на карточке Bots координатора)
`503 no_relay`	у identity не задан `DIR_COORDINATOR_URL`, пути к записям messaging нет
`502 messaging_unreachable`	координатор не достучался до messaging через агента хоста

Гости​

Приглашение​

Карточка и первый вход​

Код восстановления​

Продление, отзыв, проверка​

Токен гостя​

Боты и ассистенты​

Владелец​

Новый рабочий бот​

Изменение, отключение и удаление​

Рабочий бот: client_credentials​

Ассистент: обмен токена владельца​

Перенос существующих ботов​

Типовые отказы​