المصادقة بالبريد الإلكتروني وكلمة المرور

المصادقة بالبريد الإلكتروني وكلمة المرور هي الأسلوب الأساسي في Ithbat IAM. هذا الدليل يغطي المسار كامل: التسجيل مع التحقق من البريد، تسجيل الدخول مع إصدار JWT Tokens، إعادة تعيين كلمة المرور، وتغييرها أثناء الـ Session.

الـ Base URL

كل Authentication Endpoints تحت:

https://api.ithbat.io/api/v1/auth

جميع الـ Requests تتطلب Header X-Tenant-ID إلا إذا ذُكر غير ذلك.

---

التسجيل

الـ Request

POST /api/v1/auth/register

Header مطلوب: X-Tenant-ID: <tenant-uuid>

{
  "email": "[email protected]",
  "firstName": "Sara",
  "familyName": "Al-Rashidi",
  "fatherName": "Ahmad",
  "grandfatherName": "Khalid",
  "password": "SecurePass123!"
}

الحقل	النوع	مطلوب	الوصف
email	string	نعم	البريد الإلكتروني للمستخدم
firstName	string	نعم	الاسم الأول
familyName	string	نعم	اسم العائلة
fatherName	string	لا	اسم الأب (أسماء MENA الرباعية)
grandfatherName	string	لا	اسم الجد
password	string	نعم	8 أحرف كحد أدنى

الـ Response — 201 Created

{
  "userId": "usr_01J8X...",
  "email": "[email protected]",
  "displayName": "Sara Al-Rashidi",
  "tenantId": "ten_01J8X...",
  "message": "Registration successful. Please check your email to verify your account."
}

ملاحظة

الحساب يُنشأ فورًا، لكن المستخدم لا يستطيع تسجيل الدخول إلا بعد التحقق من البريد الإلكتروني (إلا إذا عطّل المستفيد التحقق من الإعدادات).

متطلبات كلمة المرور

• 8 أحرف كحد أدنى
• قواعد التعقيد الإضافية (أحرف كبيرة، أرقام، رموز خاصة) تُهيّأ لكل مستفيد عبر إعدادات سياسة كلمة المرور

---

التحقق من البريد الإلكتروني

بعد التسجيل، Ithbat IAM يرسل verification email فيه Token مؤقت. صلاحية الـ Token 24 ساعة.

التحقق من البريد

POST /api/v1/auth/verify-email

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

الـ Response — 200 OK

{
  "message": "Email verified successfully"
}

إعادة إرسال verification email

POST /api/v1/auth/resend-verification

{
  "email": "[email protected]"
}

الـ Response دائمًا 200 OK برسالة عامة لمنع email enumeration:

{
  "message": "If the email exists and is not verified, a verification link has been sent"
}

نصيحة

أرسل X-Tenant-ID إذا كنت تعرف المستفيد. إذا لم ترسله، يحدد النظام المستفيد تلقائيًا من domain البريد الإلكتروني.

---

تسجيل الدخول

POST /api/v1/auth/login

الـ Request

{
  "email": "[email protected]",
  "password": "SecurePass123!"
}

X-Tenant-ID اختياري — إذا لم ترسله، يحدد النظام المستفيد من domain البريد. أرسله دائمًا إذا كنت تعرفه لتجنب lookup إضافي.

الـ Response — 200 OK (تسجيل دخول عادي)

{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "user": {
    "id": "usr_01J8X...",
    "tenantId": "ten_01J8X...",
    "email": "[email protected]",
    "firstName": "Sara",
    "fatherName": "Ahmad",
    "grandfatherName": "Khalid",
    "familyName": "Al-Rashidi",
    "displayName": "Sara Al-Rashidi",
    "roles": ["member"],
    "permissions": ["profile:read", "profile:write"]
  }
}

الـ Response — 200 OK (MFA مطلوبة)

إذا كانت MFA مفعّلة على الحساب، لا يُعيد الـ Response الأول أي Tokens. بدلًا من ذلك:

{
  "mfaRequired": true,
  "mfaToken": "mfa_challenge_token_here"
}

استخدم mfaToken لإكمال Challenge العامل الثاني. راجع دليل MFA للمسار الكامل.

---

مسار التسجيل ← التحقق ← تسجيل الدخول

sequenceDiagram
    participant Client
    participant Ithbat as Ithbat IAM
    participant Email as Email Service

    Client->>Ithbat: POST /api/v1/auth/register
    Ithbat->>Ithbat: Validate fields, hash password
    Ithbat->>Email: Send verification email
    Ithbat-->>Client: 201 { userId, message }

    Email-->>Client: Verification link (24h TTL)
    Client->>Ithbat: POST /api/v1/auth/verify-email { token }
    Ithbat->>Ithbat: Mark email as verified
    Ithbat-->>Client: 200 { message: "Email verified successfully" }

    Client->>Ithbat: POST /api/v1/auth/login { email, password }
    Ithbat->>Ithbat: Verify credentials
    Ithbat-->>Client: 200 { accessToken, refreshToken, idToken, user }

---

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

المسار من 3 خطوات: بدء العملية (إرسال بريد)، التحقق من صلاحية الـ Token (اختياري)، إكمال إعادة التعيين.

