Ресурс

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

• Resource ID — строчный, неизменяемый, используется в пути прокси: запросы к /resources/{resourceId}/* направляются на resource URI. ID edge зарезервирован.
• Resource URI — абсолютный URI с пустым путем, без query и fragment. Схема resource:// зарезервирована для внутренних ресурсов.
• Audience — список клиентов, которым разрешено запрашивать этот ресурс. Клиент, не указанный в audience, не сможет получить токен для него.
• Internal или public — у internal-ресурса есть сгенерированный секрет; edge аутентифицируется к нему через Authorization: Basic {resourceId}:{secret}, и токен вызывающего до него не доходит, значит он должен жить в внутренней зоне без доступа из веба — edge его единственный вызывающий. Выпускаемые для него токены несут в claim aud значение resource://{resourceId} (RFC 8707). У public-ресурса секрета нет; edge выполняет те же проверки audience, ролей/разрешений и выражения allow, но везет токен вызывающего как есть вместо своих собственных credentials, так что ресурс сам отвечает за его валидацию, а выпускаемые для него токены несут в aud собственный URI ресурса. Секреты internal-ресурсов ротируются так же, как секреты клиентов.
• Эндпоинты — отдельные пары метод + путь, из которых состоит ресурс.

Эндпоинты

Эндпоинт — единица авторизации. Все, что Versola проверяет на каждый запрос, настраивается здесь:

• Метод + относительный путь — что сопоставлять. Сегменты — литералы или параметры {name}, соответствующие ровно одному сегменту; сопоставленные значения доступны в CEL как request.path.params, а литеральный эндпоинт имеет приоритет над параметризованным.
• Fetch userinfo — загрузить claims пользователя из auth и передать их в CEL как user.
• Allow (CEL) — булево выражение, которое должно вернуть true, чтобы вызов был авторизован.
• Inject — правила, записывающие вычисленные значения в заголовок, query-параметр или поле JSON-тела запроса к upstream.
• Step-up condition + ACR — когда условие выполняется, требовать от вызывающего достигнутого уровня аутентификации (RFC 9470).
• Max auth age — отклонить вызов, если пользователь аутентифицировался слишком давно.

Разрешения ссылаются на эндпоинты по ID, поэтому эндпоинт становится доступен пользователю только тогда, когда какая-то его роль включает покрывающее этот эндпоинт разрешение.

Когда CEL-выражение не удалось вычислить

Ничего не уходит на upstream на основании выражения, которое не дало значения. Что получит вызывающий, зависит от причины:

• В запросе нет значения, которое читает выражение (например, user.plan на токене без клейма plan) — вызов отклоняется с 403, а условие step-up считается выполненным, так что ACR требуется, а не пропускается. Набор клеймов у разных пользователей законно различается, поэтому опциональные защищайте через has(): has(user.plan) && user.plan == 'premium' или has(user.plan) ? user.plan : '' для inject-правила, которому может быть нечего подставлять.
• Само выражение невычислимо (деление на ноль, переполнение, правило allow, вернувшее не-булево значение) — вызов падает с 500. Это проблема конфигурации, а не запроса. Выражения проверяются при сохранении, так что здесь остаётся лишь то, что вскрывается только на живых данных.

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