Клиент — приложение, которое просит у Versola токены. В консоли администратора при создании выбирают один из трех типов (kind), и тип определяет, как клиент аутентифицируется и как привязаны его токены. На этой странице — что задает каждый тип и что можно менять на странице клиента потом. Общая картина описана в разделе Сущности.
Типы клиентов
Мастер спрашивает «What are you building?». Каждому типу соответствует template в Central API, а он задает applicationType.
| Тип | Описание в консоли | applicationType | template |
|---|---|---|---|
| Web app | Сайт с бэкендом. Пользователи входят, токены остаются на сервере. | web | web |
| Mobile or desktop app | Приложение на устройстве. У него есть собственный ключ. | native | device |
| Service app | Код, который вызывает ваши API без пользователя. | web | service |
После создания тип не меняется. У клиента, зарегистрированного через Central API без шаблона, тип не хранится; консоль выводит его из applicationType, redirect URI и сценария входа.
Что фиксирует каждый тип
Эти правила перечислены в панели плана мастера. Замок обозначает правило, заданное типом, а не выбор. На тенанте Standard панель добавляет заметку, что тенант не FAPI 2.0.
| Web app | Mobile or desktop app | Service app | |
|---|---|---|---|
| Credential | mTLS через edge: Central выпускает сертификат, которым аутентифицируется edge; хранить секрет не нужно (tls_client_auth) | То же: mTLS через edge, плюс DPoP-ключ, который устройство создает в своем keystore | Выбор: client secret (только на тенантах Standard), ключ (private_key_jwt) или сертификат (mTLS) |
| Edge перед клиентом | Да. Токены остаются внутри edge за cookie сессии и не попадают в браузер | Да | Нет |
| Привязка токенов | Access token, привязанный к сертификату (RFC 8705), к сертификату edge | Access token, привязанный к DPoP-ключу (RFC 9449). Сертификат edge один на все установки, привязать к нему нельзя | DPoP — с ключом, привязка к сертификату — с сертификатом. Client secret дает bearer-токены |
| PKCE | Только S256; не настройка | Только S256; не настройка | Неприменимо: запроса авторизации нет |
| Pushed authorization requests (PAR) | Включены | Включены | Неприменимо |
| Signed request objects (JAR) | Выключены, не требуются | Недоступны: у распространяемого бинарника нет собственного закрытого ключа | Неприменимо |
| Redirect URI | Callback edge | Только https App Link или Universal Link. Кастомную схему может занять любое приложение на устройстве | Нет |
| Access token TTL | 1 час | 1 час, ротация refresh включена. DPoP требует не меньше 1 часа | 1 час |
| Вход, scope, согласие | Есть | Есть | Нет. У клиента разрешения, а не OIDC scope, и нет экрана согласия |
| Refresh token | Только с offline_access | Только с offline_access; у нового мобильного приложения offline_access включен по умолчанию | Не выдается: клиент запрашивает новый access token своим credential |
Приложения за edge остаются в рамках FAPI в обоих профилях. Полный набор правил по профилям — в Профилях безопасности и Токенах с привязкой к отправителю.
Страница клиента
Если открыть клиента из списка, появится его страница. У каждой группы настроек своя кнопка Edit со своими Cancel и Save.
Вверху — значки: ID клиента, тип, Standard или FAPI 2.0, и Secret rotation, пока действует прежний секрет. Баннер Meets FAPI 2.0 перечисляет пройденные проверки (аутентификация ключом или сертификатом, токены с привязкой к отправителю, PAR, https в redirect URI). Если не соответствует, баннер называется Standard profile client, not FAPI 2.0 и показывает, чего не хватает. Баннер считается для каждого клиента, какой бы профиль ни был у тенанта.
| Секция | Что в ней |
|---|---|
| Type | Kind и Authenticates with. Выбирается при создании и не меняется. |
| Token binding and requests | Token binding, Authorization requests (PAR) и Request signing (JAR). Заблокированы там, где их задает тип. |
| General | Name (с локализацией) и Redirect URIs. Client ID виден, но не редактируется. |
| Scopes (у сервисного приложения — Permissions) | См. Scopes и разрешения. |
| Sign-in | Credential и факторы после него. У сервисного приложения секции нет. |
| Tokens | Access token, Refresh token и, для DPoP-клиентов, DPoP proof keys. |
| Keys | Зарегистрированные открытые ключи клиента, который подписывает ими. |
| Client secret | Только у клиента, который аутентифицируется секретом. |
| Ownership | First party app или Partner app и настройки согласия партнера. |
| Branding and logout | Forms theme и Logout. |
| Authorization Presets | Пресеты входа для edge. У сервисного приложения нет. |
| Delete client | Сессии заканчиваются, токены перестают работать. Отменить нельзя. |
Как клиент аутентифицируется
Authenticates with — это authMethod, он фиксируется при создании. Чтобы его сменить, удалите клиента и зарегистрируйте заново. Консоль называет методы так:
| Подпись | authMethod | Примечания |
|---|---|---|
| Certificate, issued to edge | tls_client_auth | Веб- и мобильные клиенты за edge. Регистрировать нечего. |
| Certificate | tls_client_auth | Сервисное приложение. Вы указываете поле сертификата, по которому узнают клиента (Recognised by: subject_dn, san_dns, san_uri, san_ip или san_email), и ожидаемое значение. |
| Self-signed certificate | self_signed_tls_client_auth | Auth сверяет предъявленный сертификат с набором ключей, который вы зарегистрировали. |
| Signing key | private_key_jwt | Вы регистрируете JWK Set до 10 открытых ключей или просите Central API сгенерировать пару. |
| Client secret | client_secret | Только тенанты Standard. |
| None (public client) | none | Публичный нативный клиент. Только тенанты Standard. |
Пару ключей клиента private_key_jwt Central может сгенерировать при регистрации через generateJwks (ES256, PS256 или RS256). Закрытый ключ возвращается один раз как privateKey и нигде не хранится. Эта возможность есть в Central API; форма консоли просит JWK Set, который у вас уже есть.
Автоматическое продление сертификата (EST)
Веб- или сервисный клиент с authMethod: tls_client_auth может сам получать и продлевать свой сертификат через EST (RFC 7030). При регистрации сертификата у него нет.
| Где | Имя | Что означает |
|---|---|---|
| Регистрация (Central API) | estEnrollment | true включает EST для клиента. По умолчанию false. Требует tls_client_auth, а тенант должен задать mtlsCertificateHeader. Несовместим с issueEdgeClientCertificate, enrollEdgeClientCertificate и сертификатом, который вы передаете сами. Subject сертификата — mtlsAuth, а если он не задан, CN=<client>,OU=<tenant>,O=Versola |
GET /configuration/clients, поле est | pending, certificateExpiresAt, chainEndsAt | Не прошел ли клиент выдачу, когда истекает его последний сертификат и когда заканчивается цепочка продлений (null при auto-extend или до выдачи) |
POST /configuration/clients/est/enrollment-tokens?clientId=&validityHours= | Одноразовый токен выдачи, по умолчанию 24 часа, не больше 168. Показывается один раз вместе с subject, который должен назвать запрос | |
POST /configuration/clients/est/extend?clientId= | Начинает цепочку заново после того, как она достигла client-identity.max-age | |
POST /configuration/clients/est/revoke?clientId= | Лишает права продлевать все выпущенные до этого сертификаты и отзывает открытый токен |
См. Клиентские сертификаты и их продление и Автоматическое продление клиентского сертификата (EST).
Client secret
Client secret генерируется при создании клиента и показывается один раз. После Create Client вы попадаете на страницу клиента с баннером Client created, в котором секрет и кнопка Copy secret. Auth хранит только хеш и показать секрет повторно не может.
Секция Client secret сообщает: «Set. It is shown once, when it is created or rotated.» Rotate secret выпускает новый секрет, показывает его один раз в таком же баннере и оставляет прежний рабочим; у клиента появляется значок Secret rotation, а кнопка превращается в Delete old secret. Раскатайте новый секрет и нажмите Delete old secret.
Токены
| Настройка | По умолчанию | Примечания |
|---|---|---|
| Access token | 1h | До 24 часов (86400 s). Не меньше 1 часа, если клиент требует токены, привязанные к DPoP. Задается в минутах или часах. |
Refresh token (refreshTokenTtl) | 180 дней (15552000 s) | Показывается в днях. Выдается только клиенту со scope offline_access. Срок фиксируется при выдаче и считается от входа: использование refresh token его не продлевает, по окончании пользователь входит заново. |
| DPoP proof keys | Любые, что принимает сервер | dpopSigningAlgs клиента (ES256, PS256, RS256 из числа тех, что объявляет сервер) и минимальный размер RSA-ключа. |
У клиента с аутентификацией сертификатом токены привязаны к этому сертификату сами по себе, поэтому настройки DPoP рядом нет. Мобильное или десктопное приложение привязано к DPoP-ключу. Где тип оставляет выбор, страница предлагает Require DPoP-bound access tokens, Require Pushed Authorization Requests (PAR) и Require signed request objects (JAR).
Scopes и разрешения
У веб-приложения и у мобильного или десктопного приложения Scopes — это scope, которые клиент может запрашивать; они определяют получаемые claim. openid есть всегда. Собственных разрешений у такого клиента нет: что могут вызывать его пользователи, определяют их роли.
У сервисного приложения секция называется Permissions: эндпоинты, которые клиент может вызывать от своего имени через grant client_credentials. Edge читает permissions клиента только для сервисного токена. OIDC scope у сервисного приложения нет: описывать некого.
Вход, регистрация и согласие
Sign-in описывает, что пользователь видит на первом экране этого клиента и после него. Два клиента одного тенанта могут по-разному впускать одних и тех же пользователей.
- Credential — Email, Phone или Login + password. В редакторе Sign-in на странице клиента те же настройки подписаны иначе: Primary credentials (
phone,email,login + password,passkey,inline password), First factor, Second factor, Session Challenge Equivalences (challenge, уже пройденный в сессии, засчитывается как другой) и OTP Settings (OTP Template, OTP channel). - Sign-up — у клиента такой настройки нет. Клиент, у которого первый экран просит email или телефон, без логина и без пароля на том же экране, предлагает регистрацию, когда тенант разрешает этот credential: email — по режиму Email registration, номер телефона — по настройке Sign-up его региона, обе на странице Security. Новый пользователь подтверждает адрес одноразовым кодом и, если вход клиента требует пароль, задает его. Аккаунт получает Default roles тенанта. Адрес, который тенант не разрешает регистрировать, или уже зарегистрированный тихо превращается в обычный вход и не раскрывает, какой из двух случаев имел место. Для Login + password и для карточки с паролем на первом экране регистрации нет.
- Passkey — предложить passkey на первом экране как альтернативу. Он заменяет credential и его challenge. Для нового клиента включено по умолчанию.
- Then challenge with — одноразовый код (SMS для телефона, письмо для email) и, по желанию, пароль после него. Для Login + password — необязательный одноразовый код после пароля с выбором канала доставки.
- Set up after sign-in — предложить добавить passkey после входа по коду. Включено по умолчанию; пользователь может пропустить.
Согласие и partner-клиенты
У Ownership два варианта: First party app (свое приложение: пользователя не спрашивают о согласии, обычный выбор) и Partner app (чужое приложение: пользователя спрашивают о согласии). В мастере у партнерского приложения есть Reuse the grant for (30 days, по умолчанию 90 days, Until the user revokes it или Ask every time) и под ним Let the user grant part of it, а также Logo URI, Privacy policy URI и Terms of service URI. На странице клиента — Partial grants (Let the user deselect optional scopes; openid снять нельзя, а offline_access — только если вы это разрешили, см. ниже), Required scopes, Long-lived access, Remember (until revoked или for a period, по умолчанию 90 дней; значение клиента, созданного раньше, сохраняется), Logo URI, Privacy policy и Terms of service. Расширенный scope всегда запрашивается заново. Logo URI и название клиента — это то, что пользователь видит о приложении, которое просит согласие: его иконка (первая буква названия, если логотипа нет или он не загрузился) стоит в карточке экрана согласия, а сама карточка называет вошедшего пользователя и показывает его картинку, если у пользователя есть claim picture с адресом https. Экраны входа, кода, пароля и passkey такого приложения тоже называют его внутри карточки. Собственное приложение на них не объявляется; бренд над карточкой — всегда логотип тенанта или словесный знак Versola, если логотипа нет.
Partner app — клиент, который запрашивает согласие. В мастере он сразу предлагает и оформление: Forms Theme и Appearance for this app (см. Внешний вид партнерского приложения) в блоке Branding, чтобы партнер выглядел правильно с первого входа. У first-party приложения в мастере оформления нет. Консоль помечает его значком Partner. Из этого следует две вещи:
- SMS-коды называют приложение. Консоль переключает шаблон OTP на предустановленный шаблон
partner, в тексте которого плейсхолдер{{appName}}заменяется на имя клиента, если вы не выбрали шаблон вручную. - После создания клиента согласие отключить нельзя. На странице клиента строка Ownership читается как Partner app (users are asked for consent, cannot be turned off), а в редакторе First party app недоступен, с пояснением «A partner app asks users for consent for good: it cannot be made a first party app.» Чтобы вернуть клиента в first party, удалите его и зарегистрируйте заново.
Required scopes появляется, когда включен Partial grants. Нажмите на scope, чтобы сделать его обязательным: на экране согласия он остается отмеченным, а сервер авторизации отклоняет grant без него. Пользователь по-прежнему может отказать целиком. Обязательный scope, которого клиент не запрашивал, игнорируется. openid обязателен всегда и в списке не показывается.
Long-lived access — так пользователи видят scope offline_access. По умолчанию пользователь должен его выдать или отклонить запрос целиком. Если отметить Let the user turn off long-lived access, пользователь сможет снять галочку: клиент тогда не получит refresh token и должен будет заново провести пользователя через вход, когда access token истечет. Включайте это только для клиентов, которые так умеют. Если указать offline_access в поле API requiredScopes, он остается обязательным.
В новых установках scope offline_access на экране согласия называется Long-lived access (Длительный доступ по-русски). В существующей установке прежнее описание остается, пока вы не измените scope на странице Scopes. Имя клиента на экране согласия выводится жирным.
partner — не отдельное поле: Central API считает партнером клиента с consentFlow и отказывается убирать этот flow (400). Менять flow по-прежнему можно. Появилось в 0.7.1.
Внешний вид партнерского приложения
Партнерское приложение может выглядеть иначе, чем остальной тенант: свой цвет бренда, скругления, фон страницы или цветовая схема поверх темы, которую оно использует. Выберите их при создании (Partner app на шаге входа в мастере) или откройте Edit branding and logout на странице клиента; у клиента с экраном согласия Appearance for this app стоит под Forms theme. У остальных клиентов блока нет: свой внешний вид есть только у приложения, которое запрашивает согласие пользователя, а собственный (first-party) клиент выглядит как продукт, которому принадлежит.
В блоке те же пять значений, что у темы: Brand colour, Page background, Background style, Shape и Colour scheme. Пока вы ничего не меняли, каждое показывает значение темы клиента. Заданное вами значение помечено Overridden со значением темы, а Reset возвращает его; Clear overrides сбрасывает все. Значение, равное значению темы, переопределением не сохраняется. Над значениями стоит настоящий предпросмотр формы Consent: тема клиента с его собственными значениями поверх, с именем клиента и его Logo URI, ровно так, как увидят пользователи. Показан один фиксированный пример запроса; Light и Dark переключают цветовую схему (недоступно, если схема приложения зафиксирована), Mobile и Desktop меняют ширину. Предпросмотр строит Central, поэтому он совпадает с настоящим экраном. Если у Central нет активной формы Consent или у вашей роли нет права читать формы, вместо него показывается одна строка, а значения продолжают работать. На странице клиента то, что приложение меняет, перечислено в Appearance for this app.
auth добавляет после таблицы стилей темы одно правило только с измененными значениями, поэтому они перекрывают тему, а все остальное по-прежнему берется из нее. Собственный CSS темы остается под значениями клиента. Если тема сохранена только с CSS, консоль ее значений не знает: каждое значение подписано Set by the theme’s CSS, пока вы не выберете свое, и выбор всегда сохраняется как переопределение, даже если он совпадает со встроенной темой. Переопределения применяются поверх этого CSS, но только там, где он построен на переменных из раздела Themes. CSS, написанный под другие имена, например --accent, за ними не следует. Своих переопределений токенов и поля CSS у клиента нет: они принадлежат теме.
В Central API переопределения — это themeOverrides в запросах web- и native-клиента, с теми же полями, что у overrides темы (brand, shape, surface, mode, background; последнее — glow, linear, horizon или flat). При обновлении отсутствующее значение оставляет их как есть, а пустой объект очищает. Central отвечает 400 на непустые themeOverrides у клиента без consentFlow (с учетом consentFlow, который задает сам запрос); пустой объект принимается всегда, так что оставшиеся с прежних времен переопределения можно очистить. Если убрать согласие в консоли, переопределения тоже очищаются. У сервисного приложения экранов входа нет, поэтому нет и переопределений.
Logout
Logout — один канал или никакого: Not notified, Front-channel (скрытый iframe, нужен открытый браузер) или Back-channel (сервер — сервер) в мастере; none, front-channel или back-channel в Logout Settings на странице клиента. Для выбранного канала укажите logout URI. Если клиент стоит за edge, укажите собственные эндпоинты edge, /logout/frontchannel и /logout/backchannel: edge очищает сессию для каждого клиента, который через него идет.
Authorization presets
Authorization Presets настраивают пути edge /login/{presetId} и /logout/{presetId} для клиента. У пресета есть Preset ID, Description, один из Redirect URI клиента, Scopes, Response Type, необязательные UI Locales и Custom Parameters, Post-login redirect URI, необязательный Post-logout redirect URI и необязательные домен и путь cookie сессии. На странице клиента значок ✎ рядом с Authorization Presets открывает Edit Authorization Presets; + Add Preset открывает форму ниже. См. Как защитить API с помощью edge.
