Payment Orchestrator

Тема

05.04 Roles And Permissions ​

Статус: черновик для обсуждения

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

Этот документ описывает role-based access model для Back Office.

Цель:

  • разделить platform и merchant permissions;
  • дать platform admins контроль над roles и permissions;
  • позволить merchant admins управлять users внутри своего merchant context;
  • сделать все Back Office actions permission-based;
  • избежать неявного доступа к hidden provider/internal data.

2. Основной принцип ​

Весь Back Office должен быть permission-based.

Любое значимое действие должно проверяться через permission.

UI может скрывать недоступные действия, но backend все равно обязан проверять permissions.

3. Role types ​

Roles строго разделяются на:

  • platform roles;
  • merchant roles.

Одна role не может быть одновременно platform role и merchant role.

User type также строго разделен:

  • platform user;
  • merchant user.

Один user не может одновременно быть platform user и merchant user.

Один user не может одновременно иметь platform role и merchant access.

User type после создания не меняется в MVP.

Такое разделение нужно, чтобы не смешивать:

  • platform-level access;
  • merchant-level access;
  • merchant group access;
  • internal platform operations;
  • merchant self-service operations.

4. Кто управляет roles ​

Roles создают и редактируют только platform users с соответствующей permission.

Platform user с permission может:

  • создать platform role;
  • создать merchant role;
  • изменить role name;
  • изменить role permissions;
  • включить/выключить role;
  • назначить role user-у в нужном context.
  • выдать merchant user-у доступ к merchant group.

Merchant users не могут:

  • создавать roles;
  • редактировать roles;
  • менять permissions внутри roles;
  • создавать platform roles;
  • назначать platform roles.

5. Merchant admin behavior ​

Platform назначает merchant admin-а.

После этого merchant admin, если его merchant role содержит permission управлять users, может:

  • приглашать merchant users;
  • выдавать merchant roles другим users;
  • менять merchant role user-а;
  • удалять доступ user-а к merchant;
  • управлять users только в рамках merchant context, где у него есть permission.

Merchant admin не может менять permissions этих roles.

Merchant admin не может:

  • добавлять users в merchant group;
  • выдавать roles в merchant group context;
  • менять merchant group access.

Merchant group access выдает только platform user с соответствующей permission.

Merchant admin может назначать только merchant roles, которые platform пометила как assignable by merchant admin.

Логика такая:

  • platform определяет, какие merchant roles существуют и какие permissions они содержат;
  • platform определяет, какие merchant roles может назначать merchant admin;
  • platform назначает merchant admin-а;
  • merchant admin управляет users внутри своего merchant context;
  • merchant admin может выдавать только разрешенные merchant roles, но не может изменить их содержание.

6. Permission naming ​

Permissions должны быть granular.

Permission должна описывать конкретную capability/action.

Формат может быть:

text
can_<action>_<object>

или другой consistent technical format, если development team предложит его.

Примеры:

text
can_view_transactions
can_export_transactions
can_view_transaction_details
can_resend_tx_callback
can_correct_transaction_status
can_view_provider_raw_data
can_manage_api_keys
can_rotate_api_key
can_revoke_api_key
can_manage_merchant_users
can_view_audit_logs
can_create_brand
can_edit_brand
can_view_payment_methods
can_edit_payment_method_routing
can_manage_sub_mid
can_manage_velocity_limits
can_manage_fx_settings

Главный принцип: permission должна быть понятной и точной.

Не все permissions обязаны быть CRUD-матрицей.

Например, Resend Callback не нужно описывать через generic table action. Для этого должна быть отдельная permission:

text
can_resend_tx_callback

7. Permission UI ​

В MVP не нужно обязательно делать permission matrix UI.

Так как многие permissions являются feature/action-based, а не простым CRUD, лучше использовать grouped permission list.

Пример группировки:

  • Transactions;
  • Transaction Actions;
  • Webhooks;
  • API Keys;
  • Users;
  • Roles;
  • Merchants;
  • Merchant Groups;
  • Brands;
  • Payment Method / MID;
  • MASTER MID;
  • SUB MID;
  • SUB MID Aggregators;
  • Velocity Limits;
  • FX / Fees;
  • Audit Logs;
  • Sensitive Data.

Внутри каждой группы UI показывает список permissions с human-readable label и description.

Пример:

text
Transactions
- View transactions
- View transaction details
- Export transactions

Transaction Actions
- Correct transaction status
- Resend transaction callback

Sensitive Data
- View provider raw data
- View hidden routing internals

7.1 Default roles ​

Система должна автоматически создавать default roles.

Platform Admin ​

Если в системе нет users, bootstrap flow создает first platform user.

Система автоматически создает platform role:

text
Admin

Role Admin получает все permissions системы.

First platform user получает role Admin.

Merchant Admin ​

Система должна автоматически создавать default merchant admin role.

Эта role:

  • является merchant role;
  • может быть назначена только merchant user-у;
  • назначается только в context конкретного merchant;
  • может быть marked as assignable by merchant admin, если platform так настроит;
  • может быть отредактирована platform admin-ом.

Exact permission set default merchant admin role должна определить product/development team before seed implementation.

8. Role assignment contexts ​

Role назначается user-у в context.

Поддерживаемые contexts:

  • global/platform context;
  • merchant context.