الخطوة 1 — بدء إعادة التعيين

POST /api/v1/auth/password-reset/initiate

{
  "email": "[email protected]"
}

الـ Response دائمًا 200 OK برسالة عامة بغض النظر عن وجود البريد:

{
  "message": "If the email exists, a password reset link has been sent"
}

صلاحية Reset Token ساعة واحدة.

تحذير

لا تخبر المستخدمين أبدًا إذا كان بريد إلكتروني مسجّلاً لديك. الـ Response العام مقصود — يمنع account enumeration attacks.

الخطوة 2 — التحقق من صلاحية الـ Token (اختياري)

استخدم هذا الـ Endpoint للتأكد من أن الـ Token صالح قبل عرض form إعادة التعيين. هذا يمنعك من عرض form لمستخدم لديه Token منتهي الصلاحية.

POST /api/v1/auth/password-reset/validate

{
  "token": "abc123def456..."
}

الـ Response — 200 OK

{
  "valid": true,
  "message": "Token is valid"
}

الخطوة 3 — إكمال إعادة التعيين

POST /api/v1/auth/password-reset/complete

{
  "token": "abc123def456...",
  "newPassword": "NewSecurePass456!"
}

الـ Response — 200 OK

{
  "message": "Password reset successfully"
}

بعد إعادة التعيين بنجاح، كل الـ Sessions النشطة للمستخدم تُلغى.

---

تغيير كلمة المرور (أثناء الـ Session)

يتيح للمستخدم المصادق تغيير كلمة مروره. يتطلب كلمة المرور الحالية كتأكيد.

POST /api/v1/auth/change-password

Header مطلوب: Authorization: Bearer <accessToken>

{
  "current_password": "SecurePass123!",
  "new_password": "NewSecurePass456!",
  "revoke_other_sessions": true
}

الحقل	النوع	مطلوب	الوصف
current_password	string	نعم	كلمة المرور الحالية
new_password	string	نعم	8 أحرف كحد أدنى
revoke_other_sessions	boolean	لا	إذا كانت true، يُسجَّل الخروج من جميع الـ Sessions الأخرى

الـ Response — 200 OK

{
  "message": "Password changed successfully"
}

---

تسجيل الخروج

POST /api/v1/auth/logout

Header مطلوب: Authorization: Bearer <accessToken>

{
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

إرسال refreshToken يلغي هذا الـ Token تحديدًا. إذا لم ترسله، يلغي السيرفر الـ Session المرتبطة بالـ Access Token.

الـ Response — 200 OK

{
  "message": "Logged out successfully"
}

---

أمثلة الكود

cURL — التسجيل

curl -X POST https://api.ithbat.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: ten_01J8X..." \
  -d '{
    "email": "[email protected]",
    "firstName": "Sara",
    "familyName": "Al-Rashidi",
    "password": "SecurePass123!"
  }'

cURL — تسجيل الدخول

curl -X POST https://api.ithbat.io/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: ten_01J8X..." \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!"
  }'

JavaScript SDK

import { IthbatSDK } from '@ithbatiam/sdk';

const ithbat = new IthbatSDK({
  tenantId: 'ten_01J8X...',
  baseUrl: 'https://api.ithbat.io',
});

// Register
const registration = await ithbat.auth.register({
  email: '[email protected]',
  firstName: 'Sara',
  familyName: 'Al-Rashidi',
  password: 'SecurePass123!',
});

// Login
const session = await ithbat.auth.login({
  email: '[email protected]',
  password: 'SecurePass123!',
});

console.log(session.accessToken);
console.log(session.user.displayName);

// Password reset
await ithbat.auth.initiatePasswordReset({ email: '[email protected]' });

// Complete reset with token from email link
await ithbat.auth.resetPassword({
  token: 'abc123...',
  newPassword: 'NewSecurePass456!',
});

---

معالجة الأخطاء

HTTP Status	Error Code	السبب
400	VALIDATION_ERROR	حقل مطلوب ناقص
400	VALIDATION_ERROR	Header X-Tenant-ID ناقص عند التسجيل
401	UNAUTHORIZED	بيانات اعتماد غير صحيحة
401	UNAUTHORIZED	البريد الإلكتروني لم يُتحقق منه بعد
403	FORBIDDEN	الحساب موقوف أو مقفل
404	NOT_FOUND	لم يُعثر على مستفيد لهذا الـ email domain
429	RATE_LIMITED	محاولات تسجيل دخول كثيرة

صيغة Error Response

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials",
    "details": null
  }
}

خطر

Endpoints تسجيل الدخول لا تفرّق بين "كلمة مرور خاطئة" و"الحساب غير موجود" في رسالة الخطأ. جميعها تُعيد Invalid credentials. هذا يمنع user enumeration.

---

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

• Token Lifecycle — فهم Access Tokens و Refresh Tokens وإدارة الـ Sessions
• MFA — إضافة عامل ثانٍ لتسجيل الدخول
• Passwordless — تسجيل دخول بدون كلمة مرور عبر Magic Link
• Social Login — تمكين تسجيل الدخول بحسابات Google و GitHub وغيرها