Как зарегистрировать клиента

Клиент — это приложение, которое запрашивает у Versola токены. На этой странице разобрана его регистрация в административной панели. О том, что такое клиент и как он связан с остальными сущностями, читайте в разделе Сущности.

Что понадобится

Тенант, которому принадлежит приложение.
Точный список redirect URI, которые будет использовать приложение.
Скоупы, которые ему нужны (если их еще нет, создайте их в разделе Scopes).
Разрешения, нужные ему от своего имени — актуально только для machine-to-machine клиентов, использующих grant client_credentials.

1. Откройте раздел Clients

Выберите тенант в боковом меню и откройте Clients. В списке отображаются все клиенты этого тенанта с их client ID и бейджем Secret Rotation, если предыдущий секрет еще активен.

Список клиентов в административной панели Versola — Clients — список клиентов выбранного тенанта

Клик по карточке раскрывает полную конфигурацию: redirect URI, скоупы, разрешения, TTL токена и auth flow.

Раскрытая карточка клиента с redirect URI, скоупами, разрешениями и auth flow — Раскрытая карточка клиента

2. Начните создание клиента

Нажмите + Create Client.

Пустая форма создания клиента — Create New Client — пустая форма

3. Заполните идентификацию и параметры токена

Client ID — строчные буквы, цифры и дефисы, начинается с буквы. Неизменяем после создания.
Client Name — человекочитаемое название, отображается в панели и на экранах входа.
Access Token TTL — задается в минутах или часах; держите его коротким и полагайтесь на refresh-токены.

4. Выдайте скоупы и разрешения

OAuth Scopes — скоупы, которые этот клиент может запрашивать. Каждый раскрывается и показывает возвращаемые claims, так что видно, что именно приложение узнает о пользователе.

Permissions используются только когда клиент вызывает API от своего имени через client_credentials. Каждое разрешение раскрывается и показывает эндпоинты, которые оно открывает. Для клиента, действующего только от имени пользователей, оставьте поле пустым.

Форма клиента с заполненными ID, названием, redirect URI, скоупами и разрешениями — Заполненные идентификация, redirect URI, скоупы и разрешения

5. Настройте authorization flow

Секция Authorization Flow определяет сценарий входа для этого клиента:

Primary credentials — что запрашивается первым: phone, email или login + password.
First factor — следующая проверка: otp или password.
Second factor — дополнительная необязательная проверка.
Passkey — предлагать вход по passkey, при необходимости со своим следующим фактором, и предлагать пользователям зарегистрировать passkey.
Session Challenge Equivalences — объявить, что уже пройденная в сессии проверка засчитывается за другую, чтобы не спрашивать вернувшегося пользователя дважды.
OTP Settings — шаблон и канал доставки одноразовых кодов. При первичном credential «телефон» канал фиксируется на SMS.
Forms Theme — тема оформления экранов входа.

Если выключить переключатель Authorization Flow, клиент становится чисто client_credentials: скоупы, redirect URI, темы и настройки выхода к нему неприменимы, и форма их скрывает.

6. Включите самостоятельную регистрацию (опционально)

Переключатель Registration появляется, если primary credential — phone или email и inline password выключен: регистрации нужен входной credential, который проверяется через OTP, поэтому она недоступна для клиентов login + password.

Включите его, чтобы новые пользователи могли создать аккаунт прямо с карточки credential, а не только входить в существующий. Credential для проверки зафиксирован тем же primary credential, что выбран выше.

Форма клиента с раскрытой секцией Registration: выбор challenge и назначенные роли — Registration включена — challenge и роли, выдаваемые при создании аккаунта

Challenge — что происходит после успешного OTP: none (аккаунт создается, и пользователь сразу входит в систему), set password или enroll passkey.
Assigned roles — роли, которые выдаются аккаунту в момент создания, для текущего выбранного тенанта. Нужна хотя бы одна роль.

Уже зарегистрированный credential никогда не раскрывает этот факт: при его вводе форма молча переключается на обычный вход по OTP вместо продолжения регистрации, так что регистрацию нельзя использовать для перебора существующих аккаунтов.

7. Добавьте redirect URI

Введите URI и нажмите Enter или Add. Значения должны точно совпадать с тем, что приложение отправит в redirect_uri; все остальное будет отклонено на /authorize.

8. Настройте выход (опционально)

Выберите front-channel или back-channel logout и укажите соответствующий URI, если приложение должно узнавать о завершении сессии.

Если клиент работает через edge, укажите собственные эндпоинты edge вместо URL самого клиента: /logout/frontchannel и /logout/backchannel. Edge предоставляет оба «из коробки» и завершает сессию для всех клиентов, проходящих через него, — реализовывать эти эндпоинты самостоятельно не нужно.

9. Создайте клиента и сохраните секрет

Нажмите Create Client. Versola сгенерирует секрет клиента и покажет его один раз.

Баннер со сгенерированным секретом клиента — Секрет клиента показывается только один раз — скопируйте его до закрытия баннера

Сразу перенесите его в свое хранилище секретов. Позже его получить нельзя; если секрет утерян, выполните ротацию на экране редактирования клиента.

Ротация секрета

Откройте клиента на редактирование и нажмите Rotate Secret. Versola выпустит новый секрет, оставив предыдущий действительным и пометив клиента бейджем Secret Rotation. Разверните новый секрет, затем нажмите Delete old secret, чтобы завершить ротацию.

Дальше

Зарегистрируйте API, которые будет вызывать этот клиент: Как зарегистрировать ресурс
Добавьте клиента в Audience этих ресурсов, чтобы он мог получать для них токены.