RBAC -- التحكم بالوصول بالأدوار

يعتمد Ithbat على نموذج صلاحيات بصيغة resource:action. كل عملية محمية تتطلب صلاحية محددة، والأدوار هي مجموعات مسمّاة من هذه الصلاحيات. عيّن دورًا أو أكثر للمستخدم لمنحه الوصول المطلوب.

---

نموذج الصلاحيات

الصلاحيات تتبع صيغة resource:action مع ثلاثة actions:

Action	الوصف
read	عرض وسرد المورد
write	إنشاء أو تحديث المورد
delete	حذف المورد

مستخدم يملك user:write يمكنه إنشاء وتحديث المستخدمين، لكنه لا يستطيع حذفهم بدون user:delete.

مرجع الصلاحيات الكامل

الصلاحية	تتحكم بالوصول إلى
user:read	عرض وسرد حسابات المستخدمين
user:write	إنشاء وتحديث حسابات المستخدمين
user:delete	حذف حسابات المستخدمين
role:read	عرض وسرد الأدوار
role:write	إنشاء وتحديث الأدوار، تعيين وإلغاء الأدوار
role:delete	حذف الأدوار
group:read	عرض وسرد المجموعات وأعضائها
group:write	إنشاء وتحديث المجموعات، إضافة وإزالة الأعضاء، تعيين أدوار للمجموعات
organization:read	عرض وسرد المؤسسات وأعضائها
organization:write	إنشاء وتحديث المؤسسات وإدارة الأعضاء
tenant:read	عرض تفاصيل الـ Tenant والإحصائيات والفوترة
tenant:write	تحديث إعدادات الـ Tenant، إنشاء وإيقاف وحذف Tenants
tenant:delete	حذف Tenants
settings:read	عرض الإعدادات وإعدادات SAML وIdP وسياسات كلمات المرور
settings:write	تحديث الإعدادات، إنشاء إعدادات SAML/IdP، إدارة IP Whitelists
billing:read	عرض الاشتراك والفواتير والاستخدام ووسائل الدفع
billing:write	إنشاء وتغيير الاشتراكات، إضافة وإزالة وسائل الدفع
oauth:read	عرض وسرد OAuth 2.0 Clients
oauth:write	إنشاء وتحديث وحذف OAuth Clients
webhook:read	سرد إخطارات آلية وعرض Delivery Logs
webhook:write	إنشاء وتحديث وحذف إخطارات آلية، إرسال Test Events، وRetry Deliveries
feature:read	عرض Feature Flags وTenant Overrides
feature:write	إنشاء وتحديث وحذف Feature Flags وOverrides
invitation:read	عرض وسرد الدعوات
invitation:write	إرسال وإعادة إرسال وإبطال الدعوات
permission:read	سرد الصلاحيات المتاحة
permission:write	إنشاء صلاحيات مخصصة
policy:read	عرض سياسات الوصول
policy:write	إنشاء وتحديث وحذف السياسات
workflow:read	عرض Workflows وInstances وطلبات الوصول
workflow:write	إنشاء وإدارة Workflows، الموافقة على طلبات الوصول أو رفضها
directory:read	عرض اتصالات الدليل ومهام المزامنة
directory:write	إنشاء وتحديث اتصالات الدليل وتشغيل المزامنة
scim:read	عرض إعدادات SCIM والـ Tokens والـ Logs
scim:write	تحديث إعدادات SCIM، إنشاء وإبطال Tokens
email_template:read	عرض قوالب البريد الإلكتروني
email_template:write	تحديث ومعاينة قوالب البريد
content:read	عرض عناصر المحتوى
content:write	إنشاء وتحديث ونشر وأرشفة المحتوى
audit:read	عرض سجل التدقيق وسجلات تسجيل الدخول
log:read	الاستعلام عن السجلات الخام وتصديرها
analytics:read	عرض لوحات التحليلات

Admin Wildcard

الصلاحية الخاصة admin تمنح وصولًا كاملًا لـ جميع الموارد داخل الـ Tenant. دور يتضمن admin لا يحتاج أي صلاحية أخرى. آلية التحقق:

