Политики эндпоинтов

У каждого эндпоинта ресурса может быть политика, которую edge вычисляет при каждом запросе: булево правило allow, правила inject, меняющие пересылаемый запрос, и требования step-up. Правила пишутся на CEL. На странице перечислены поля, данные, доступные правилу, порядок вычисления и поведение при сбоях. Сначала нужно зарегистрировать ресурс (Как зарегистрировать ресурс).

Поля политики

Разрешения в политику не входят. Эндпоинт должен быть разрешён ещё и через разрешение роли или клиента, и эта проверка идёт первой (Разрешение).

Что может читать правило

Любое выражение (allow, inject, stepUpCondition) видит одни и те же три переменные:

Язык — стандартный CEL со стандартными макросами: сравнения, логические операторы, in, арифметика, ?:, has(x.y), all, exists, exists_one, map, filter, строковые и списочные функции. Выражения компилируются один раз и кэшируются. Консоль проверяет синтаксис и тип результата при сохранении, поэтому синтаксическая ошибка или небулев allow не дадут сохранить ресурс.

Правило, которое читает то, чего нет в запросе, не вызывает ошибку CEL: это отсутствующие данные. Отсутствующие данные — это request.body.total в запросе без JSON-тела или user.plan у пользователя без такого claim. Необязательные значения защищайте через has():

!has(request.query.draft) || "manager" in token.roles

Отсутствующие данные в allow дают 403. Везде, где значение необязательное, используйте has().

Порядок вычисления

flowchart TD
    A["Request to /resources/{resourceId}/{path}"] --> B{"Token found?\nBearer, DPoP or EDGE_SESSION"}
    B -- no --> R401A["401"]
    B -- yes --> C{"Signature valid\nand not expired?"}
    C -- "expired, cookie" --> C2["Refresh with stored refresh token\nrotate cookie"]
    C -- "expired, header" --> R401B["401"]
    C -- "invalid" --> R401C["401"]
    C2 -- "refresh fails" --> R401D["401 + Location /login/{presetId}\ncookie cleared"]
    C2 --> D
    C -- yes --> D{"Revoked?\nin-memory list"}
    D -- yes --> R401E["401"]
    D -- no --> E{"Token binding OK?\nDPoP proof, cnf rules"}
    E -- no --> R401F["401 + WWW-Authenticate"]
    E -- yes --> F{"Resource and endpoint\nregistered?"}
    F -- no --> R404["404"]
    F -- yes --> G{"Role or client permission\ngrants this endpoint?"}
    G -- no --> R403A["403"]
    G -- yes --> H{"Audience covers\nthe resource?"}
    H -- no --> R403B["403"]
    H -- yes --> I["Fetch /userinfo\nonly if fetchUserInfo"]
    I --> J{"allow rule true?"}
    J -- "false or data missing" --> R403C["403"]
    J -- "rule broken" --> R500A["500"]
    J -- yes --> K{"Step-up needed?\nstepUpCondition, stepUpAcr, maxAge"}
    K -- yes --> R401G["401 + WWW-Authenticate\ninsufficient_user_authentication"]
    K -- "condition broken" --> R500B["500"]
    K -- no --> L["Evaluate inject rules\nheader, query, body"]
    L -- "data missing" --> R403D["403"]
    L -- "rule broken" --> R500C["500"]
    L --> M["Forward to the resource\nBasic credential or caller's Bearer token"]

1. Токен. Найден, подпись верна, срок не истёк. Просроченный токен из cookie обновляется, просроченный токен из заголовка — нет.
2. Отзыв. Поиск в памяти по ID токена, семейству refresh-токенов, сессии и субъекту.
3. Привязка. Proof DPoP и правила cnf (Токены с привязкой к отправителю).
4. Поиск. Сначала ресурс, затем эндпоинт по методу и пути. Литеральный сегмент выигрывает у сегмента {param}, поэтому /users/me приоритетнее /users/{userId}.
5. Разрешение. Эндпоинт разрешён какой-либо ролью вызывающего или, для сервисного токена (sub равен client_id), разрешениями клиента.
6. Audience. В aud есть resource://{resourceId} (или resource://edge) для внутреннего ресурса либо абсолютный URI ресурса для публичного.
7. Userinfo, только если включён fetchUserInfo.
8. allow.
9. Step-up. Намеренно после allow: вызывающий без права на эндпоинт получает обычный 403, а не предложение повторно войти, которое закончилось бы тем же отказом.
10. Inject, затем пересылка.

Правила работают с данными одного запроса. Между запросами ничего не сохраняется, а allow и stepUpCondition не видят результат друг друга.

Примеры

Allow по роли или claim

GET /invoices с необязательным фильтром draft. Черновики видят менеджеры, остальные с этим разрешением видят только закрытые счета.

Claim, который есть только в userinfo, требует включить fetchUserInfo:

Подстановка идентичности пользователя

Upstream читает идентичность из заголовков и не разбирает токен.

То, что клиент прислал в X-User-Id, сначала удаляется, поэтому заголовок подделать нельзя. Так же работают правило query (имя tenant, выражение token.tenant_id) и правило body (имя userId, выражение token.sub).

Владение через параметр пути

Пользователь читает только свои заказы.

Step-up для чувствительного эндпоинта

Переводы выше лимита требуют более сильной аутентификации, а для любого перевода вход должен быть не старше десяти минут.

stepUpAcr берёт значения из словаря ACR вашего тенанта (Challenges & Security в консоли). Запрос, не прошедший хотя бы одну проверку, получает:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="insufficient_user_authentication", acr_values="otp", max_age="600"

В ответе перечислены все невыполненные требования, поэтому одного повторного входа хватает на оба. Приложение отправляет браузер на /login/{presetId}?acr_values=otp&max_age=600 и повторяет запрос после входа (RFC 9470).

Чтобы требовать acr при каждом вызове, задайте stepUpCondition равным true. Если задан stepUpAcr, а условия нет, ничего не требуется. Если условие истинно, а stepUpAcr не задан, действует только maxAge.

Поведение при сбоях

Отказы возвращают только статус без пояснений. Код попадает в ключ error строки лога запроса и в метрики. Правило inject, вычисленное в null, ничего не добавляет, а значение клиента с этим именем всё равно удаляется.

Два ограничения, которые стоит учесть. Значения inject — строки: число или boolean преобразуется через toString. Для подстановки в тело нужно JSON-тело в виде объекта, а любое другое тело пересылается без изменений и без подстановки.

Задать политику в консоли

1. Откройте Resources и нажмите + Create Resource, либо откройте существующий ресурс для редактирования.
2. Нажмите Add endpoint. Введите метод и относительный путь, например /users/{userId}/orders.
3. Включите Fetch userinfo, если какое-то правило читает user.
4. Введите Allow (CEL). Пустое поле означает отсутствие проверки.
5. В разделе Inject нажмите Add rule и задайте Target, Name и Expression (CEL).
6. Заполните Step-up Condition (CEL), Step-up ACR и Max Auth Age (seconds).
7. Сохраните ресурс. edge подхватит изменение не позднее чем через configuration-cache-refresh-interval.

×

×

Сохранение ресурса никому не даёт доступ. Привяжите эндпоинт к разрешению, а разрешение к роли, как в Как зарегистрировать разрешение.

Что дальше

• Как защитить API с помощью edge: полный пример с curl.
• Обзор edge: жизненный цикл запроса вокруг конвейера.
• RFC 9470: вызов step-up.