المفاهيم الأساسية

هذه الصفحة تشرح المفاهيم الأساسية في Ithbat IAM. قراءتها تساعدك تتخذ قرارات دمج أفضل وتفهم المنطق وراء تصميم API.

الـ Tenants

الـ Tenant هو حد العزل الأعلى في Ithbat IAM. كل مستخدم ودور ومجموعة وSession وسجل إعدادات ينتمي لـ tenant واحد فقط. الـ Tenants معزولون تمامًا عن بعض: لا يمكن لمستخدم في Tenant "أ" أن يُرى أو يُستعلم عنه أو يُصادَق ضد Tenant "ب" تحت أي ظرف.

عند التسجيل في Ithbat IAM، تُنشئ tenant واحداً على الأقل. الإعداد النموذجي يتضمن tenant لكل بيئة (تطوير، اختبار، إنتاج). المنتجات التي تخدم عدة عملاء مستقلين — تطبيق SaaS مثلاً — تمثّل كل عميل كـ tenant، مما يعطيهم أدلة مستخدمين منفصلة وهوية بصرية منفصلة وإعدادات منفصلة.

كل API request مرتبط بـ tenant يجب يتضمن header الـ X-Tenant-ID مع UUID الخاص بالـ tenant. معظم endpoints تسجيل الدخول والتسجيل تدعم أيضًا التعرف التلقائي على الـ tenant: إذا حذفت X-Tenant-ID، API يحدد الـ tenant من نطاق بريد المستخدم عبر POST /api/v1/auth/resolve-tenant.

curl -X POST https://api.ithbat.io/api/v1/auth/resolve-tenant \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

{
  "tenantId": "3f8a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c",
  "tenantSlug": "acme",
  "tenantName": "Acme Corp"
}

إعدادات الـ Tenant تغطي الهوية البصرية (الشعار، الألوان، النطاق المخصص)، وسياسات الأمان (قوة كلمة المرور، فرض MFA، مدة الـ Session، قوائم IP المسموحة)، وقوالب البريد الإلكتروني، وFeature Flags. تُدار جميعها عبر Settings API أو لوحة تحكم المسؤول.

المستخدمون

المستخدم هو هوية رقمية مصادق عليها داخل tenant. يُعرّف المستخدمون ببريدهم الإلكتروني ويمكنهم حمل حقول الملف الشخصي التالية:

الحقل	النوع	ملاحظات
`id`	UUID	يُنشأ تلقائيًا، غير قابل للتعديل
`tenantId`	UUID	الـ Tenant المالك
`email`	string	فريد داخل الـ Tenant
`firstName`	string	مطلوب عند التسجيل
`fatherName`	string	اختياري؛ يُستخدم في أنماط التسمية العربية
`grandfatherName`	string	اختياري
`familyName`	string	مطلوب عند التسجيل
`displayName`	string	محسوب: `firstName + familyName`
`status`	enum	`active`، `suspended`، `locked`
`mfaEnabled`	boolean	هل تم تسجيل أي عامل MFA
`metadata`	object	أزواج key/value عشوائية لاستخدام التطبيق
`externalIds`	object	معرّفات أنظمة خارجية (مثل `{"salesforce": "0031a00000xyz"}`)

المستخدمون يمرون بدورة حياة: نشط هو الحالة الطبيعية، موقوف يعني أن مسؤول عطّل الوصول بدون حذف الحساب، ومقفل يعني أن الحساب قُفل بسبب محاولات تسجيل دخول فاشلة كثيرة. يمكنك فتح الحسابات المقفلة عبر POST /api/v1/users/{id}/unlock دون فقدان أي بيانات.

التحقق من البريد الإلكتروني مطلوب افتراضيًا. بعد التسجيل، المستخدم يتلقى رابط تحقق. حتى يتحقق، بعض العمليات ممكن تكون محظورة وفق السياسة. يمكنك إعادة إرسال بريد التحقق عبر POST /api/v1/auth/resend-verification، أو تخطّي التحقق تمامًا للمستخدمين المُنشأين من المسؤول بتمرير skipEmailVerification: true في request الإنشاء.

المصادقة

Ithbat IAM يدعم عدة أساليب مصادقة. جميع عمليات المصادقة الناجحة تُعيد نفس بنية الـ Tokens:

{
  "accessToken": "eyJ...",
  "refreshToken": "rt_...",
  "idToken": "eyJ...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "user": { ... }
}

البريد الإلكتروني وكلمة المرور هو الأسلوب الأساسي. كلمات المرور تُجزّأ باستخدام bcrypt وتُتحقق وفق سياسة كلمة المرور الخاصة بالـ tenant (الحد الأدنى للطول والتعقيد والسجل وكشف الاختراق — كل هذا قابل للتهيئة).