Merchant group access is supported as access scope, but it is not a role assignment context in MVP.

Platform role назначается в platform/global context.

Merchant role в MVP назначается только в:

  • merchant context.

Merchant role не назначается в merchant group context в MVP.

Merchant group access является access scope к merchants внутри group, но не является role assignment context.

Ограничения:

  • platform role может быть назначена только platform user-у;
  • merchant role может быть назначена только merchant user-у;
  • merchant context role может быть назначена platform user-ом или merchant user-ом с permission в этом merchant context;
  • merchant group access может быть выдан только platform user-ом с permission.

9. Multiple roles ​

Один user может иметь несколько roles в разных contexts.

Примеры:

  • platform user имеет platform role Support;
  • merchant user имеет merchant role Viewer в merchant A;
  • merchant user имеет access к merchant group B, но merchant role назначается только на конкретные merchants.

Нельзя смешивать platform role и merchant roles у одного user.

Access всегда рассчитывается с учетом:

  • user type;
  • assigned roles;
  • role context;
  • merchant / merchant group access;
  • permissions;
  • entity visibility rules.

Изменения role и permissions должны применяться сразу, включая active sessions.

Если user удаляется из merchant context, active sessions завершать не нужно. Система должна сразу пересчитать permissions/access.

Если merchant добавили в merchant group или убрали из merchant group, users с group access должны сразу получить или потерять доступ к этому merchant.

Если role переводится в INACTIVE или DELETED, эта role должна быть удалена у users, которым она была назначена.

10. Merchant group and merchant permissions merge ​

Если user имеет merchant group access и merchant-specific roles, effective access должен рассчитываться с учетом обоих источников.

Это значит:

  • group access дает access scope к merchants внутри group;
  • merchant-specific role дает permissions на конкретный merchant;
  • итоговый доступ является объединением доступного scope и permissions на конкретных merchants.

Пример:

text
User has access to Merchant Group A.
User also has Merchant Admin role for Merchant X inside Group A.

For Merchant X:
permissions = Admin permissions

For other merchants in Group A:
user can see only what group access allows without merchant role, according to exact access model

Exact technical merge algorithm for group access without group role should be defined by development team.

11. Sensitive permissions ​

Некоторые permissions должны считаться sensitive.

Примеры:

  • view provider raw data;
  • view hidden routing internals;
  • manage SUB MID Aggregators;
  • manage MASTER MID internals;
  • correct transaction status;
  • resend transaction callback;
  • view API key metadata;
  • rotate/revoke API key;
  • manage roles;
  • terminate user sessions;
  • view audit logs.

Sensitive permissions должны быть явно видны platform admin при настройке role.

12. Audit log ​

Все role/permission changes должны попадать в audit log.

Audit log должен фиксировать:

  • role created;
  • role updated;
  • role disabled/enabled;
  • permission added to role;
  • permission removed from role;
  • role assigned to user;
  • role removed from user;
  • user merchant access added;
  • user merchant access removed;
  • user merchant role changed;
  • user merchant group access added;
  • user merchant group access removed;
  • context of assignment;
  • actor;
  • timestamp.

Merchant user actions по назначению roles внутри merchant context также должны попадать в audit log.

13. Acceptance Criteria ​

Roles and Permissions считаются согласованными для MVP, если:

  • Roles разделены на platform roles и merchant roles.
  • Одна role не может быть одновременно platform и merchant role.
  • User type строго разделен на platform user и merchant user.
  • Один user не может одновременно иметь platform role и merchant access.
  • User type после создания не меняется в MVP.
  • Roles и permissions создают/редактируют только platform users с permission.
  • Merchant users не могут менять permissions roles.
  • Platform назначает merchant admin-а.
  • Merchant admin с permission может приглашать users и выдавать merchant roles только внутри своего merchant context.
  • Merchant group access доступен только platform user-ам с permission.
  • Merchant role не назначается в merchant group context в MVP.
  • Merchant admin может назначать только merchant roles, которые platform пометила как assignable by merchant admin.
  • Permissions granular.
  • Permissions могут быть feature/action-based, например can_resend_tx_callback.
  • Permission UI строится как grouped permission list, а не обязательная CRUD matrix.
  • Role назначается в context: platform/global or merchant.
  • Merchant group access не является role assignment context in MVP.
  • Один user может иметь несколько roles в разных contexts.
  • Merchant group access и merchant-specific roles учитываются together in effective access calculation.
  • First platform Admin role создается автоматически and receives all permissions.
  • Default merchant admin role создается автоматически.
  • Изменения role/permissions применяются сразу.
  • Удаление user-а из merchant context сразу пересчитывает access без terminate sessions.
  • Изменение состава merchant group сразу влияет на group-based access.
  • INACTIVE/DELETED role удаляется у users, которым она была назначена.
  • Sensitive permissions выделяются явно.
  • Все role/permission changes пишутся в audit log.
  • Все user access changes пишутся в audit log.

14. Open Questions ​

Product open questions отсутствуют.

Technical/design follow-up:

  1. Определить exact permission naming convention.
  2. Составить полный permission dictionary для MVP.
  3. Определить UI группировку permissions.
  4. Определить default platform role Admin.
  5. Определить exact merge algorithm для edge cases.