hasPermission = permissions.includes('admin') || permissions.includes('system:admin') || permissions.includes(requiredPermission)

---

الأدوار المدمجة

يتضمن Ithbat ثلاثة أدوار نظام لا يمكن حذفها:

الدور	الصلاحيات	الوصف
Tenant Admin	admin (wildcard)	وصول كامل لجميع موارد الـ Tenant
User	user:read، content:read	عضو عادي -- يستعرض ملفه الشخصي والمحتوى العام
System Admin	system:admin	مسؤول على مستوى المنصة (لوحة تحكم المنصة فقط)

---

إنشاء أدوار مخصصة

الأدوار المخصصة تتيح تطبيق مبدأ الحد الأدنى من الصلاحيات. مثلًا، دور Support Agent يمكنه قراءة بيانات المستخدمين دون تعديلها.

عبر لوحة تحكم المسؤول

1. انتقل إلى الأدوار > إنشاء دور.
2. أدخل الاسم ووصفًا اختياريًا.
3. اختر الصلاحيات من شجرة الصلاحيات.
4. انقر حفظ.

عبر الـ API

POST /api/v1/roles
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "name": "Support Agent",
  "description": "Read-only access to users and audit logs"
}

بعد إنشاء الدور، عيّن الصلاحيات بتحديثه:

PUT /api/v1/roles/{id}
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Support Agent",
  "description": "Read-only access to users and audit logs",
  "permissions": ["user:read", "audit:read"]
}

الـ Response:

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "tenantId": "c2e3f4a5-...",
  "name": "Support Agent",
  "description": "Read-only access to users and audit logs",
  "permissions": ["user:read", "audit:read"],
  "isSystem": false,
  "createdAt": "2026-02-24T10:00:00Z",
  "updatedAt": "2026-02-24T10:00:00Z"
}

---

تعيين الأدوار للمستخدمين

عبر لوحة تحكم المسؤول

1. انتقل إلى المستخدمون > {المستخدم} > الأدوار.
2. انقر تعيين دور واختر من الأدوار المتاحة.

عبر الـ API

POST /api/v1/users/{userId}/roles
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

إزالة دور من مستخدم

DELETE /api/v1/users/{userId}/roles/{roleId}
Authorization: Bearer {token}

جلب الـ Effective Permissions لمستخدم

GET /api/v1/users/{userId}/permissions
Authorization: Bearer {token}

يرجع الـ Response الـ union لجميع الصلاحيات من كل الأدوار المعيّنة:

{
  "userId": "3fa85f64-...",
  "permissions": ["user:read", "audit:read"]
}

---

Group-Based Access

عيّن أدوارًا للمجموعات بدل الأفراد. عند انضمام مستخدم للمجموعة يرث أدوارها تلقائيًا. هذا النهج المُوصى به لإدارة الوصول على نطاق واسع.

تعيين دور لمجموعة

POST /api/v1/groups/{groupId}/roles
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "roleId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
}

عرض أدوار المجموعة

GET /api/v1/groups/{groupId}/roles
Authorization: Bearer {token}

عند إضافة مستخدم لمجموعة يرث فورًا أدوارها. وعند إزالته تُلغى الأدوار الموروثة.

---

الصلاحيات على مستوى المؤسسة

يدعم Ithbat المؤسسات داخل الـ Tenant -- وحدات فرعية كالأقسام مثلًا. يمكن للمستخدم أن يملك أدوارًا مختلفة في مؤسسات مختلفة.

إضافة مستخدم لمؤسسة بدور محدد

POST /api/v1/organizations/{orgId}/members
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}
Content-Type: application/json

{
  "userId": "3fa85f64-...",
  "roles": ["7c9e6679-..."]
}

تحديث أدوار عضو في المؤسسة

PUT /api/v1/organizations/{orgId}/members/{userId}/roles
Authorization: Bearer {token}
Content-Type: application/json

