پرش به محتویات

استاندارد تدوین نقش‌ها و دسترسی‌ها در تریپیلون

۱. هدف

این راهنما روش استاندارد طراحی دسترسی در ماژول‌های تریپیلون را تعریف می‌کند تا مشخص باشد چه Actorی، با کدام Role، در چه Scope و تحت چه شرطی می‌تواند یک Action را روی یک Resource انجام دهد.

۲. جایگاه در طراحی ماژول

دسترسی‌ها پس از نهایی‌شدن سناریو، User Flow و Workflow طراحی می‌شوند؛ زیرا Permission باید از Action واقعی و وضعیت معتبر فرایند استخراج شود.

ترتیب:

  1. هدف، محدوده و سناریوها
  2. User Flow
  3. Workflow و وضعیت‌ها
  4. نقش‌ها و دسترسی‌ها
  5. اعلان‌ها
  6. خطاها و موارد خاص
  7. IA و Wireframe

۳. اصول پایه

  • Deny by default: نبود قاعده صریح به معنی رد دسترسی است.
  • Least privilege: هر Role فقط حداقل Permission لازم را دریافت می‌کند.
  • Permission through Role: در نسخه اولیه Permission مستقیم به شخص داده نمی‌شود.
  • Scope required: Permission بدون Scope معتبر قابل اجرا نیست.
  • Authorization on every action: مشاهده UI یا دریافت لینک، مجوز انجام Action نیست.
  • Separation of duties: Actionهای حساس می‌توانند به Actor، تأیید یا Policy جدا نیاز داشته باشند.
  • Auditability: اعطا، تغییر و استفاده از دسترسی حساس باید قابل پیگیری باشد.
  • Fail secure: خطا در ارزیابی دسترسی باید به رد امن منجر شود.

۴. مفاهیم اصلی

مفهوم تعریف
Account هویت دیجیتال سراسری کاربر
Membership حضور عملیاتی شخص در ساختمان
Role مسئولیت قابل انتساب در یک Scope
Role Assignment اتصال Role فعال به Membership و Scope
Role Template بسته Permissionهای یک Role در یک ساختمان
Permission اجازه انجام Action مشخص روی Resource
Scope محدوده اثر Permission
Policy شرط تکمیلی مانند سقف مالی یا نیاز به تأیید
Support Access Grant دسترسی موقت و Ticket-based پشتیبانی

Authentication با Authorization یکسان نیست. ورود موفق فقط هویت را تأیید می‌کند و به‌تنهایی Permission ایجاد نمی‌کند.

۵. فرمول دسترسی مؤثر

دسترسی فقط زمانی مجاز است که همه شروط زیر برقرار باشند:

Account Link معتبر
AND Membership فعال
AND Role Assignment فعال
AND Role Template شامل Permission
AND Scope با Resource منطبق
AND Guardهای Workflow برقرار
AND Policy تکمیلی اجازه دهد
AND هیچ Deny یا Suspension مؤثری وجود نداشته باشد

برای اقدام شخص روی دعوت خودش، رابطه او با Invitation و OTP معتبر جای Role مدیریتی را می‌گیرد.

۶. مدل نام‌گذاری

Role Code

UPPER_SNAKE_CASE

نمونه:

  • BUILDING_ADMIN
  • BUILDING_MANAGER
  • BOARD_CHAIR
  • ACCOUNTANT

Permission Code

resource.action

نمونه:

  • unit.view
  • unit.manage
  • invitation.send
  • role_template.manage

Permission باید یک Action قابل بررسی باشد. نام‌هایی مانند full_access یا manage_everything مجاز نیستند.

Scope

  • BUILDING
  • UNIT
  • FACILITY
  • SHIFT
  • ASSIGNMENT
  • TICKET
  • PLATFORM

۷. ساختار استاندارد سند هر ماژول

  1. هدف و مرزبندی
  2. تصمیم‌های نقش
  3. Actorها و Roleها
  4. Permission Catalog
  5. Scope و Guardها
  6. Default Role Matrix
  7. Permissionهای حساس
  8. قواعد Role Template
  9. دسترسی پشتیبانی موقت
  10. Self-service Capabilityها
  11. Transitionهای دسترسی
  12. Audit
  13. سناریوهای سوءاستفاده
  14. تصمیم‌های باز
  15. معیارهای پذیرش

