Перейти к основному содержимому

Tenancy And Identity — Субъекты платформы, изоляция и модель доступа

Версия: 1.0
Дата: 23.04.2026
Статус: Готов к обсуждению

Назначение документа​

Этот документ фиксирует единую модель субъектов платформы, tenancy boundaries, roles, capabilities, API clients и access control.

Его задача — ответить на фундаментальные вопросы, которые до сих пор были распылены между overview, api-contracts, clients, business-services, domain-model и review-документами:

  • что является субъектом платформы;
  • что является tenant boundary;
  • agency и partner — это одна сущность или разные;
  • чем отличается user, actor, agency member, partner client, api client;
  • где живут роли, capabilities, quotas и visibility rules;
  • как организована изоляция данных и прав;
  • как соотносятся human access и machine access.

Опорные документы​

Почему Этот Документ Нужен Отдельно​

В Главные выводы и проблемные зоны платформы уже зафиксировано, что tenancy, identity и access-модель пока распылены по разным документам.

Это критическая проблема, потому что без единой модели субъектов платформа не сможет последовательно определить:

  • client surfaces;
  • partner contracts;
  • pricing visibility;
  • quote ownership;
  • booking ownership;
  • governance visibility;
  • rate limits and quotas;
  • audit subjects;
  • data isolation.

Identity and access здесь не являются "security appendix". Это часть центрального домена платформы.

Но одного этого документа недостаточно, чтобы описать, как tenant practically enabled, какие supplier/commercial/usage envelopes ему выданы и на каких operational and financial основаниях он допускается к платформе.

Именно поэтому tenancy boundary и tenant configuration должны мыслиться как соседние, но не одинаковые контуры.

Главный Принцип Identity And Tenancy​

Платформа должна различать:

  • кто является субъектом;
  • в каком организационном контексте он действует;
  • в каком surface-е он действует;
  • какие capabilities ему доступны;
  • какие объекты он имеет право видеть и изменять;
  • какие коммерческие и contractual последствия имеет его действие.

Из этого следует главное правило:

authentication, organizational ownership, actor context и capability scope не являются одной и той же сущностью и не должны сливаться в один "role" или один "user type".

Основные Уровни Модели​

Identity and tenancy модель платформы должна состоять минимум из шести различаемых уровней.

1. Identity​

Это устойчивый субъект аутентификации:

  • человек;
  • сервисный клиент;
  • внешний API client;
  • webhook sender/receiver subject.

Identity отвечает на вопрос: кто предъявил себя системе.

2. Organization​

Это организационный субъект:

  • agency;
  • partner;
  • internal organization unit;
  • platform-owned service organization, если понадобится.

Organization отвечает на вопрос: в чьём контуре экономически и операционно живёт субъект.

3. Tenant​

Tenant — это boundary of isolation and policy application.

Tenant не обязан совпадать с любой организацией один в один, но на текущем этапе самый разумный подход такой:

  • internal platform tenancy;
  • agency tenancy;
  • partner tenancy;
  • при необходимости dedicated tenant for large embedded/white-label clients.

Tenant отвечает на вопрос: где проходит граница данных, policy и scope isolation.

4. Actor Context​

Это рабочий контекст, в котором identity действует в конкретный момент.

Например, один и тот же человек может быть:

  • internal operator;
  • agency manager;
  • partner support representative;
  • delegated actor in a customer workflow.

Actor context отвечает на вопрос: кем субъект является в данном действии.

5. Capability Scope​

Это набор разрешённых действий и ограничений:

  • что можно читать;
  • что можно менять;
  • в каком surface;
  • на каких объектах;
  • с какими коммерческими последствиями;
  • с какими лимитами.

6. Contract / Access Medium​

Это форма доступа:

  • user session;
  • access token;
  • API key;
  • service credential;
  • webhook credential.

Один и тот же actor context не обязан использовать только один access medium.

Главные Субъекты Платформы​

На текущем этапе нужно жёстко различать следующие классы субъектов.

1. Internal User​

Это пользователь внутреннего контура платформы.

Он может выполнять:

  • governance review;
  • booking exception handling;
  • supplier monitoring;
  • support actions;
  • partner administration;
  • finance/reconciliation actions.