{
  "roles": ["new-role-id"]
}

---

التحقق من الصلاحيات في تطبيقك

من الـ Access Token (JWT)

عند المصادقة، تُضمَّن الصلاحيات في الـ JWT Claims. فكّ ترميز الـ Token لقراءتها:

{
  "sub": "3fa85f64-...",
  "tenant_id": "c2e3f4a5-...",
  "permissions": ["user:read", "audit:read"],
  "exp": 1740391200
}

في JavaScript/TypeScript

function hasPermission(token: DecodedToken, permission: string): boolean {
  return token.permissions.includes('admin') ||
         token.permissions.includes('system:admin') ||
         token.permissions.includes(permission);
}

if (hasPermission(decodedToken, 'user:write')) {
  // show create user button
}

في Server Middleware (مثال Go)

func RequirePermission(required string) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            claims := claimsFromContext(r.Context())
            for _, p := range claims.Permissions {
                if p == "admin" || p == "system:admin" || p == string(required) {
                    next.ServeHTTP(w, r)
                    return
                }
            }
            http.Error(w, "forbidden", http.StatusForbidden)
        })
    }
}

التحقق عبر الـ API

للتحقق من التفويض على الـ Server بدون JWT Decoding:

GET /api/v1/users/{userId}/permissions
Authorization: Bearer {token}

---

Access Request Workflow

المستخدمون الذين لا يملكون صلاحية معينة يمكنهم تقديم طلب وصول. يوافق عليه أو يرفضه مستخدم بصلاحية workflow:write.

تقديم طلب وصول

POST /api/v1/access-requests
Authorization: Bearer {user_token}
Content-Type: application/json

{
  "requestedRoleId": "7c9e6679-...",
  "reason": "Need access to run billing reports"
}

عرض الطلبات المعلّقة

GET /api/v1/access-requests/pending-approvals
Authorization: Bearer {approver_token}

الموافقة

POST /api/v1/access-requests/{id}/approve
Authorization: Bearer {approver_token}

الرفض

POST /api/v1/access-requests/{id}/reject
Authorization: Bearer {approver_token}
Content-Type: application/json

{
  "reason": "Access not required for your current role"
}

---

Roles API Reference

سرد الأدوار

GET /api/v1/roles
Authorization: Bearer {token}
X-Tenant-ID: {tenant_id}

جلب دور

GET /api/v1/roles/{id}
Authorization: Bearer {token}

جلب الصلاحيات المتاحة

يرجع القائمة الكاملة للصلاحيات القابلة للتعيين:

GET /api/v1/roles/permissions
Authorization: Bearer {token}

حذف دور

أدوار النظام (isSystem: true) لا يمكن حذفها.

DELETE /api/v1/roles/{id}
Authorization: Bearer {token}

---

أفضل الممارسات

الحد الأدنى من الصلاحيات -- امنح فقط الصلاحيات المطلوبة. ابدأ بـ read وأضف write عند الحاجة.

استخدم المجموعات للفرق -- عيّن الأدوار للمجموعات (Engineering، Finance، Support) بدل الأفراد. عند انضمام شخص أو مغادرته، حدّث عضويته لا صلاحياته.

لا توسّع admin -- صلاحية admin تمنح وصولًا كاملًا. احصرها في Tenant Admins واستخدم صلاحيات محددة للبقية.

راجع الأدوار دوريًا -- تحقق من يملك user:delete وtenant:write وbilling:write كل ربع سنة. استخدم سجل التدقيق لتتبع تعيينات الأدوار.

استخدم Access Requests للصلاحيات المرتفعة -- بدل منح صلاحيات مرتفعة بشكل دائم، وجّه الطلبات عبر الـ Approval Workflow.

---

الخطوات التالية

• Multi-Tenancy -- الأدوار على مستوى المؤسسة ونموذج الصلاحيات عبر الـ Tenants
• سجل التدقيق -- تتبع تعيينات الأدوار والتغييرات
• إدارة المستخدمين -- إدارة المستخدمين وتعيينات أدوارهم