دليل المصادقة الثنائية (2FA)

نظرة عامة

تضيف المصادقة الثنائية (2FA) طبقة حماية إضافية لعملية تسجيل الدخول في نما، إذ تطلب من المستخدمين تقديم وسيلة تحقق ثانية تتجاوز اسم المستخدم وكلمة المرور. تدعم هذه الميزة طرق مصادقة متعددة وتوفر خيارات إعداد مرنة لمسؤولي النظام.

طرق المصادقة المدعومة

1. Message OTP (كلمة المرور لمرة واحدة)

تستخدم قالب الإشعار المُعدّ الذي يمكنه إرسال رموز OTP عبر قنوات متعددة:

• SMS: إرسال رموز OTP عبر رسالة قصيرة إلى رقم الجوال المسجّل للمستخدم
• البريد الإلكتروني: إرسال رموز OTP إلى عنوان البريد الإلكتروني المسجّل للمستخدم
• WhatsApp: إرسال رموز OTP عبر رسائل WhatsApp
• إشعارات داخل التطبيق: عرض OTP ضمن نظام الإشعارات في التطبيق

2. تكامل Estidamah API

تكامل مع مزود مصادقة مخصص للمؤسسات التي تستخدم بوابة مصادقة Estidamah. تعمل هذه الطريقة على النحو التالي:

• تشفير بيانات الاعتماد باستخدام مفاتيح التشفير المُعدّة
• إرسال البيانات المشفرة إلى بوابة مصادقة Estidamah
• تتولى البوابة تسليم OTP للمستخدمين
• التحقق من OTP عبر الـ API المتكاملة

3. بلا مصادقة ثنائية

تعطيل المصادقة الثنائية (غير موصى به في بيئات الإنتاج)

من لا يُطلب منه رمز أبداً

حتى مع تفعيل المصادقة الثنائية، تمر ثلاث حالات دون سؤال، وإليها ينتهي كل سؤال عن «لماذا لم يُطلب مني رمز؟»:

• المستخدم admin؛
• المستخدم الذي عُلِّم في سجله خيار استثناء من المصادقة الثنائية؛
• الجلسة التي تحقق رمزها بالفعل — فالرمز المتحقق منه محفوظ، ولذلك لا تُسأل عنه الطلبات التالية للدخول.

إعدادات الضبط

الوصول إلى إعدادات تسجيل الدخول

افتح إدارة النظام ← الإعدادات ← إعدادات النظام، واختر ملف الإعدادات العامة، ثم صفحة الأمان وتسجيل الدخول — والخيارات في مجموعة المصادقة الثنائية فيها.

قواعد التحقق من الإعدادات

يطبّق النظام قواعد التحقق التالية عند ضبط المصادقة الثنائية:

1. متطلبات طريقة Message OTP:

   • قالب الإشعار: يجب اختيار تعريف إشعار لإرسال رموز OTP
   • رسالة الخطأ في حال عدم الضبط: "Can not select the option Message OTP without fill Notification For Two-Factor Authentication OTP"

2. متطلبات طريقة Estidamah API:

   • تحتاج الطريقة إلى أربعة إعدادات — Estidamah Environment Url وEstidamah Api Key وEstidamah Encryption Key وEstidamah Encryption IV. ثلاثة منها تُفحص عند الحفظ، أما Api Key فلا يُفحص، فيُحفظ الإعداد الناقص بلا اعتراض ثم يفشل عند البوابة في أول محاولة دخول. فاملأ الأربعة.
   • Custom Password Validator: يجب تفعيله في nama.properties
   • الخطأ في حال عدم التفعيل: "You can not enable estidamah login method without enabling custom password validator in nama.properties first, use-custom-password-validator=true"

حقول الضبط المتاحة في الإعداد العام

الحقل	الوصف	الافتراضي	الخيارات	قواعد التحقق
نوع المصادقة الثنائية لتسجيل الدخول	العامل الثاني الذي يطلبه تسجيل الدخول	None	None · Message OTP · Estidamah API	-
تنبيه OTP للمصادقة الثنائية	تعريف التنبيه الذي يحمل الرمز	-	أي تعريف تنبيه يدوي	مطلوب حين تكون الطريقة Message OTP
OTP Format	شكل الرمز المُولَّد	Numeric	Numeric (123456) · Alphabetic (ABCDEF) · AlphaNumeric (A1B2C3)	-
طول OTP	عدد أحرف الرمز	6 إذا تُرك الحقل فارغاً أو صفراً	أي عدد	-
وقت انتهاء صلاحية OTP	الثواني قبل أن يتوقف قبول الرمز	3 دقائق إذا تُرك الحقل فارغاً	دقائق صحيحة — تُقسم القيمة على 60، فتعمل 90 ثانية كدقيقة واحدة	-
مدة الانتظار قبل إعادة إرسال OTP	الثواني قبل أن يُسمح بطلب الرمز من جديد	60 إذا تُرك الحقل فارغاً أو صفراً	أي عدد	-

الإعدادات الخاصة بـ Estidamah

مطلوبة فقط عند استخدام طريقة Estidamah API:

