Ресурс (resource) — это upstream API за edge. Регистрация говорит edge, куда пересылать трафик, каким клиентам можно запрашивать токены для ресурса и какие правила действуют на каждом эндпоинте. Общая картина описана в разделе Сущности.
Строка открывает страницу ресурса. Меню строки: Open, Copy ID и Delete resource. Поиск работает по ID, хосту, /path и METHOD /path; при поиске эндпоинта показываются ресурсы, у которых он есть.
Страница
Страница открывается только для чтения. Заголовок — ID ресурса, рядом кнопка копирования и чипы типа (Internal или Public) и, пока открыта ротация, Secret rotation. У каждой карточки свой Edit: он открывает только эту группу отдельной страницей с кнопкой Cancel и кнопкой Save, названной по группе.
| Карточка | Что показывает | Редактор |
|---|---|---|
| General | Resource URI и Reached at — маршрут /resources/{resourceId}/*, по которому edge пересылает запросы на URI | Edit general |
| Audience | Клиенты, которым разрешено запрашивать токены для ресурса, и под ними по строке на каждого клиента, которому ресурс задал лимит. Метка клиента открывает этого клиента | Edit audience |
| Endpoints | Таблица с правилами каждого эндпоинта | Edit endpoints |
| Secret | Только у internal-ресурсов: задан ли секрет и ждет ли активации новый | Rotate secret, затем Activate new secret |
| Fixed | Resource ID и Type, оба заданы при создании | Нет |
| Delete resource | Последняя на странице | Нет |
В консоли только для чтения те же карточки показаны без кнопок.
Поля
| Поле | Что это | Правила |
|---|---|---|
| Resource ID | Имя в пути прокси: edge пересылает /resources/{resourceId}/* на URI ресурса | Строчные латинские буквы, цифры и дефисы, первый символ — буква (^[a-z][a-z0-9-]*$). edge зарезервирован. Уникален во всей установке, а не только в тенанте. После создания не меняется |
| Absolute resource URI | Куда edge отправляет запрос | Абсолютный URI со схемой и хостом, без пути (даже без завершающего /), без query и fragment. Схема resource:// зарезервирована. Позже URI можно изменить |
| Audience | Клиенты, которым разрешено запрашивать этот ресурс | Клиенты того же тенанта, выбираются из списка с фильтром и Select all. Клиент, которого нет в списке, не получит токен для ресурса. Клиент, которого уже нет в тенанте, остается в списке, пока вы не снимете отметку |
| Type | Internal или Public | Выбирается при создании, потом не меняется |
| Endpoints | Пары «метод и путь», которые принимает edge, у каждой своя политика | См. ниже |
Ни консоль, ни Central API не задают максимальную длину этих значений.
Public и internal
| Public | Internal | |
|---|---|---|
| Секрет | Нет | Генерирует Versola |
Что edge отправляет upstream в Authorization | Access token вызывающего как Bearer, без изменений. Ресурс сам его проверяет | Basic: ID ресурса как имя и секрет ресурса как пароль. Токен вызывающего не пересылается |
aud выданного токена | URI ресурса | resource://{resourceId} |
| Кто проверяет вызывающего | Сам ресурс, по токену | edge. Upstream проверяет только Basic-учетные данные, поэтому держите его доступным только с edge |
У обоих типов в edge одни и те же проверки: аудитория, разрешения и политика эндпоинта. Жизненный цикл запроса описан в Обзоре edge.
Лимиты для клиентов аудитории
Сколько может брать каждый клиент аудитории, говорит ресурс, а не клиент. В Edit audience под списком клиентов есть свернутый блок Rate limits: раскройте его, и появится по одной секции на каждого клиента аудитории с надписью No limit или кратким описанием; раскройте клиента, чтобы задать его лимит (Set a limit, затем Mode, Count by (The client as a whole или Each user), окна и Burst). Лимит действует на вызовы этого клиента к этому ресурсу, на любом endpoint, вместе со своими политиками лимитов edge, и действует меньший лимит. Клиент, вышедший из аудитории, теряет свой лимит. Владелец клиента ничего не задает о том, сколько тот может брать у API.
Эндпоинты и их политика
Эндпоинт — единица авторизации. У каждого есть метод (GET, POST, PUT, PATCH или DELETE) и относительный путь. Путь начинается с /. Каждый сегмент — либо литерал из букв, цифр и дефисов, либо параметр {name}, который соответствует ровно одному сегменту. Имена параметров в пути уникальны, а два эндпоинта с одним методом не могут отличаться только именами параметров. Литеральный эндпоинт приоритетнее параметризованного.
Карточка Endpoints — таблица, колонки которой отвечают на главные вопросы без открытия редактора:
| Колонка | Что показывает |
|---|---|
| Endpoint | Метод, путь и тег userinfo, если включен Fetch userinfo |
| Who may call | Разрешения, покрывающие эндпоинт, через or (достаточно любого), и правило Allow либо No extra check |
| Step-up | Значения ACR, условие, при котором они нужны, и максимальный возраст входа (at most 5m; точное число секунд — в подсказке) |
| Added to the request | Правила inject в виде HEADER X-User-Id = token.sub либо Nothing |
Edit endpoints открывает страницу: слева список эндпоинтов, справа выбранный. Список отмечает несохраненное (New, Edited) и то, какие правила несет эндпоинт (Allow, Step-up, Inject); Add добавляет эндпоинт, а фильтр ищет по тексту, /path или METHOD /path. Справа пять панелей в том же порядке, в каком читается таблица, а свернутая Rate limit стоит последней:
| Панель | Поля |
|---|---|
| Request | Method, Relative path, Fetch userinfo: загрузить claims пользователя из auth и отдать их CEL как user. Один дополнительный вызов на запрос |
| Who may call | Required permission только для чтения (перечисляет разрешения, покрывающие эндпоинт) и Allow (CEL) — булево выражение, которое должно вернуть true. Пусто — дополнительной проверки нет |
| Step-up | Condition (CEL): если вернет true, у вызывающего должно быть одно из значений Required ACR; пусто — step-up не требуется. Required ACR: значения, зарегистрированные в Step-up (ACR) на странице Security. Max auth age (seconds): отказать, если пользователь аутентифицировался раньше; пусто — без ограничения, действует независимо от условия |
| Inject | Add rule: каждое правило записывает вычисленное значение в заголовок, query-параметр или поле верхнего уровня JSON-тела запроса к upstream. У правила есть Target, Name и Expression (CEL) |
| Rate limit | Свернута, потому что меняется редко: в заголовке видно, что задано (No limit или Enforce · 30 / 60 s · each user · burst 5). Set a limit добавляет лимит на частоту вызовов endpoint: Mode, Count by (The endpoint as a whole, Each client или Each user), окна и Burst. Edge применяет его вместе со своими политиками лимитов, и действует меньший лимит. В таблице endpoint с лимитом помечен limit: и его краткой записью |
Ничего не отправляется до Save endpoints. Полоса под списком называет изменения (Not saved yet: GET /orders (new), POST /orders/{orderId}/refund (edited)). Сохранение отправляет удаленные эндпоинты, новые и измененные одним запросом; измененный эндпоинт остается тем же, поэтому покрывающие его разрешения остаются привязаны. Удаление эндпоинта, который покрыт разрешениями, сначала спрашивает подтверждение и называет их.
Выражения, доступные им переменные, порядок вычисления и код ответа для каждой ошибки описаны в Политиках эндпоинтов. Выражения проверяются по мере ввода и при сохранении; синтаксическая ошибка блокирует сохранение, как и путь, нарушающий правила выше.
Пока эндпоинт не покрыт разрешением, которое есть у вызывающего, ответ всем — 403.
Секрет internal-ресурса
Versola генерирует секрет при создании internal-ресурса и показывает его один раз в баннере на странице нового ресурса. Он хранится в зашифрованном виде, повторно показать его нельзя. Если секрет потерян, замените его ротацией. Если уйти со страницы, не нажав I’ve saved it, консоль сначала спросит подтверждение.
Для ротации нажмите Rotate secret на карточке Secret. Новый секрет показывается один раз. Прежний остается в силе, в заголовке появляется чип Secret rotation, а баннер сообщает A new secret was issued. Во время ротации edge продолжает аутентифицироваться прежним секретом. Научите upstream принимать оба секрета, затем нажмите Activate new secret (в баннере или на карточке) и подтвердите. После следующей синхронизации edge перейдет на новый секрет, прежний будет удален. Одновременно может идти только одна ротация.
Создание и удаление
+ Create Resource открывает одну форму из трех групп: Basics (ID и URI), Type (две карточки, Internal и Public) и Audience. Эндпоинты добавляются потом, на странице нового ресурса, где видно, какие разрешения их покрывают. Ресурс без эндпоинтов допустим. После создания открывается страница ресурса, а у internal-ресурса — баннер с секретом.
Можно менять URI, аудиторию и эндпоинты. Удаление ресурса требует подтверждения; диалог называет маршрут, который перестанет работать, и разрешения, связанные с его эндпоинтами: они сохраняют их как detached endpoints.
Что дальше
- Как зарегистрировать ресурс: форма по шагам.
- Политики эндпоинтов: переменные CEL, inject, step-up и коды ошибок.
- Разрешение: сделать эндпоинты доступными.