Как зарегистрировать клиента — Versola Docs
/docs
До 1.00.7.5versola.ioGitHub
RUEN

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

Пошаговая регистрация веб-приложения, мобильного или десктопного приложения и сервисного приложения через мастер создания клиента в консоли администратора Versola

Клиент — приложение, которое запрашивает у Versola токены. Здесь по шагам разобран четырехшаговый мастер создания клиента в консоли администратора для каждого типа. Тип выбирайте внимательно: после создания клиента его не изменить. Что задает каждый тип, описано в разделе Клиент.

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

  • Тенант, которому принадлежит приложение. Его профиль безопасности определяет, что предложит мастер.
  • Client ID, который вас устроит: он не меняется.
  • Для веб-приложения и мобильного или десктопного приложения: точные redirect URI и нужные scope (если их нет, создайте сначала). Мобильному или десктопному приложению нужен https App Link или Universal Link.
  • Для сервисного приложения: нужные разрешения и, для сертификата или ключа, данные сертификата или JWK Set.

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

Выберите тенант в боковом меню и откройте Clients. Таблица показывает каждого клиента с его Type, значением Authenticates with и значком Security (FAPI 2.0 или Standard). Вкладки фильтруют по типу. Нажмите строку, чтобы открыть страницу клиента.

Clients — по строке на клиента, фильтр по типу
Таблица OAuth Clients с фильтрами по типу.

2. Шаг 1: What you are building

Нажмите + Create Client. Выберите Web app, Mobile or desktop app или Service app. Под карточками панель плана перечисляет, что задает тип. Замок обозначает правило, а не выбор. На тенанте Standard панель еще сообщает, что тенант не FAPI 2.0.

Шаг 1 — план для веб-приложения
Шаг 1 мастера клиента: выбран тип «Web app» и список того, что он задает.

Нажмите Continue to basics.

3. Шаг 2: Basics

Заполните идентификацию и, если у типа есть пользователи, redirect URI.

  • Client ID — строчные буквы, цифры и дефисы, начинается с буквы. Выбирается сейчас и не меняется.
  • Client name — показывается пользователям на экранах входа и согласия (с локализацией, по значению на язык). У сервисного приложения показывается только в Central.
  • Redirect URIs — введите каждый URI и нажмите Enter или Add. Они должны в точности совпадать с redirect_uri, который отправляет приложение. Для веб-приложения подсказка говорит: «Edge’s callback, not the page the user ends up on». Мобильное или десктопное приложение принимает https App Link или Universal Link.
  • How the client authenticates — у веб-приложения и мобильного или десктопного приложения это фиксировано: mTLS by edge, регистрировать нечего и хранить секрет не нужно. У мобильного или десктопного приложения еще есть DPoP proof key, который устройство создает в своем keystore.
  • Logout (необязательно) — front-channel или back-channel и его URI. См. Logout.
Шаг 2 — Basics для веб-приложения
Шаг 2 (Basics) мастера клиента для «Web app», заполненный.

Нажмите Continue to sign-in.

4. Шаг 3: Sign-in

Выберите, как пользователи входят в этого клиента. Настройка относится только к нему.

  • Credential — Email, Phone или Login + password.
  • Sign-up — переключателя на шаге нет: регистрация — решение тенанта. В блоке Registration на странице Security вы выбираете режим для email (Closed, Open, Allowlist), настройку Sign-up каждой страны для телефона и Default roles, которые получает новый аккаунт. Клиент, который просит email или телефон, предлагает регистрацию, когда тенант разрешает этот credential. Для Login + password регистрации нет: такие аккаунты создаются в Central.
  • Passkey — предложить passkey на первом экране, с одноразовым кодом после него или без. Для нового клиента включено по умолчанию.
  • Then challenge with — одноразовый код (фиксируется по credential: телефону — SMS) и, по желанию, Then ask for a password.
  • Set up after sign-in — Ask the user to add a passkey. Включено по умолчанию; пользователь может пропустить.
  • Scopes — выберите из scope тенанта. openid есть всегда. Добавьте offline_access, если клиенту нужны refresh token.
  • Consent — First party, no prompt или Ask for consent. Ask for consent делает клиента partner-клиентом: его SMS-коды называют приложение, а согласие потом не отключить.
Шаг 3 — Sign-in: credential phone; регистрация настраивается в Security
Шаг Sign-in мастера клиента: credential phone, одноразовый код по SMS и варианты с passkey.

При Ask for consent шаг показывает еще и подсказку о partner и настройки согласия.

Шаг 3 — Ask for consent делает клиента partner-клиентом

Нажмите Continue to review.

5. Шаг 4: Review

Обзор группирует ваш выбор, у каждой группы ссылка Change на нужный шаг. Для клиента, соответствующего FAPI 2.0, наверху Meets FAPI 2.0. Проверьте Kind, Authenticates with, Token binding и Refresh token: refresh token показан как «none», пока offline_access не в scope. Для веб-приложения и мобильного или десктопного приложения обзор сообщает, что секрет не выдается.

Шаг 4 — Review
Шаг 4 (Review) мастера клиента для «Web app».

Нажмите Create Client. Вы попадете на страницу клиента.

Страница клиента после создания
Страница клиента-веб-приложения, соответствующего FAPI 2.0.

Мобильные и десктопные приложения

Шаги 1–4 те же, с такими отличиями:

  • В шаге 1 в плане есть DPoP-bound access tokens, App Link redirect only и 1 hour access token, refresh rotation on.
  • В шаге 2 redirect URI должен быть https App Link или Universal Link.
  • Scope в шаге 3 по умолчанию включают offline_access. Тогда в обзоре refresh token на 180 дней.
Шаг 1 для мобильного или десктопного приложения
Шаг 1 мастера клиента: выбран тип «Mobile or desktop app» и список того, что он задает.

О вызовах, которые приложение делает дальше, см. Как собрать поток нативного мобильного приложения.

Сервисные приложения

У сервисного приложения нет пользователя, поэтому мастер отличается:

  • В Basics нет redirect URI. В How the client authenticates выберите client secret, key или certificate. client secret предлагается только на тенанте Standard; на тенанте FAPI 2.0 выбирают между key и certificate.
  • С certificate сертификат можно продлевать в вашем PKI с тем же subject или выдавать и продлевать автоматически через EST (estEnrollment). См. Автоматическое продление клиентского сертификата (EST).
  • Шаг 3 — Permissions, а не Sign-in: отметьте разрешения, которые может вызывать сервис. OIDC scope, экрана согласия и refresh token нет.
  • При client secret секрет генерируется, когда вы нажимаете Create Client, и показывается один раз на странице, куда вы попадаете. Сохраните его, пока не ушли: auth хранит только хеш и повторно показать секрет не может. Access token — bearer.
Баннер Client created: скопируйте секрет, прежде чем закрыть его
Баннер после создания сервисного клиента с секретом клиента (показывается один раз).
Шаг 2 для сервисного приложения — выбор способа аутентификации
Шаг 2 (Basics) мастера клиента для «Service app», заполненный.
Шаг 3 для сервисного приложения — разрешения
Шаг 3 (Sign-in) мастера клиента для «Service app».
Шаг 4 — тенант Standard предупреждает, что client_secret не соответствует FAPI 2.0
Шаг 4 (Review) мастера клиента для «Service app».

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

На странице клиента, который аутентифицируется секретом, откройте Client secret и нажмите Rotate secret. Versola выпустит новый секрет, покажет его один раз и оставит прежний рабочим; у клиента появится значок Secret rotation. Раскатайте новый секрет и нажмите Delete old secret.

Что дальше