Перейти к основному содержанию
Одно действие пользователя даёт два результата: он входит, а ваш продукт получает живой канал — MAX, Telegram, WhatsApp, другой мессенджер или Email, смотря где подтвердили. Дальше по этому каналу можно отправлять уведомления, подтверждения и сервисные сообщения, не выпрашивая отдельно контакт.

Что отправляете

Обычный authorize-запрос, но со scope channel:

Что получаете

После обмена кода на токены — два дополнительных claim: Без scope channel типизированных claims не будет. Они не попадут ни в access_token, ни в id_token, а значит не появятся и в ответе /connect/userinfo — его состав повторяет access token.
Гейт закрывает отдельные claims, но не значение. При резолвере идентичности по умолчанию sub формируется как {channel_type}:{channel_user_id}, то есть приложение, разрезав строку по двоеточию, получит те же две части, не запросив scope. Рассчитывайте на гейт как на способ не работать с идентификаторами канала там, где они не нужны, а не как на средство скрыть их.
Гейт действует во всех режимах поставки, включая встроенный. Даже когда Veriqa подключена библиотекой в ваш же процесс, приложение получает идентичность штатным обменом authorize → code → token, а не готовым принципалом. Отдельного «внутреннего» пути, отдающего claims канала мимо scope, не существует.

Как связать

sub — стабильный идентификатор субъекта; пара channel_type + channel_user_id — адрес пользователя в конкретном мессенджере. Привязка хранится на вашей стороне: Veriqa не ведёт учётных записей вашего приложения и не сопоставляет их с каналами. Практическое следствие: sub для вас — ключ учётной записи. Так же поступают и готовые CMS — Drupal и TYPO3 хранят его как имя внешней идентичности.

Если учётная запись уже существует

Сценарий работает и как «дозаведение канала» к существующей учётной записи: пользователь, вошедший обычным способом, проходит authorize со scope channel, а вы сохраняете полученную пару рядом со своей учётной записью. Отдельного API для этого нет — тот же самый запрос.
Посмотреть вживую. В онлайн-примере Helio клиент, вошедший через мессенджер, добавляет к учётной записи адрес почты: подтверждает его через канал Email.

Привязка с сервера без входа

Бывает, что редиректа браузера нет: ваш сервер сам хочет получить канал для учётной записи — например, вошедший пользователь просит бота поддержки подключить мессенджер. Это делается через server-to-server вход подтверждения и следующий за ним обмен на токен. Что включает интегратор у клиента: AllowClientCredentials, AllowConfirmationTokenGrant и openid в AllowedScopes (и channel, если нужны типизированные claims). Разрешение выдаёт интегратор: ни один параметр вашего запроса раскрытие не расширяет, а claims не выходят за AllowedScopes.
  1. Создайте транзакцию подтверждения — POST /api/transaction/confirmation, без expected_identities: вы ещё не знаете, какой аккаунт канала подтвердит, — именно это вы и хотите узнать. Покажите пользователю channel_entry из ответа.
  2. Дождитесь исхода — GET /api/transaction/{id}/result до confirmed. Без ожидаемых идентичностей matched_type равен null — это не отказ, токен выдаётся всё равно.
  3. Обменяйте транзакцию на токен:
    Ответ — обычный ответ token endpoint: access_token, token_type, expires_in и id_token, без refresh_token. scope — по RFC 6749 §5.1: он возвращается, только если выданный набор scopes отличается от запрошенного. Обмен выдаёт ровно запрошенный набор, поэтому поля scope в ответе нет — не требуйте его.
  4. Сохраните sub из id_token рядом со своей учётной записью.
Правила обмена:
  • scope обязан содержать openid; channel добавляет channel_type и channel_user_id; всё остальное — в пределах AllowedScopes. offline_access отвергается с invalid_scope, как и scope без openid. Нет transaction_id — invalid_request.
  • Транзакция погашается однократно. Повторный обмен получает invalid_grant — ту же ошибку с тем же описанием, что и неизвестный идентификатор, транзакция другого клиента, ещё не завершённая транзакция или уже удалённая по истечении CompletedRetentionSeconds. Ответы намеренно не различают эти причины, поэтому обменивайте сразу после confirmed. Из двух одновременных обменов токен получает ровно один.
  • Однократность относится к погашению, а не к чтению claims: access_token того же ответа несёт те же claims и до истечения отдаёт их через /connect/userinfo.
  • Ключ привязки — sub целиком. При резолвере идентичности по умолчанию он формируется как {channel_type}:{channel_user_id}, но хост со своим резолвером вправе составить его иначе — не разбирайте строку; если нужна пара, запрашивайте scope channel.
Что узнаёт приложение и кто предупреждает пользователя. При включённом grant ваше приложение получает канальную идентичность подтвердившего в каждом подтверждении этого клиента, а не только там, где она нужна для дела. Отдельного вопроса «передать мои данные?» Veriqa пользователю не задаёт: предупреждение о передаче данных и контекст запроса задаются в текстовке action_type интегратора и в слотах, которые заполняет ваш бэкенд. Veriqa не проверяет, что такое предупреждение есть во всех типах действий такого клиента, — это ответственность интегратора. Вход — на предъявителя: кто первым его откроет, тот и подтвердит, и sub будет его, — поэтому контекст запроса и должен стоять в текстовке.
Контекст запроса собирается из слотов типа string в контракте сообщения типа действия; каждый такой слот обязан объявить max_length, потолок — 128 символов. Текстовку пишет интегратор, а слоты (slot_values) при создании заполняет ваш бэкенд тем, что он видит об устройстве, — тот, кто перешлёт QR-код, подделать эти значения не может: вашим бэкендом он не владеет. Например, шаблон:
Здесь service, device и location — слоты, которые заполняет ваш бэкенд. Слот {app} подтверждения сервер заполняет сам — идентификатором приложения транзакции (client_id), а не DisplayName клиента, — поэтому человекочитаемое имя приложения попадает в текстовку только через ваш собственный слот. Пример синтетический: таких имён слотов и такой текстовки в поставляемой конфигурации нет. Как объявить контракт и шаблон и как выглядят запрос и ответ целиком — в API серверного подтверждения.