الحقل	الوصف
Estidamah Environment Url	عنوان البوابة (يُفحص عند الحفظ)
Estidamah Api Key	مفتاح الحساب المرسَل مع كل نداء (لا يُفحص عند الحفظ، ومع ذلك تطلبه البوابة)
Estidamah Encryption Key	مفتاح التشفير لتأمين بيانات الاعتماد (يُفحص عند الحفظ)
Estidamah Encryption IV	متجه التهيئة للتشفير (يُفحص عند الحفظ)

متطلب إعداد مهم

لاستخدام طريقة مصادقة Estidamah API، يجب تفعيل custom password validator في nama.properties:

use-custom-password-validator=true

يمنع هذا الإعداد تشفير كلمة المرور ويسمح للنظام بإرسال بيانات الاعتماد المشفرة إلى بوابة Estidamah.

تجربة المستخدم

تسجيل الدخول القياسي مع المصادقة الثنائية

1. تسجيل الدخول الأولي

   • يُدخل المستخدم اسم المستخدم وكلمة المرور
   • يتحقق النظام من بيانات الاعتماد

2. توليد OTP

   • إذا كانت المصادقة الثنائية مفعّلة، يُولّد النظام OTP
   • يُرسَل OTP عبر الطريقة المُعدّة (SMS/بريد إلكتروني/إشعار)
   • يرى المستخدم شاشة إدخال OTP

3. التحقق من OTP

   • يُدخل المستخدم رمز OTP المستلَم
   • يتحقق النظام من OTP
   • عند التحقق الناجح، يحصل المستخدم على الوصول

4. إعادة إرسال OTP

   • إذا لم يستلم المستخدم OTP، يمكنه طلب إعادة الإرسال
   • الإرسال متاح بعد انتهاء فترة التأخير المُعدّة
   • يُعاد إرسال نفس OTP إذا كان لا يزال صالحاً، أو يُولَّد رمز جديد إذا انتهت صلاحيته

رسائل قد تراها

الرسالة	ماذا تعني
«You must provide OTP»	كلمة المرور صحيحة، وهذا طلب الرمز لا رفض. وتحمل الرسالة طول الرمز ومدة الانتظار قبل إعادة الإرسال، وهو ما تعرضه شاشة الرمز.
«Invalid OTP»	الرمز لا يطابق الرمز الصادر، أو انتهت صلاحيته وأُرسل رمز أحدث. اطلب رمزاً جديداً.
«Error with Message OTP»	تعذّر إرسال الرمز أصلاً — والسبب في الغالب تعريف التنبيه: غير موجود، أو ليس يدوياً، أو لا يحمل المستخدم رقم موبايل أو بريداً.

إعدادات المستخدم

استثناء المستخدمين من المصادقة الثنائية

يمكن استثناء مستخدمين بعينهم من متطلبات المصادقة الثنائية:

1. افتح إدارة النظام ← الصلاحيات ← مستخدم
2. ابحث عن حساب المستخدم
3. علّم خيار استثناء من المصادقة الثنائية في إعدادات المستخدم
4. احفظ التغييرات

هذا مفيد لـ:

• حسابات الخدمة
• حسابات الوصول الطارئ
• المستخدمون في أدوار محددة لا تستلزم المصادقة الثنائية

تفاصيل التنفيذ التقني

إدارة الجلسة

• يرتبط التحقق من OTP بجلسة تسجيل الدخول
• بعد التحقق، يُخزَّن معرّف OTP مؤقتاً
• استدعاءات الـ API اللاحقة ضمن الجلسة لا تتطلب إعادة التحقق
• انتهاء الجلسة يستدعي إجراء مصادقة ثنائية جديدة

إعداد قالب الإشعار

إنشاء قالب إشعار المصادقة الثنائية

1. افتح إدارة النظام ← تخصيص شكل النظام ← تعريف تنبيهات
2. أنشئ إشعاراً يدوياً جديداً بما يلي:
   • الاسم: "2FA OTP Notification"
   • للنوع: User
   • يدوي: True (محدد)
   • القناة: اختر واحدة أو أكثر:
     • SMS
     • البريد الإلكتروني
     • WhatsApp
     • إشعار داخل التطبيق
   • متغيرات القالب:
     • {name1} - الاسم العربي الكامل للمستخدم
     • {name2} - الاسم الإنجليزي الكامل للمستخدم
     • {otpCode} - رمز OTP المُولَّد
     • أي حقل متاح في ملف بيانات المستخدم الرئيسي

مثال على قالب SMS

Dear ${name2},
Your Nama ERP verification code is: {otpCode}
This code expires in 3 minutes.
Do not share this code with anyone.

مثال على قالب البريد الإلكتروني

<p>Dear {name1},</p>
<p>Your Nama ERP login verification code is:</p>
<h2>{otpCode}</h2>
<p>This code will expire in 2 minutes.</p>
<p>If you didn't request this code, please contact your system administrator immediately.</p>

مثال على قالب WhatsApp

🔐 *Nama ERP Security Code*

Hello {name2},

Your verification code is: *{otpCode}*

⏱️ Valid for 3 minutes only
⚠️ Do not share this code with anyone

If you didn't request this, contact IT immediately.