Что отправляете
Обычный authorize-запрос, но со scopechannel:
Что получаете
После обмена кода на токены — два дополнительных claim:
Без scope
channel типизированных claims не будет. Они не попадут ни в access_token, ни в
id_token, а значит не появятся и в ответе /connect/userinfo — его состав повторяет access token.
Гейт действует во всех режимах поставки, включая встроенный. Даже когда Veriqa подключена
библиотекой в ваш же процесс, приложение получает идентичность штатным обменом
authorize → code → token, а не готовым принципалом. Отдельного «внутреннего» пути, отдающего
claims канала мимо scope, не существует.
Как связать
sub — стабильный идентификатор субъекта; пара channel_type + channel_user_id — адрес
пользователя в конкретном мессенджере. Привязка хранится на вашей стороне: Veriqa не ведёт
учётных записей вашего приложения и не сопоставляет их с каналами.
Практическое следствие: sub для вас — ключ учётной записи. Так же поступают и готовые CMS —
Drupal и TYPO3 хранят его как имя внешней идентичности.
Если учётная запись уже существует
Сценарий работает и как «дозаведение канала» к существующей учётной записи: пользователь, вошедший обычным способом, проходит authorize со scopechannel, а вы сохраняете полученную пару
рядом со своей учётной записью. Отдельного API для этого нет — тот же самый запрос.
Привязка с сервера без входа
Бывает, что редиректа браузера нет: ваш сервер сам хочет получить канал для учётной записи — например, вошедший пользователь просит бота поддержки подключить мессенджер. Это делается через server-to-server вход подтверждения и следующий за ним обмен на токен. Что включает интегратор у клиента:AllowClientCredentials, AllowConfirmationTokenGrant и
openid в AllowedScopes (и channel, если нужны типизированные claims). Разрешение выдаёт интегратор:
ни один параметр вашего запроса раскрытие не расширяет, а claims не выходят за AllowedScopes.
-
Создайте транзакцию подтверждения —
POST /api/transaction/confirmation, безexpected_identities: вы ещё не знаете, какой аккаунт канала подтвердит, — именно это вы и хотите узнать. Покажите пользователюchannel_entryиз ответа. -
Дождитесь исхода —
GET /api/transaction/{id}/resultдоconfirmed. Без ожидаемых идентичностейmatched_typeравенnull— это не отказ, токен выдаётся всё равно. -
Обменяйте транзакцию на токен:
Ответ — обычный ответ token endpoint:
access_token,token_type,expires_inиid_token, безrefresh_token.scope— по RFC 6749 §5.1: он возвращается, только если выданный набор scopes отличается от запрошенного. Обмен выдаёт ровно запрошенный набор, поэтому поляscopeв ответе нет — не требуйте его. -
Сохраните
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}, но хост со своим резолвером вправе составить его иначе — не разбирайте строку; если нужна пара, запрашивайте scopechannel.
string в контракте сообщения типа действия; каждый такой
слот обязан объявить max_length, потолок — 128 символов. Текстовку пишет интегратор, а слоты
(slot_values) при создании заполняет ваш бэкенд тем, что он видит об устройстве, — тот, кто
перешлёт QR-код, подделать эти значения не может: вашим бэкендом он не владеет. Например, шаблон:
service, device и location — слоты, которые заполняет ваш бэкенд. Слот {app}
подтверждения сервер заполняет сам — идентификатором приложения транзакции (client_id), а не
DisplayName клиента, — поэтому
человекочитаемое имя приложения попадает в текстовку только через ваш собственный слот. Пример синтетический: таких имён слотов и такой текстовки в
поставляемой конфигурации нет. Как объявить контракт и шаблон и как выглядят запрос и ответ целиком — в
API серверного подтверждения.
Два бота: передача пользователя вашему боту
Вход принимает бот, которого ведёт Veriqa, а бизнес-сценарии ведёт ваш собственный бот. После входа первый бот показывает кнопку-ссылку во второго, и вашему боту нужно узнать, кто её нажал. Адрес этой кнопки может нести handle связки — одноразовое значение, которое ваш сервер меняет на идентичность только что вошедшего пользователя. Два бота — один из нескольких способов использовать уже работающего бота вместе с Veriqa; сравнение — на странице У меня уже есть бот.-
Запишите
{handle}в адрес кнопки — вRedirectUrlлибо вActionпункта-ссылки меню (Menu и Redirect):Пример синтетический:shop_bot— не настоящий бот. Handle — 22 символа[0-9A-Za-z]; остаток бюджета платформы на стартовый параметр (64 символа в Telegram) — ваш. -
Ваш бот получает handle, когда пользователь нажимает кнопку, — в Telegram это
/start <handle>. -
Ваш сервер обменивает его под токеном client credentials того приложения, в которое вошёл
пользователь (как получить токен; клиенту
нужен
AllowClientCredentials):channel_typeиchannel_user_idвозвращаются только клиенту, у которого вAllowedScopesестьchannel; иначе в ответе одинsub.sub— тот же, что это приложение получает в токенах. -
Сохраните связку у себя — «пользователь моего бота ↔
sub». Veriqa хранит 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 и
возвращается в ваше приложение. Кнопка в вашего бота приходит следом и на вход не влияет — если
пользователь её не нажал, он всё равно вошёл, а ваш бот его ещё не знает и написать ему не может.
Если без перехода в бота пускать пользователя дальше нельзя, сделайте переход обязательным в своём
приложении:
- После входа проверьте, есть ли связка для полученного
sub. Она появляется, когда ваш сервер обменял handle (шаг 3 выше); там, где бот видит тот же идентификатор, что вернул вход, — когда бот получил от этого пользователя первое сообщение. - Связки нет — покажите экран «остался один шаг» со ссылкой в вашего бота и не пускайте дальше. Пользователь у вас уже вошёл, поэтому ссылку на этом экране можно выпустить самим: свой одноразовый токен в стартовом параметре, который ваш бот сопоставит с сессией. Handle от Veriqa для неё не нужен — он есть только в кнопке в чате и живёт недолго.
- Откройте доступ, когда связка появилась — по событию от вашего бота либо опросом со страницы.
Один вход, два канала
Для чувствительных операций подтверждение можно потребовать в двух разных доверенных каналах.