Два бота: передача пользователя вашему боту

Вход принимает бот, которого ведёт Veriqa, а бизнес-сценарии ведёт ваш собственный бот. После входа первый бот показывает кнопку-ссылку во второго, и вашему боту нужно узнать, кто её нажал. Адрес этой кнопки может нести handle связки — одноразовое значение, которое ваш сервер меняет на идентичность только что вошедшего пользователя. Два бота — один из нескольких способов использовать уже работающего бота вместе с Veriqa; сравнение — на странице У меня уже есть бот.
  1. Запишите {handle} в адрес кнопки — в RedirectUrl либо в Action пункта-ссылки меню (Menu и Redirect):
    Пример синтетический: shop_bot — не настоящий бот. Handle — 22 символа [0-9A-Za-z]; остаток бюджета платформы на стартовый параметр (64 символа в Telegram) — ваш.
  2. Ваш бот получает handle, когда пользователь нажимает кнопку, — в Telegram это /start <handle>.
  3. Ваш сервер обменивает его под токеном client credentials того приложения, в которое вошёл пользователь (как получить токен; клиенту нужен AllowClientCredentials):
    channel_type и channel_user_id возвращаются только клиенту, у которого в AllowedScopes есть channel; иначе в ответе один sub. sub — тот же, что это приложение получает в токенах.
  4. Сохраните связку у себя — «пользователь моего бота ↔ sub». Veriqa хранит handle только до обмена или истечения срока, а связку не хранит.
Проверьте, кто нажал кнопку. Кнопку можно переслать, и handle вашему боту принесёт тот, кто её нажал. Там, где платформа даёт человеку один идентификатор для всех ботов, — например, в Telegram — сравните отправителя сообщения (from.id) с channel_user_id из ответа и откажите при расхождении. Veriqa эту сверку за вас не делает: эндпоинт принимает только handle. Для сверки клиенту нужен scope channel. Там, где каждый бот видит свой идентификатор одного и того же человека, либо у тенанта включена псевдонимизация (channel_user_id тогда псевдоним), сверять не с чем — handle остаётся ссылкой на предъявителя: связку получает тот, кто нажал кнопку первым.
Правила обмена:
  • Handle обменивается один раз и только приложением, которому принадлежит вход. Другое приложение получает 404, а handle остаётся действительным для своего.
  • Он живёт недолго: Veriqa:TransactionEngine:CompletedRetentionSeconds (по умолчанию 600 секунд) с момента отправки кнопки. Кнопка остаётся в чате: нажатая позже, она приносит вашему боту handle, на который эндпоинт отвечает 404, — предложите пользователю войти заново.
  • 404 — один ответ на отсутствующий или пустой handle, на неизвестный, истёкший и уже обменянный, на handle чужого приложения — причины намеренно не различаются. Тело не в формате JSON — 400, Content-Type, отличный от JSON, — 415; без токена — 401; токен, выданный пользователю, — 403. 500 означает, что идентичность прочитать не удалось, — такой handle тоже израсходован.
  • Handle действует и до того, как браузер завершил вход — и тогда, когда вкладку закрыли и он его не завершит. Идентичность к этому моменту подтверждена пользователем в канале.
  • Нескольким репликам нужно общее хранилище. Без Redis-реализаций канальных хранилищ handle находит только та реплика, которая его выпустила.
  • Кнопка без handle допустима там, где он не нужен: в Telegram ваш бот видит тот же идентификатор пользователя, что вход вернул в channel_user_id, поэтому уже связанная учётная запись узнаётся без обмена.
  • Эндпоинт работает только для входов; за подтверждением, которое создал ваш сервер, кнопка не следует.

Если без вашего бота вход не имеет смысла

Вход завершается, когда пользователь подтвердил его в канале: браузер получает code и возвращается в ваше приложение. Кнопка в вашего бота приходит следом и на вход не влияет — если пользователь её не нажал, он всё равно вошёл, а ваш бот его ещё не знает и написать ему не может. Если без перехода в бота пускать пользователя дальше нельзя, сделайте переход обязательным в своём приложении:
  1. После входа проверьте, есть ли связка для полученного sub. Она появляется, когда ваш сервер обменял handle (шаг 3 выше); там, где бот видит тот же идентификатор, что вернул вход, — когда бот получил от этого пользователя первое сообщение.
  2. Связки нет — покажите экран «остался один шаг» со ссылкой в вашего бота и не пускайте дальше. Пользователь у вас уже вошёл, поэтому ссылку на этом экране можно выпустить самим: свой одноразовый токен в стартовом параметре, который ваш бот сопоставит с сессией. Handle от Veriqa для неё не нужен — он есть только в кнопке в чате и живёт недолго.
  3. Откройте доступ, когда связка появилась — по событию от вашего бота либо опросом со страницы.
Если сайта нет и ваш продукт целиком живёт в боте, отдельная проверка не нужна: обмен handle и есть вход в бота, а пользователь, не нажавший кнопку, просто не вошёл.

Один вход, два канала

Для чувствительных операций подтверждение можно потребовать в двух разных доверенных каналах.