Сущности

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

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

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

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

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

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

Сущности

• Пользователь — конечный пользователь: его идентификаторы, claims, credentials и роли по тенантам, хранящиеся один раз в auth.
• Клиент — приложение, запрашивающее токены: его идентичность, скоупы, разрешения, auth flow и настройки выхода.
• Ресурс — upstream API за edge: его идентичность, audience, тип internal/public и эндпоинты, из которых он состоит.
• Тенант — пространство имен, которому принадлежат клиенты, ресурсы, скоупы, разрешения и роли.
• Скоуп — именованный набор claims, которые клиент может запросить о пользователе.
• Разрешение — именованный набор эндпоинтов ресурса, на который ссылаются роли и клиенты.
• Роль — именованный набор разрешений, назначаемый пользователю по тенантам.

Пошаговые инструкции по регистрации — в разделе Как это сделать.

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

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

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

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

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