۸. Permission Catalog

برای هر Permission این اطلاعات ثبت شود:

فیلد توضیح
کد شناسه پایدار
عنوان نام فارسی
Resource منبع هدف
Action عمل مجاز
Scope محدوده‌های معتبر
حساسیت عادی، مهم، حساس یا بحرانی
Roleهای پیش‌فرض Roleهای دارای Permission
Guard شرط Workflow یا Policy
Audit سطح ثبت
خارج از محدوده Actionهای مشابه ولی غیرمجاز

۹. Role Template

  • Permissionها به Role Template متصل می‌شوند، نه مستقیم به شخص.
  • هر ساختمان نسخه مستقل Role Templateهای فعال خود را دارد.
  • بسته پیش‌فرض مسیر اصلی است.
  • فهرست کامل Permissionها در مسیر پیشرفته نمایش داده می‌شود.
  • تغییر Template بر همه Role Assignmentهای فعال و آینده همان Role اثر دارد.
  • Per-person Override در نسخه اولیه استفاده نمی‌شود.
  • بازگشت به بسته پیش‌فرض باید ممکن و Audit شود.

۱۰. Permission حساس

این حوزه‌ها به‌صورت پیش‌فرض حساس‌اند:

  • مدیریت Role و Permission
  • مشاهده یا تغییر اطلاعات خصوصی
  • انتقال مالکیت
  • تنظیم مقصد تسویه
  • تأیید یا انتشار مالی
  • مشاهده Audit حساس
  • دسترسی پشتیبانی
  • تغییر Building Admin

فعال‌سازی یا استفاده از Permission حساس می‌تواند نیازمند تأیید صریح، دلیل، مدرک یا Policy تکمیلی باشد.

۱۱. Role Assignment

  • Role Assignment فقط برای Membership معتبر ایجاد می‌شود.
  • Role حساس پیش از پذیرش PENDING_ACCEPTANCE است و Permission ندارد.
  • یک شخص می‌تواند چند Role و Scope داشته باشد.
  • پایان یک Role یا Scope نباید Roleهای نامرتبط را غیرفعال کند.
  • Role بدون متصدی فقط Role Template فعال دارد و Role Assignment فعال ندارد.

۱۲. دسترسی پشتیبانی موقت

پشتیبانی نباید برای انجام کار مشتری، Role دائمی داخل ساختمان دریافت کند.

Support Access Grant باید:

  • به Ticket یا درخواست ثبت‌شده متصل باشد؛
  • Scope ساختمان و Permissionهای مجاز را محدود کند؛
  • زمان شروع و پایان داشته باشد؛
  • Actor واقعی پشتیبانی را حفظ کند؛
  • تمام Actionها را با عبارت «به درخواست مشتری» Audit کند؛
  • پس از پایان یا Revoke غیرقابل استفاده شود.

مسیر break-glass فقط برای Incident فوری، با دلیل، Audit تقویت‌شده و بازبینی پس از اقدام مجاز است.

۱۳. Self-service Capability

برخی Actionها بر اساس رابطه شخص با Resource مجاز می‌شوند و Permission مدیریتی نیستند:

  • مشاهده و تصمیم درباره Role پیشنهادی خود
  • مشاهده وضعیت دعوت خود
  • گزارش تعلق اشتباه ساختمان یا واحد
  • پرداخت بدهی واحد مرتبط، طبق قواعد ماژول مالی

این Actionها همچنان به هویت تأییدشده و Guardهای Resource نیاز دارند.

۱۴. ماتریس نقش‌ها

مقادیر پیشنهادی:

علامت معنا
D دسترسی پیش‌فرض
C قابل اعطا با تنظیم ساختمان
V فقط مشاهده
P وابسته به Policy
T موقت و Ticket-based
— بدون دسترسی

ماتریس خلاصه جای Permission Catalog را نمی‌گیرد.

۱۵. تغییر دسترسی

برای تغییر Role Template مشخص شود:

  • چه کسی مجاز است؟
  • چند شخص فعال متأثر می‌شوند؟
  • Permission حساس اضافه یا حذف می‌شود؟
  • تأیید صریح لازم است؟
  • اثر فوری است یا زمان‌دار؟
  • Rollback چگونه انجام می‌شود؟
  • چه اطلاعاتی Audit می‌شوند؟

