إدارة كلمات المرور

جديد في الإصدار v2.4.0

يستخدم نظام المصادقة في Potato خوارزمية PBKDF2-SHA256 بـ 100000 تكرار مع ملح خاص بكل مستخدم، وهو الأسلوب نفسه الذي يوصي به NIST لتخزين كلمات المرور بأمان. تشرح هذه الصفحة كيف تُخزَّن كلمات المرور، وكيف يُعاد تعيينها، وكيف تُحفظ بيانات الاعتماد بين عمليات إعادة تشغيل الخادم.

تنطبق الصفحة على الطريقتين in_memory وdatabase. أما مع OAuth فمزوّد الهوية هو من يدير كلمة المرور، فلا ينطبق شيء من هذا إلا على الحسابات المحلية في الوضع المختلط.

تفاصيل التنفيذ الأمني

تُخزَّن كلمات المرور بصيغة salt$hash:

• ملح سداسي عشري من 32 محرفاً، فريد لكل مستخدم
• خلاصة سداسية عشرية من 64 محرفاً، مشتقة بـ PBKDF2-HMAC-SHA256 من كلمة المرور مع ذلك الملح و100000 تكرار
• مقارنة بزمن ثابت عبر hmac.compare_digest لمنع هجمات التوقيت

تمريرة واحدة من SHA-256 على كلمة مرور مملّحة سريعة بما يكفي لكسرها بالقوة الغاشمة على نطاق واسع. والتكرارات المئة ألف هي ما يجعل كل محاولة تخمين مكلفة.

أما كلمات المرور الموجودة كنص صريح في ملفات user_config.json فتُعاد تجزئتها تلقائياً بأملاح فريدة عندما يحمّلها Potato، دون حاجة إلى ترحيل يدوي.

التهيئة الافتراضية

يستخدم Potato افتراضياً المصادقة في الذاكرة. والمفتاح require_password مفتاح من المستوى الأعلى وليس جزءاً من كتلة authentication:

require_password: true
 
authentication:
  method: in_memory
 
user_config:
  users:
    - username: "annotator1"
      password: "initial-password"   # will be hashed on first load
    - username: "annotator2"
      password: "initial-password"

بيانات الاعتماد الدائمة

تُكتب الحسابات المنشأة عبر نموذج التسجيل في ملف JSONL وتُقرأ من جديد عند التشغيل التالي. ومع in_memory يكون هذا الملف user_config.json بجوار مجلد المخرجات، ما لم تحدد ملفاً آخر.

الحفظ في ملف

authentication:
  method: in_memory
  user_config_path: /shared/path/to/user_config.jsonl

حدّد مساراً عندما تتشارك عدة نسخ من الخادم قائمة مستخدمين واحدة، أو عندما تريد وضع القائمة في مكان غير مجاور للتعليقات التوضيحية. تُكتب التسجيلات الجديدة وتغييرات كلمات المرور لحظة حدوثها.

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

قبل الإصدار v2.8.3 لم تكن in_memory تكتب شيئاً ما لم يُضبط user_config_path صراحةً، فلم تكن الحسابات تبقى بعد إعادة التشغيل. إذا أجريت دراسة على إصدار أقدم، فتلك الحسابات قد ضاعت، أما التعليقات التوضيحية فلم تضع.

قاعدة بيانات

SQLite (بلا اعتماديات إضافية):

authentication:
  method: database
  database_url: "sqlite:///auth/users.db"

PostgreSQL (تتطلب psycopg2-binary):

authentication:
  method: database
  database_url: "postgresql://user:password@localhost:5432/potato_auth"

ينشئ Potato الجدول users عند أول تشغيل، ويشغّل SQLite في وضع WAL لتحسين القراءات المتزامنة. يجب أن تبدأ database_url بـ sqlite:/// أو postgresql://. ويمكنك أيضاً ضبط POTATO_DB_CONNECTION في البيئة، وتتقدّم عليه database_url عند وجود الاثنين.

