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

Ресурс (resource) — upstream API, который защищает edge. Здесь вы зарегистрируете его в консоли администратора, от идентификатора до политик эндпоинтов, и закончите тем, что сделаете эндпоинты доступными. Поля и правила описаны в разделе Resource.

Предварительные требования

• Тенант, привязанный к edge и выбранный в консоли.
• Абсолютный URI upstream API.
• Клиенты, которые будут запрашивать для него токены. Их можно добавить в аудиторию позже.
• Методы и пути эндпоинтов, которые нужно открыть.

1. Откройте Resources

Откройте Resources в нужном тенанте. В строке — ID ресурса с хостом под ним, тип (Internal или Public, а пока открыта ротация — Secret rotation), первые два эндпоинта и первые два клиента аудитории.

×

Откройте строку, чтобы увидеть страницу ресурса: URI, аудиторию, эндпоинты с их правилами и секрет internal-ресурса.

×

2. Начните новый ресурс

Нажмите + Create Resource. В форме три группы и нет эндпоинтов: их вы добавите на странице ресурса.

×

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

1. Resource ID: строчные латинские буквы, цифры и дефисы, первый символ — буква, например orders-api. edge пересылает /resources/{resourceId}/* на ресурс. edge зарезервирован. ID должен быть уникален во всей установке, позже его изменить нельзя.
2. Absolute resource URI: схема и хост без пути, query и fragment, например https://orders.acme.example. Завершающий / считается путем. Схема resource:// зарезервирована.
3. Type: выберите Internal или Public. Позже тип изменить нельзя.
   • Internal: Versola генерирует секрет. edge вызывает upstream по HTTP Basic: ID ресурса как имя, секрет как пароль — и не пересылает токен вызывающего. В aud токенов для него стоит resource://{resourceId}. Держите upstream доступным только с edge.
   • Public: секрета нет. edge пересылает access token вызывающего как Bearer, а upstream сам его проверяет. В aud токенов для него стоит URI ресурса.
4. Audience: отметьте клиентов, которым разрешено запрашивать токены для этого ресурса. Если список длинный, воспользуйтесь фильтром. Токен получат только отмеченные клиенты. Аудитория необязательна и позже меняется.

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

×

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

Нажмите Create resource. Откроется страница нового ресурса. Для internal-ресурса баннер один раз показывает секрет. Нажмите Copy secret, сохраните его и настройте upstream на HTTP Basic: ID ресурса как имя, этот секрет как пароль. Чтобы убрать баннер, нажмите I’ve saved it; если уйти со страницы раньше, консоль попросит подтвердить, потому что секрет повторно показать нельзя.

×

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

На карточке Endpoints нажмите Edit endpoints, затем Add для каждой пары «метод и путь». Правая часть страницы правит выбранный эндпоинт в четырех панелях.

1. Request: Method и Relative path. Путь сопоставляется после /resources/{resourceId}. Он начинается с /. Сегмент — литерал из букв, цифр и дефисов либо параметр {name}, например /orders/{id}/cancel. Имена параметров в пути должны быть уникальны, а два эндпоинта с одним методом не могут отличаться только именами параметров. Fetch userinfo включайте, только если правило читает user: это добавляет вызов auth на каждый запрос.
2. Who may call: Allow (CEL) — булево правило, которое должно вернуть true. Пусто — дополнительной проверки нет. Required permission только для чтения: эндпоинты привязываются к разрешениям на шаге 6.
3. Step-up: если Condition (CEL) истинно, у вызывающего должно быть одно из отмеченных значений Required ACR. Список берется из Step-up (ACR) на странице Security. Если он пуст, сначала зарегистрируйте значения ACR там. Max auth age (seconds) — отказывать тем, кто аутентифицировался раньше; пусто — без ограничения.
4. Inject: нажмите Add rule, выберите Target (header, query или body), Name и Expression (CEL), например token.sub в заголовок X-Account-Id. Внедренные значения заменяют то, что прислал клиент.

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

×

Нажмите Save endpoints. Страница вернется к ресурсу, где карточка Endpoints показывает правила каждого эндпоинта в таблице.

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

Сохранение ресурса никому не дает доступа. Эндпоинт отвечает 403, пока его не покроет разрешение и оно не будет у вызывающего.

1. Создайте разрешение и привяжите эндпоинты.
2. Добавьте его в роль и назначьте роль пользователям тенанта. Для service app с client_credentials добавьте разрешение клиенту.

Колонка Who may call таблицы эндпоинтов показывает, какие разрешения покрывают каждый эндпоинт.

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

1. Откройте ресурс и нажмите Rotate secret на карточке Secret. Баннер один раз покажет новый секрет.
2. Научите upstream принимать и старый, и новый секреты. Во время ротации edge продолжает использовать старый.
3. Нажмите Activate new secret и подтвердите. После следующей синхронизации edge перейдет на новый секрет, старый будет удален.

Одновременно может быть открыта только одна ротация. У public-ресурса секрета нет, ротировать нечего.

Изменение и удаление ресурса

Можно менять URI, аудиторию и эндпоинты, каждое со своей карточки. ID и тип фиксированы. Удаление эндпоинта, который покрыт разрешениями, требует подтверждения и называет их. Чтобы удалить ресурс, используйте последнюю карточку Delete resource; диалог перечисляет разрешения, которые покажут удаленные эндпоинты в блоке Detached endpoints.

Что дальше

• Политики эндпоинтов: переменные CEL, inject, step-up и коды ошибок.
• Как зарегистрировать разрешение: сопоставить эндпоинты с разрешениями.
• Как защитить API с помощью edge: полный пример с curl.