Passwordless تستخدم Magic Links محدودة الزمن تُرسل لبريد المستخدم. استدعِ POST /api/v1/auth/passwordless/start مع عنوان البريد، ثم POST /api/v1/auth/passwordless/verify مع الـ token من الرابط.

تسجيل الدخول الاجتماعي يفوّض المصادقة لـ identity provider خارجي. أعد توجيه المستخدم إلى GET /api/v1/auth/social/{provider}/login وتعامل مع الـ callback في GET /api/v1/auth/social/{provider}/callback. الـ providers المدعومون يُهيّؤون لكل tenant في إعدادات identity provider.

SAML 2.0 يُمكّن SSO للمؤسسات حيث يعمل الـ tenant كـ Service Provider (SP) ويعمل identity provider المؤسسة (Active Directory، Okta، Azure AD، إلخ) كـ IdP. تدفقات SAML متاحة في /api/v1/auth/saml/{tenant_id}/.

يمكن ربط Passwordless identities وSocial identities بحساب مستخدم موجود. يمكن للمستخدم أن يمتلك عدة هويات مرتبطة (واحدة لكل provider) إلى جانب بيانات اعتماد البريد وكلمة المرور.

الأدوار والصلاحيات

Ithbat IAM يستخدم RBAC بنموذج صلاحيات مسطح. الصلاحيات تتبع صيغة resource:action حيث الـ action هو read أو write أو delete.

user:read       — يمكنه عرض وقراءة الملفات الشخصية للمستخدمين
user:write      — يمكنه إنشاء وتحديث وإيقاف وإعادة تفعيل المستخدمين
user:delete     — يمكنه حذف المستخدمين نهائيًا
role:read       — يمكنه عرض الأدوار وتعيينات الصلاحيات
role:write      — يمكنه إنشاء وتعديل الأدوار وتعيينها للمستخدمين
audit:read      — يمكنه الاستعلام عن سجلات التدقيق وسجل تسجيل الدخول

الأدوار هي مجموعات مسماة من الصلاحيات. تنشئ أدوار في لوحة التحكم أو عبر POST /api/v1/roles وتعيّنها للمستخدمين عبر POST /api/v1/users/{id}/roles. يمكن للمستخدم أن يمتلك عدة أدوار؛ صلاحياته الفعلية هي اتحاد جميع الصلاحيات عبر جميع الأدوار المعيّنة.

صلاحية admin هي wildcard permission تمنح وصول كامل لكل شيء. عيّنها للأدوار التي يجب تملك قدرة إدارية كاملة داخل الـ tenant.

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

المؤسسات هي طبقة إضافية لمنتجات B2B. المؤسسة تمثل شركة العميل داخل الـ tenant. يمكن للمستخدمين أن يكونوا أعضاءً في مؤسسات متعددة ولديهم أدوار مختلفة في مؤسسات مختلفة، مما يتيح تحديد نطاق الصلاحيات لكل عميل.

curl -X POST https://api.ithbat.io/api/v1/users/a1b2c3d4-e5f6-7890-abcd-ef1234567890/roles \
  -H "Authorization: Bearer ADMIN_TOKEN" \
  -H "X-Tenant-ID: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"roleId": "r9b8a7c6-d5e4-3f21-bcde-fa0987654321"}'

الـ Sessions

الـ Session تمثل سياق المستخدم المصادق عليه على جهاز أو في متصفح. Ithbat IAM يدعم concurrent sessions — يمكن للمستخدم نفسه أن يكون مسجّلاً في عدة أجهزة في وقت واحد، كل منها بـ Refresh Token مستقل.

الـ Sessions تُنشأ عند تسجيل الدخول وتُدمّر عند تسجيل الخروج. يمكنك تعرض جميع الـ sessions النشطة للمستخدم الحالي عبر GET /api/v1/auth/sessions، وتلغي session محددة عبر DELETE /api/v1/auth/sessions/{id}، أو تلغي جميع الـ sessions الأخرى (مع الاحتفاظ بالحالية) عبر DELETE /api/v1/auth/sessions.

يستطيع المسؤولون عرض جميع الـ sessions لمستخدم محدد عبر GET /api/v1/users/{id}/sessions وإنهاؤها قسريًا عبر DELETE /api/v1/users/{id}/sessions. مفيد للاستجابة لحوادث الأمان.

إعدادات أمان الـ tenant تتحكم بمدة الـ Session. عند انتهاء صلاحية الـ Refresh Token، يجب على المستخدم إعادة المصادقة. تفعيل كشف الـ Sessions المشبوهة يتسبب في وسم الـ sessions المشبوهة (دولة جديدة، جهاز جديد) وتحديها اختياريًا بـ MFA قبل منح الوصول.

الـ Tokens