ملاحظة: لا يجتمع method: database مع user_config_path، فاختر إحدى استراتيجيتي الحفظ. ويُصدر Potato خطأً إذا هُيّئ الاثنان معاً.

إعادة تعيين كلمات المرور

سطر أوامر المشرف

أعد تعيين كلمة مرور من سطر الأوامر:

# Prompts for username and password
potato reset-password config.yaml
 
# Prompts for the password only
potato reset-password config.yaml --username annotator1

واجهة برمجة المشرف

أعد التعيين برمجياً باستخدام مفتاح API الخاص بالمشرف:

curl -X POST http://localhost:8000/admin/reset_password \
  -H "X-API-Key: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "annotator1", "new_password": "new-secure-password"}'

يُؤخذ المفتاح، بهذا الترتيب، من الإعداد admin_api_key في المستوى الأعلى، أو من متغير البيئة POTATO_ADMIN_API_KEY، أو من ملف admin_api_key.txt مولَّد في مجلد المهمة.

إعادة التعيين الذاتية بالرموز

يستطيع المعلّقون الذين نسوا كلمة المرور إعادة تعيينها بأنفسهم. ينتقلون إلى /forgot-password ويدخلون اسم المستخدم، فيولّد Potato رمزاً صالحاً لمرة واحدة ولمدة 24 ساعة. يظهر رابط إعادة التعيين على الشاشة ليمرّره المشرف، إذ لا يرسل Potato أي بريد إلكتروني. يفتح المعلّق /reset/<token> ويضبط كلمة مرور جديدة، فيُستهلك الرمز.

لا يحتاج هذا التدفق إلى أي تهيئة. وعند ضبط require_password: true يظهر رابط "Forgot Password?" في صفحة تسجيل الدخول.

ويمكن للمشرفين أيضاً توليد رمز مباشرة:

curl -X POST http://localhost:8000/admin/create_reset_token \
  -H "X-API-Key: $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "annotator1"}'
 
# {"reset_link": "http://localhost:8000/reset/abc123...",
#  "token": "abc123...", "expires_in_hours": 24}

مرّر "ttl_hours": 48 في جسم الطلب لتحديد مدة صلاحية مختلفة.

الوضع بلا كلمة مرور

في العروض الصفية والدراسات السريعة والمهام التي تعتمد مصادقة خارجية (MTurk وProlific)، يمكنك تعطيل كلمات المرور بالكامل:

require_password: false
 
authentication:
  method: in_memory

يدخل المعلّقون بأي اسم مستخدم، ولا تظهر مطالبة بكلمة مرور. وهذا غير مستحسن للبيانات الحساسة أو المهام التي تتطلب هوية موثّقة.

راجع تسجيل الدخول بدون كلمة مرور للتفاصيل.

المرجع الكامل

# Top-level: require a password at login (default: true)
require_password: true
 
# Top-level: key for the admin endpoints
admin_api_key: ${POTATO_ADMIN_API_KEY}
 
authentication:
  # in_memory (default) | database | clerk | oauth
  method: in_memory
 
  # in_memory only, mutually exclusive with method: database
  user_config_path: users.jsonl
 
  # database only; sqlite:/// or postgresql://
  # database_url: "sqlite:///auth.db"
 
user_config:
  users:
    - username: "researcher"
      password: "secure-passphrase"
    - username: "annotator1"
      password: "initial-pass"

قراءة إضافية

• مصادقة SSO وOAuth: تسجيل الدخول عبر Google أو GitHub أو نظام SSO المؤسسي
• تسجيل الدخول بدون كلمة مرور: وصول باسم المستخدم فقط للمهام المفتوحة
• إعداد الإنتاج: تهيئة HTTPS والوسيط العكسي
• لوحة تحكم المشرف: إدارة حسابات المعلّقين

للاطلاع على تفاصيل التنفيذ، راجع الوثائق المصدرية.