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

Ресурс — это upstream API за edge. Его регистрация сообщает edge, куда проксировать трафик, кто может его вызывать и что должно быть истинно для каждого отдельного эндпоинта. Общая картина описана в разделе Сущности.

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

Абсолютный URI upstream API.
Клиенты, которые будут его вызывать — они должны быть уже зарегистрированы (Как зарегистрировать клиента).
Список эндпоинтов (метод + путь), которые вы хотите открыть.
Решение о том, будет ресурс internal или public (см. шаг 3).

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

Выберите тенант и откройте Resources. На каждой карточке показаны resource URI, resource ID и бейджи Internal и Secret Rotation.

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

Клик по карточке раскрывает audience и зарегистрированные эндпоинты.

Раскрытая карточка ресурса с audience и эндпоинтами — Раскрытая карточка ресурса

2. Начните создание ресурса

Нажмите + Create Resource.

Пустая форма создания ресурса — Create Resource — пустая форма

3. Заполните идентификацию, audience и тип

Resource ID — строчные буквы, цифры и дефисы, начинается с буквы. Он становится частью пути прокси: edge направляет /resources/{resourceId}/* на resource URI. После создания неизменяем, значение edge зарезервировано.

Absolute resource URI — абсолютный URI с пустым путем, без query и fragment, например http://invoices-api.billing.svc.cluster.local:8080 для сервиса, доступного внутри кластера, или https://invoices.example.com для сервиса, опубликованного вовне. Схема resource:// зарезервирована.

Audience — клиенты, которым разрешено запрашивать этот ресурс. Начните вводить client ID, выберите его из подсказок и нажмите Add audience. Клиент, не указанный здесь, не получит токен для этого ресурса: auth отклонит запрос на /authorize или /token.

Resource type:

Internal — Versola генерирует секрет, и edge аутентифицируется к upstream через Authorization: Basic {resourceId}:{secret}. Токен вызывающего до upstream API не доходит, поэтому самому API валидация токенов не нужна — а значит upstream-сервис должен жить во внутренней зоне без прямого доступа из веба: единственный вызывающий для него — edge. Токены, выпущенные для такого ресурса, несут в aud значение resource://{resourceId}, а не resource URI. Обычный выбор для сервисов, живущих за edge.
Public — секрета нет. edge выполняет ровно те же проверки — audience, роли/разрешения, выражение allow эндпоинта — но вместо собственных Basic credentials передает access-токен вызывающего без изменений, и upstream API сам отвечает за его валидацию. Токены, выпущенные для такого ресурса, несут в aud собственный URI ресурса.

Форма ресурса с заполненными ID, URI, audience и типом internal — Resource ID, URI, audience и тип

4. Добавьте эндпоинты

Нажимайте Add endpoint для каждой пары метод + путь, которую нужно открыть. Эндпоинт — единица авторизации: все, что проверяется на каждый запрос, настраивается здесь.

Редактор эндпоинта с методом, путем, allow-выражением, step-up и inject — Редактор эндпоинта

Метод и относительный путь. Путь сопоставляется с частью запроса, следующей за /resources/{resourceId}. Каждый сегмент — либо литерал (строчные или заглавные буквы, цифры и дефисы), либо параметр {name}, соответствующий ровно одному сегменту, как в /tenants/{tenantId}/orders/{orderId}. Имена параметров в пути не должны повторяться, а два эндпоинта одного метода не могут отличаться только именами параметров. Литеральный эндпоинт всегда имеет приоритет над параметризованным, поэтому /users/me сохраняет свои правила рядом с /users/{userId}. В метриках и трейсах используется зарегистрированный шаблон, а не сопоставленные значения.

Fetch userinfo. Включите, чтобы перед вычислением правил загрузить claims владельца ресурса из auth. Они станут доступны в CEL как user. Это дополнительный вызов на каждый запрос, поэтому включайте только там, где выражение действительно их использует.

Allow (CEL). Булево выражение, которое должно вернуть true, чтобы вызов был авторизован. Пустое значение отключает проверку. Доступные корни:

Корень	Содержимое
`token`	Claims проверенного access-токена — `token.sub`, `token.scope`, …
`user`	Claims из userinfo, только при включенном Fetch userinfo
`request.path.params`	Параметры пути, сопоставленные сегментами `{name}` эндпоинта
`request.query` / `request.queryAll`	Query-параметры: первое значение / все значения
`request.headers` / `request.headersAll`	Заголовки запроса: первое значение / все значения
`request.body`	Разобранное JSON-тело, когда content-type — `application/json`

Например:

"read" in token.scope && user.department == "engineering"

Панель проверяет выражение перед сохранением, поэтому синтаксическая ошибка или небулев результат блокируют сохранение, а не приводят к отказу во время запроса.

Step-up condition и ACR. Когда step-up condition возвращает true, вызывающий должен иметь указанный уровень аутентификации; иначе edge попросит его пройти аутентификацию повторно (RFC 9470). Так защищают чувствительное подмножество в остальном обычного API.

Max auth age. Отклонить вызов, если владелец аутентифицировался раньше указанного числа секунд назад, независимо от срока действия токена.

Inject. Каждое правило записывает вычисленное значение в запрос к upstream — в header, query-параметр или поле верхнего уровня JSON-body. Значение задается CEL-выражением над теми же корнями, что и Allow. Внедренные значения перезаписывают переданные клиентом, поэтому это безопасный способ передать upstream проверенную идентичность — например, заголовок x-user-id со значением token.sub.

5. Создайте ресурс и сохраните секрет

Нажмите Create Resource. Для internal-ресурса Versola сгенерирует секрет и покажет его один раз.

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

Настройте upstream-сервис на прием HTTP Basic credentials, где имя пользователя — resource ID, а пароль — этот секрет.

6. Сделайте эндпоинты доступными

Регистрация эндпоинта сама по себе никому не дает доступа. Чтобы завершить настройку:

Создайте Permission и привяжите к нему нужные эндпоинты.
Добавьте это разрешение в Role и назначьте роль пользователям тенанта — или, для интеграции через client_credentials, привяжите разрешение напрямую к клиенту.

Пока эндпоинт не покрыт разрешением, которым обладает вызывающий, edge отвечает 403.

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

Откройте ресурс на редактирование и нажмите Rotate Secret. Новый секрет будет показан один раз, а предыдущий останется действительным — карточка получит бейдж Secret Rotation. Сначала настройте upstream-сервис на прием обоих секретов сразу — edge может по-прежнему использовать старый, пока вы разворачиваете новый. Как только upstream принимает оба секрета, нажмите Activate new secret: это убирает старый секрет из конфигурации edge, и с этого момента upstream должен принимать только новый.