Internal user не должен моделироваться как частный случай agency user.

2. Agency User​

Это пользователь агентского контура.

Он действует внутри Agency и использует Agency Working Surface.

Ему могут быть доступны:

  • search and compare;
  • quote creation;
  • booking operations;
  • tour draft/proposal work;
  • customer-related workflows;
  • agency-scoped reporting.

3. Partner User​

Это human subject партнёрского контура, если партнёр использует human-facing interfaces.

Он не обязан существовать всегда, но модель должна допускать:

  • partner admins;
  • partner operators;
  • partner support users;
  • partner analysts.

4. Api Client​

Это machine subject, действующий через partner or system contract.

Его нельзя смешивать с human user. Для него важны:

  • credential lifecycle;
  • contract scopes;
  • quotas;
  • environment binding;
  • audit attribution.

5. Service Identity​

Это внутренний системный субъект для service-to-service access.

Он нужен для:

  • internal calls;
  • background jobs;
  • event publishing/consuming;
  • operational automation.

6. Delegated / Shared Access Actor​

Платформа должна быть готова к тому, что часть действий выполняется:

  • от имени организации;
  • в delegated context;
  • через automation on behalf of human users.

Это нужно для auditability и capability discipline.

Agency И Partner — Не Одна И Та Же Сущность​

Это один из самых важных выводов документа.

Agency​

Agency — субъект, который использует платформу для собственной агентской работы:

  • поиска;
  • quote creation;
  • booking;
  • tour building;
  • client servicing.

Agency — это прежде всего working and commercial actor внутри платформы.

Partner​

Partner — субъект, который взаимодействует с платформой через внешний contract surface:

  • partner API;
  • white-label integration;
  • embedded channel;
  • downstream reseller or integrator relationship.

Partner — это прежде всего contractual and channel actor.

Почему Это Нельзя Смешивать​

Потому что тогда расплываются:

  • quota and billing subject;
  • access model;
  • UI surface model;
  • pricing visibility rules;
  • contract promises;
  • tenant isolation strategy.

Одна организация может в будущем совмещать признаки Agency и Partner, но модель должна позволять это как осознанную комбинацию, а не как скрытую путаницу.

Что Такое Tenant Boundary​

Tenant boundary — это не просто удобная группировка пользователей.

Это граница, по которой определяются:

  • data isolation;
  • visibility rules;
  • pricing context;
  • policy application;
  • quota application;
  • audit ownership;
  • integration environment bindings.

Базовые Tenant Classes Для Платформы​

  • platform_internal_tenant
  • agency_tenant
  • partner_tenant
  • dedicated_embedded_tenant, если потребуется

Практический Принцип​

По умолчанию объект, quote, booking, proposal или API client должны иметь понятную tenant-affiliation или explicit cross-tenant rule.

Без этого access model будет постоянно давать исключения и ad hoc правила.

User, Identity И Actor Context​

Эти понятия нельзя считать взаимозаменяемыми.

Identity​

Отвечает на вопрос: кто аутентифицировался.

User​

Это human identity, зарегистрированная в системе, со своим профилем и жизненным циклом.

Actor Context​

Отвечает на вопрос: в какой роли и в каком organizational scope действует user прямо сейчас.

Один User может иметь несколько actor contexts:

  • internal operator;
  • agency member;
  • agency admin;
  • partner admin;
  • support delegate.

Это даёт гораздо более устойчивую модель, чем попытка хранить всё в одном поле role.

Roles И Capabilities​

Платформе нужна двухуровневая модель:

  • roles as assignment bundles;
  • capabilities as executable permissions.

Roles​

Role — это удобный агрегат для назначения и управления доступом.

Примеры:

  • internal_operator
  • internal_governance_reviewer
  • agency_admin
  • agency_agent
  • partner_admin
  • partner_api_manager

Capabilities​

Capability — это атомарное или полуатомарное право.

Примеры:

  • search.read
  • offer.read
  • quote.create
  • quote.read_scoped
  • booking.create
  • booking.read_scoped
  • booking.manage_exception
  • proposal.publish
  • governance.review
  • partner_client.manage
  • tenant.settings.manage

Почему Нужны Оба Уровня​