Ithbat IAM يصدر ثلاثة أنواع من الـ Tokens عند كل مصادقة ناجحة:

Access Token — JWT قصير العمر (الافتراضي: ساعة واحدة) يفوّض الـ requests للـ protected endpoints. يحتوي على معرّف المستخدم ومعرّف الـ Tenant والأدوار والصلاحيات كـ claims. مرّره في header الـ Authorization: Bearer. تحقق منه مقابل المفاتيح العامة لـ OIDC المنشورة في GET /.well-known/openid-configuration.

Refresh Token — token مُعتم طويل العمر (الافتراضي: 30 يومًا) يُستخدم للحصول على Access Tokens جديدة. مرتبط بالـ Session وخاضع للتدوير: كل استدعاء لـ POST /api/v1/auth/refresh يُبطل الـ Refresh Token السابق ويصدر جديد. خزّن الـ Refresh Tokens بأمان (HttpOnly cookies للمتصفحات، secure storage لتطبيقات الهاتف).

ID Token — JWT متوافق مع OIDC يحتوي على claims الملف الشخصي للمستخدم (sub، email، name، إلخ). استخدمه لتأسيس الهوية في طبقة تطبيقك؛ لا تستخدمه لتفويض API.

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "[email protected]",
  "name": "Jane Doe",
  "iss": "https://api.ithbat.io",
  "aud": "your-tenant-id",
  "iat": 1740390000,
  "exp": 1740393600,
  "roles": ["member"],
  "permissions": ["user:read"]
}

مفاتيح API

مفاتيح API هي credentials طويلة العمر لعمليات الدمج بين الخوادم حيث لا يوجد مستخدم نهائي. تُنشأ لكل tenant من الإعدادات > مفاتيح API في لوحة تحكم المسؤول وتُمرّر في header الـ Authorization: Bearer تمامًا كـ Access Token.

مفاتيح API تحمل صلاحيات الدور الذي أُنشئت به. أنشئ مفاتيح API منفصلة لكل خدمة أو بيئة وحدّد نطاق كل منها بالحد الأدنى من الصلاحيات المطلوبة. يمكنك إلغاء مفتاح API في أي وقت من لوحة التحكم دون التأثير على أي credentials أخرى.

تحذير

مفاتيح API لا تنتهي صلاحيتها تلقائيًا. دوّرها دوريًا وألغها فورًا إذا اشتبهت في اختراق. لا تضمّن مفاتيح API أبدًا في client-side code أو public repositories.

المؤسسات

المؤسسات تمثل حالة استخدام B2B حيث مستخدليس الـ tenant يمثلون عدة شركات أو أقسام مستقلة. لكل مؤسسة قائمة أعضاء خاصة وتعيينات أدوار خاصة.

يمكن للمستخدم أن ينتمي إلى عدة مؤسسات في وقت واحد، كل منها بدور مختلف. مثلاً، مستشار في شركة استشارات قد يكون viewer في مؤسسة العميل "أ" وadmin في مؤسسة العميل "ب"، كل ذلك ضمن نفس الـ tenant.

أنشئ المؤسسات عبر POST /api/v1/organizations، وأضف الأعضاء عبر POST /api/v1/organizations/{id}/members، وعيّن الأدوار لكل مؤسسة عبر PUT /api/v1/organizations/{id}/members/{userId}/roles.

يستطيع المستخدمون تمرير organizationId في طلب تسجيل الدخول لتحديد نطاق الـ session بسياق مؤسسة محددة:

{
  "email": "[email protected]",
  "password": "SecurePass123!",
  "organizationId": "org-uuid-here"
}

المناطق وData Residency

Ithbat IAM يعمل عبر ثلاث مناطق:

المنطقة	الوصف	حالة الاستخدام
عالمي	المنطقة الافتراضية	الاستخدام العام والتطبيقات الدولية
المملكة العربية السعودية	المملكة العربية السعودية	متطلبات data residency وفق لوائح SAMA وNCA
مصر	مصر	متطلبات data residency وفق قانون حماية البيانات الشخصية المصري

عند إنشاء الـ tenant، تختار منطقته. جميع البيانات — المستخدمون وسجلات التدقيق والـ Sessions والـ Tokens — تُخزّن وتُعالج داخل تلك المنطقة. لا يحدث نقل بيانات عبر المناطق للبيانات المرتبطة بالـ tenant.

اختر منطقتك عبر GET /api/v1/regions للاطلاع على الخيارات المتاحة، ثم حددها أثناء إنشاء الـ tenant عبر POST /api/v1/tenants/register.

الـ Tenants​

المستخدمون​

المصادقة​

الأدوار والصلاحيات​

الـ Sessions​

الـ Tokens​

مفاتيح API​

المؤسسات​

المناطق وData Residency​