Сущности — Versola Docs

Versola построена вокруг трех действующих лиц OAuth 2.0: пользователя (в терминах OAuth — resource owner), которому принадлежат данные, клиента, который хочет действовать от его имени, и ресурса, который эти данные хранит. Все остальное в консоли администратора — тенанты, scope, разрешения и роли — существует, чтобы описать, как эти трое могут взаимодействовать.

Общая картина

flowchart TB
    subgraph tenant["🏢 Tenant — configuration boundary"]
        client["📱 Client<br/><i>an application</i><br/>redirect URIs, scopes,<br/>permissions, auth flow"]
        resource["🔌 Resource<br/><i>an upstream API</i><br/>resource URI, audience,<br/>endpoints"]
        scope["🏷️ Scope<br/><i>claims released<br/>to the client</i>"]
        permission["🔑 Permission<br/><i>a set of<br/>resource endpoints</i>"]
        role["👥 Role<br/><i>a set of<br/>permissions</i>"]
    end

    owner["👤 Resource Owner<br/><i>the end user</i><br/>global identity + claims"]

    owner -->|holds roles in| tenant
    owner -->|grants access to| client
    client -->|requests| scope
    client -->|may request| resource
    resource -->|lists allowed clients in| client
    role -->|bundles| permission
    permission -->|unlocks endpoints of| resource
    client -->|carries own| permission

    style owner fill:#166534,stroke:#166534,color:#fff
    style client fill:#155e75,stroke:#e6edf3,color:#fff
    style resource fill:#155e75,stroke:#e6edf3,color:#fff
    style scope fill:#334155,stroke:#e6edf3,color:#fff
    style permission fill:#92400e,stroke:#92400e,color:#fff
    style role fill:#92400e,stroke:#92400e,color:#fff

Сущность	Что это	Где хранится
Пользователь	Конечный пользователь и его claims (OAuth resource owner)	`auth` (глобально, вне тенантов)
Клиент	Приложение, запрашивающее токены	`central`, внутри тенанта
Ресурс	Upstream API за `edge`	`central`, внутри тенанта
Тенант	Пространство имен, которому принадлежит все ниже	`central`
Scope	Claims, выдаваемые клиенту	`central`, внутри тенанта
Разрешение	Набор эндпоинтов ресурсов	`central`, внутри тенанта
Роль	Набор разрешений, назначаемый пользователям	`central`, внутри тенанта

Тенант — граница конфигурации

Тенант — это пространство имен, которому принадлежат клиенты, ресурсы, scope, разрешения и роли. В двух тенантах может быть свой клиент web-app, и они не будут конфликтовать. Тенант может быть привязан к развертыванию edge, и все клиенты и ресурсы внутри него наследуют эту привязку.

Пользователи намеренно не привязаны к тенанту: у человека одна идентичность на всю платформу. К тенанту привязаны его роли — пользователь может быть администратором в одном тенанте и обычным пользователем в другом.

Как через них проходит запрос

sequenceDiagram
    participant Owner as 👤 Resource Owner
    participant Client as 📱 Client
    participant Auth as auth
    participant Edge as edge
    participant Resource as 🔌 Resource

    Owner->>Client: Uses the application
    Client->>Auth: /authorize (scope, resource)
    Auth->>Auth: Authenticate the owner<br/>(auth flow of this client)
    Auth->>Auth: Check requested resources:<br/>client must be in resource.audience
    Auth-->>Client: Access token (aud = resource URIs)

    Client->>Edge: GET /resources/{resourceId}/orders<br/>+ access token
    Edge->>Edge: Verify signature, aud, expiry
    Edge->>Edge: Match method + path → endpoint
    Edge->>Edge: Permission check<br/>(owner roles or client permissions)
    Edge->>Edge: Evaluate allow (CEL),<br/>step-up, max age
    Edge->>Resource: Proxy request<br/>+ injected headers/query/body
    Resource-->>Edge: Response
    Edge-->>Client: Response

Два рубежа авторизации стоит выделить отдельно:

При выпуске токена (auth) — запрошенные значения resource проверяются по реестру: ресурс должен существовать в тенанте клиента, а клиент должен быть указан в его audience. Только тогда resource URI попадает в claim aud.
При выполнении запроса (edge) — aud токена должен покрывать ресурс, найденный эндпоинт должен быть доступен через роли вызывающего (или, для client_credentials, через собственные разрешения клиента), а выражение allow эндпоинта должно вернуть true.

Когда изменение вступает в силу

Изменение	Результат
Изменение эндпоинтов разрешения или разрешений роли либо клиента	`edge` применяет его после очередного обновления конфигурации (`configuration-cache-refresh-interval`). Новые правила действуют и для уже выпущенных токенов
Снятие роли с пользователя	Claim `roles` фиксируется при выпуске токена. Изменение попадет в следующий выпущенный или обновленный access-токен, а до тех пор старый токен несет роль
Отзыв токена, цепочки refresh-токенов или сессии	`edge` отклоняет токен, как только получит событие отзыва

Снятие роли не отзывает уже выпущенные токены: они сохраняют роль до истечения срока.

Общая картина

Тенант — граница конфигурации

Рекомендуемый порядок создания

Как через них проходит запрос

Когда изменение вступает в силу