Если оставить только roles, система станет слишком грубой.

Если оставить только capabilities, модель станет неудобной для управления.

Поэтому правильный путь:

  • roles агрегируют capabilities;
  • capabilities применяются в actor context;
  • финальный access decision учитывает ещё и scope/tenant/object ownership.

Scope Model​

Access control должен учитывать не только роль, но и область действия.

Виды Scope​

  • tenant scope;
  • organization scope;
  • actor-own scope;
  • object ownership scope;
  • surface scope;
  • contract scope;
  • environment scope.

Примеры​

  • agency user может читать только свои agency quotes and bookings;
  • partner API client может работать только в пределах своего partner contract scope;
  • internal reviewer может видеть review cases across multiple tenants, но не обязан видеть коммерчески чувствительные partner fields;
  • white-label embedded client может видеть только те ресурсы, которые explicitly delegated этому каналу.

Human Access И Machine Access​

Платформа должна жёстко различать human and machine access.

Human Access​

Формы:

  • web sessions;
  • user access tokens;
  • delegated operator sessions.

Особенности:

  • richer interactive workflows;
  • actor switching or contextual selection;
  • UI-driven capabilities;
  • support for explanation and confirmation flows.

Machine Access​

Формы:

  • partner API keys;
  • service credentials;
  • webhook secrets;
  • signed client credentials.

Особенности:

  • stricter scopes;
  • rate and quota discipline;
  • explicit environment binding;
  • no implicit UI-derived rights;
  • stronger idempotency and audit requirements.

API key и user session не являются взаимозаменяемыми access objects.

API Clients И Credentials​

ApiClient должен быть выделен как отдельная сущность.

ApiClient Должен Описывать​

  • owning organization;
  • tenant affiliation;
  • environment;
  • contract type;
  • allowed surfaces;
  • allowed capabilities;
  • quotas and rate limits;
  • credential rotation policy;
  • status and lifecycle.

ApiCredential Должен Описывать​

  • credential type;
  • hashed secret or key reference;
  • issuance time;
  • expiry / revocation;
  • environment binding;
  • last used metadata;
  • incident / suspension state.

Практический Вывод​

Нельзя моделировать partner API доступ как "ещё один user role". Это отдельный класс субъекта.

Visibility Model​

Доступ должен определять не только действие, но и видимость данных.

Нужно Различать​

  • object visibility;
  • field visibility;
  • action visibility;
  • pricing visibility;
  • governance visibility;
  • support-only visibility.

Примеры​

  • один и тот же offer может быть видим с разным price view;
  • booking может быть виден agency user без внутренних support fields;
  • partner client может видеть только contract-facing identifiers;
  • internal operator может видеть lineage, exceptions and support annotations.

Ownership Model​

У большинства значимых объектов должен быть понятный ownership context.

Минимально Нужно Фиксировать​

  • who created;
  • on behalf of which actor context;
  • under which tenant;
  • under which organization;
  • under which commercial profile;
  • under which contract or client, если действие machine-driven.

Особенно Это Важно Для​

  • Quote
  • Booking
  • TourDraft
  • TourProposal
  • ApiClient
  • ReviewCase

Иначе audit trail и access rules будут постоянно расходиться.

Isolation Model​

На уровне документации платформе нужно зафиксировать минимум три класса изоляции.

1. Strong Tenant Isolation​

Для данных, которые не должны пересекать tenant boundary без explicit delegation:

  • quotes;
  • bookings;
  • proposals;
  • tenant settings;
  • partner credentials.

2. Controlled Cross-Tenant Visibility​

Для внутренних operational and governance cases, когда:

  • платформа должна решать инциденты;
  • support должен видеть issue across tenants;
  • reconciliation требует cross-tenant diagnostics.

Это всегда должно идти через explicit capability and audit policy.

3. Shared Platform Knowledge​

Для truly shared platform data:

  • canonical property knowledge;
  • normalized classifications;
  • часть reviewed content;
  • часть supplier-independent reference models.

Это не отменяет того, что некоторые derived views of the same objects могут быть tenant-sensitive.

Access Decisions Как Комбинация Факторов​

Итоговое решение о доступе не должно приниматься только по одному признаку.