۱۶. ارزیابی درخواست دسترسی

flowchart TD accTitle: ارزیابی دسترسی مؤثر accDescr: سامانه هویت، عضویت، نقش، Permission، Scope، Guard و Policy را برای هر Action بررسی می‌کند START(["درخواست انجام Action"]):::start IDENTITY{"هویت و Account Link معتبر است؟"}:::decision MEMBERSHIP{"Membership فعال است؟"}:::decision ROLE{"Role Assignment فعال است؟"}:::decision PERMISSION{"Role Template شامل Permission است؟"}:::decision SCOPE{"Scope با Resource منطبق است؟"}:::decision GUARD{"Guard و Policy اجازه می‌دهند؟"}:::decision DENY{"Deny یا Suspension مؤثر وجود دارد؟"}:::decision ALLOW(["اجازه انجام Action و ثبت Audit لازم"]):::success REJECT(["رد امن دسترسی"]):::error START --> IDENTITY IDENTITY -->|"خیر"| REJECT IDENTITY -->|"بله"| MEMBERSHIP MEMBERSHIP -->|"خیر"| REJECT MEMBERSHIP -->|"بله"| ROLE ROLE -->|"خیر"| REJECT ROLE -->|"بله"| PERMISSION PERMISSION -->|"خیر"| REJECT PERMISSION -->|"بله"| SCOPE SCOPE -->|"خیر"| REJECT SCOPE -->|"بله"| GUARD GUARD -->|"خیر"| REJECT GUARD -->|"بله"| DENY DENY -->|"بله"| REJECT DENY -->|"خیر"| ALLOW classDef start fill:#DBEAFE,stroke:#2563EB,color:#172554,stroke-width:2px; classDef decision fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:2px; classDef success fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:2px; classDef error fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D;

۱۷. سناریوهای سوءاستفاده

حداقل این موارد بررسی شوند:

  • تغییر Building ID یا Unit ID در درخواست
  • استفاده از Role یک ساختمان در ساختمان دیگر
  • اجرای Action پس از پایان Scope
  • فعال‌سازی Role پیش از پذیرش
  • استفاده دوباره از Support Grant منقضی
  • اعطای Permission مستقیم به شخص
  • دسترسی به Person یا Unit نامرتبط
  • کاهش Permission بدون اصلاح Session یا Cache
  • درخواست تکراری برای Action حساس

۱۸. کنترل کیفیت

  • Deny by default رعایت شده است.
  • Permissionها از Actionهای واقعی استخراج شده‌اند.
  • Role و Permission با هم اشتباه نشده‌اند.
  • Permission مستقیم به شخص داده نمی‌شود.
  • Scope برای هر Permission مشخص است.
  • Guardهای Workflow ثبت شده‌اند.
  • Roleهای پیش‌فرض کمترین دسترسی لازم را دارند.
  • Permissionهای حساس مشخص و دارای تأیید یا Audit هستند.
  • Self-service Actionها از Permission مدیریتی جدا شده‌اند.
  • دسترسی پشتیبانی موقت، محدود و Ticket-based است.
  • پایان Role یا Scope دسترسی نامرتبط را حذف نمی‌کند.
  • Role Pending هیچ Permission فعالی ندارد.
  • تمام Actionها در سمت سامانه دوباره Authorization می‌شوند.
  • Matrix با Permission Catalog و Role Templateها سازگار است.
  • تصمیم‌های باز و استثناها ثبت شده‌اند.

۱۹. روش اجرای استاندارد

  1. Actionهای User Flow و Transitionهای Workflow استخراج شوند.
  2. Resource و Scope هر Action مشخص شود.
  3. Permission Catalog ساخته شود.
  4. Permissionهای حساس علامت‌گذاری شوند.
  5. Roleهای ماژول و بسته پیش‌فرض آن‌ها تعریف شوند.
  6. Default Role Matrix ساخته شود.
  7. Guard، Policy، Audit و Self-service Actionها تکمیل شوند.
  8. دسترسی پشتیبانی و Break-glass جدا مدل شوند.
  9. سناریوهای سوءاستفاده بررسی شوند.
  10. تناقض با Domain Model و Workflow برطرف شود.
  11. پس از تأیید، UI فقط Actionهای مجاز را نمایش دهد؛ Backend همچنان هر درخواست را مستقل بررسی کند.

۲۰. منابع