Оно должно учитывать как минимум:

  1. identity class;
  2. actor context;
  3. tenant boundary;
  4. assigned roles;
  5. effective capabilities;
  6. object ownership;
  7. requested surface;
  8. environment;
  9. optional commercial constraints.

Это важнее простой RBAC-модели.

Identity And Access В Связи С Другими Документами​

Domain Model​

Domain Model — Центральная доменная модель платформы уже ввёл Tenant, Workspace, RoleAssignment, CapabilityGrant, ApiClient, ApiCredential. Этот документ раскрывает их смысл.

API Contracts​

API Contracts — Surface Contracts и правила внешнего взаимодействия требует actor-aware, scope-aware и environment-aware contracts. Этот документ задаёт для этого доменную основу.

Clients​

Clients Layer — Клиентские поверхности и рабочие модели зависит от различия internal, agency, partner and client-facing surfaces. Этот документ объясняет, почему эти различия существуют не только в UI, но и в access model.

Business Services​

Business Services — Сервисная декомпозиция платформы уже фиксирует Identity And Access Service как отдельный сервисный контур. Здесь определяется, что именно этот контур должен обслуживать.

Storage​

Storage Layer — Модель хранения и жизненный цикл данных должен хранить identity and organization truth как долгоживущий persistent layer, а runtime access markers — как отдельный технический слой.

Что Должно Быть Перепроверено После Этого Документа​

Следующим шагом после фиксации identity and tenancy модели должен идти документ про:

  • offer / pricing / booking semantics

Потому что именно там access model начнёт реально влиять на:

  • price visibility;
  • quote ownership;
  • booking ownership;
  • partner-specific and agency-specific commercial behavior.

После этого нужно будет вернуться и синхронизировать:

  • database-schema.md;
  • api-contracts.md;
  • clients.md;
  • будущий документ про commercial model.

Текущий Практический Вывод​

Для vitiana-api-platform больше нельзя мыслить субъектов как расплывчатый набор слов user, agent, agency, partner, API key.

Правильная модель должна быть такой:

  • Identity отвечает за аутентификацию;
  • Organization отвечает за принадлежность;
  • Tenant отвечает за изоляцию;
  • ActorContext отвечает за текущую рабочую роль;
  • Role агрегирует доступ;
  • Capability определяет конкретные действия;
  • ApiClient и ApiCredential описывают machine access;
  • итоговый access decision всегда зависит от subject, scope, ownership and surface.

Именно эта модель должна дальше удерживать клиентские поверхности, partner API, booking ownership, governance visibility и platform isolation как единую систему.

Уточнение под Фазы 4–6 (28.04.2026) — Workspace, isolation tier, IsolationBoundaryCheck​

После Фаз 4–6 каноничной архитектуры (25–27.04.2026) ряд понятий tenancy и identity углублён в специализированных документах. Этот документ остаётся как базовая модель субъектов и tenant boundary, но детальные правила изоляции, уровни tier-зависимой изоляции, и автоматизированная проверка пересечения границ — в специализированных источниках.

Workspace — рабочая единица внутри Tenant​

В этом документе Workspace упомянут косвенно (строка о Domain Model). В каноничной архитектуре Workspace — first-class сущность Group 7 (см. overview/canonical-domain-spine.md и reference/clients.md).

Каноничные роли Workspace:

  • рабочая единица внутри Tenant для agency surface (см. reference/clients.md, Surface 2 Agency Working);
  • quotes живут в workspace context, не только в tenant;
  • drafts и proposals имеют owner / workspace semantics;
  • booking follow-up зависит от workspace policy (наследует Tenant policy + workspace overrides);
  • один и тот же User (через разный ActorContext) может видеть разный набор действий в разных workspaces.

Workspace не заменяет Tenant — это под-боundary внутри Tenant с собственными правами и видимостью. Tenant boundary остаётся самой строгой границей данных и policy; workspace boundary — рабочая декомпозиция внутри неё.

Уровни изоляции Tenant — каноничная истина в multi-tenant-isolation-strength.md​

В этом документе Tenant boundary определён как граница data isolation, но уровень изоляции (как именно реализуется граница) не зафиксирован. Каноничная истина — в reference/multi-tenant-isolation-strength.md (Фаза 5):

УровеньЧто значитКогда применяется
logicalshared infrastructure, tenant_id во всех таблицах + RLS policiesFree, Starter, Professional tier (по умолчанию)
dedicated_computeshared databases, но dedicated namespace в кластереProfessional tier (опционально), Enterprise tier
dedicated_infrastructureполностью выделенная infrastructure (отдельный кластер/регион)Enterprise tier (mandatory для regulated клиентов)

Связь с этим документом: Tenant boundary в этом документе — это логическая граница, всегда. Уровень logical / dedicated_compute / dedicated_infrastructure — это физическая реализация этой логической границы, выбираемая per-tenant по контракту (см. api-as-product.md, tier model).

IsolationBoundaryCheck — автоматизированная проверка​

Каноничная архитектура требует continuous automated check пересечения tenant boundary в production. Эта проверка зафиксирована в reference/multi-tenant-isolation-strength.md:

  • IsolationBoundaryCheck runs continuously;
  • attempts cross-tenant queries с different actors;
  • alert при successful unauthorized access;
  • target: 0 successful breaches за rolling 90 дней.

Это first-class security control платформы, не optional admin feature. Связан с reference/security-architecture.md.

Capability Set — каноничный resolver​

В этом документе Capability Scope зафиксирован как уровень модели. Каноничный механизм resolution capability set per (actor, tenant, workspace) — в reference/clients.md:

  • UI и API получают capability_set через GET /capability/me;
  • UI потребляет для скрытия/показа кнопок и меню;
  • API использует то же capability set для authorization checks;
  • это исключает рассогласование UI ↔ API.

Каноничные capabilities (выборка): search.execute, offer.view, quote.create, quote.revise, quote.expire, booking.create, booking.cancel, booking.modify, tour.compose, tour.publish, payment.refund.initiate, payment.chargeback.respond, partner.onboard, partner.certify, governance.review, governance.lock, governance.publish_hold, analytics.view.tenant, experiment.assign, notification.send.outbound.

Связь с API as Product — tier model​

Каждый Tenant имеет привязку к API tier (Free / Starter / Professional / Enterprise), определяющему:

Полная матрица — в reference/api-as-product.md.

Связь с security architecture​

Identity, MFA, session management, audit logging для всех subject types — в reference/security-architecture.md:

  • каноничные 3 уровня authentication (Level 1 single factor / Level 2 MFA / Level 3 step-up);
  • token model (access JWT TTL ≤ 1 час, refresh tokens с rotation, service account keys 90 дней rotation);
  • RBAC + ABAC hybrid authorization;
  • comprehensive audit logging для всех authn/authz events.

Identity-уровень в этом документе — концептуальный; реализация — в security-architecture.md.

Связь с compliance​

GDPR data subject rights для users/identities — в reference/compliance-and-legal.md:

  • right of access, rectification, erasure, portability;
  • DSR API: GET /privacy/data-export, POST /privacy/data-delete;
  • consent log (для marketing channels);
  • KZ data localization для KZ-resident subjects.

Каноничный итог уточнения​

Этот документ остаётся базовой моделью субъектов и tenant boundary (6 уровней: Identity, Organization, Tenant, Actor Context, Capability Scope, Contract Medium). Расширения и реализация:

  • Workspace — first-class под-boundary внутри Tenant (см. canonical-domain-spine.md, clients.md);
  • Уровень изоляции Tenant — logical / dedicated_compute / dedicated_infrastructure (см. multi-tenant-isolation-strength.md);
  • IsolationBoundaryCheck — continuous automated check (см. multi-tenant-isolation-strength.md);
  • Capability Set resolver — GET /capability/me (см. clients.md);
  • API tier model — Free/Starter/Professional/Enterprise определяет isolation tier и SLA (см. api-as-product.md);
  • Security implementation — MFA, tokens, RBAC+ABAC, audit (см. security-architecture.md);
  • Compliance implementation — GDPR DSR, consent, data localization (см. compliance-and-legal.md).

При конфликте с этим документом — истина в каноничном специализированном (правило single source of truth per domain).

Уточнение выполнено через no-destruction.

Связанная Документация​