أساليب المصادقة

نطاق auth في SDK يغطي كل تدفق تسجيل دخول يدعمه Ithbat IAM. جميع الدوال تُعيد Promises وترمي IthbatError عند الفشل.

---

تسجيل مستخدم جديد

SDK: sdk.auth.register(params)

REST: POST /api/v1/auth/register مع Header الـ X-Tenant-ID

const result = await sdk.auth.register({
  email: '[email protected]',
  firstName: 'Jane',
  familyName: 'Doe',
  password: 'SecurePass123!',
  tenantId: 'YOUR_TENANT_ID',
});

console.log(result.id);
console.log(result.message);

Parameters:

الاسم	النوع	مطلوب	الوصف
email	string	نعم	البريد الإلكتروني للمستخدم. يجب أن يكون فريدًا داخل الـ Tenant.
password	string	نعم	يجب أن يستوفي سياسة كلمة المرور الخاصة بالـ Tenant.
tenantId	string	نعم	الـ Tenant لتسجيل المستخدم فيه.
firstName	string	لا	الاسم الأول.
familyName	string	لا	اسم العائلة.

Returns: RegisterResponse

interface RegisterResponse {
  id: string;
  email: string;
  message: string;
}

---

تسجيل الدخول بالبريد وكلمة المرور

SDK: sdk.auth.login(params)

REST: POST /api/v1/auth/login مع Header الـ X-Tenant-ID

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

if (session.accessToken) {
  sdk.setAccessToken(session.accessToken);
  console.log(session.user?.id);
}

Parameters:

الاسم	النوع	مطلوب	الوصف
email	string	نعم
password	string	نعم
rememberMe	boolean	لا	إشارة لتمديد مدة الـ Session.

Returns: LoginResponse

interface LoginResponse {
  accessToken?: string;
  refreshToken?: string;
  expiresIn?: number;
  user?: UserInfo;
  mfaRequired?: boolean;
  mfaToken?: string;
}

interface UserInfo {
  id: string;
  email: string;
  emailVerified: boolean;
  firstName?: string;
  familyName?: string;
  roles?: string[];
}

معلومة

الـ accessToken اختياري. إذا كانت MFA مفعّلة، يرجع mfaRequired: true مع mfaToken بدون Access Token.

التعامل مع MFA: إذا كانت MFA مفعّلة عند المستخدم، mfaRequired تكون true والـ accessToken / refreshToken غائبين. استخدم الـ mfaToken لإكمال MFA Challenge:

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

if (session.mfaRequired) {
  const code = await promptUserForMFACode();
  const fullSession = await sdk.auth.verifyMfa({
    mfaToken: session.mfaToken!,
    code,
  });
  sdk.setAccessToken(fullSession.accessToken);
}

---

تسجيل الخروج

SDK: sdk.auth.logout()

REST: POST /api/v1/auth/logout (يتطلب Header الـ Authorization)

يُبطل الـ Session الحالية على السيرفر.

await sdk.auth.logout();

---

تحديث الـ Access Token

SDK: sdk.auth.refreshToken()

REST: POST /api/v1/auth/refresh

يستبدل Refresh Token بـ Access Token جديد:

const tokens = await sdk.auth.refreshToken({
  refreshToken: 'rt_...',
});

sdk.setAccessToken(tokens.accessToken);

Returns: RefreshTokenResponse

interface RefreshTokenResponse {
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
}

تحذير

كل Refresh يُبطل الـ Refresh Token السابق ويصدر جديدًا. احتفظ دائمًا بأحدث Refresh Token وتخلّص من القديم فورًا.

---

جلب المستخدم الحالي

SDK: sdk.auth.me()

REST: GET /api/v1/users/me (يتطلب Header الـ Authorization)

ترجع الملف الشخصي للمستخدم المصادق حاليًا:

const me = await sdk.auth.me();
console.log(me.id, me.email, me.roles);

Returns: UserInfo

---

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

SDK: sdk.auth.resetPassword({ email })

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

يُرسل رابط إعادة تعيين كلمة المرور لبريد المستخدم. الـ Response دائمًا 200 OK بغض النظر عن وجود البريد، لمنع Email Enumeration.

await sdk.auth.resetPassword({ email: '[email protected]' });

---

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

SDK: sdk.auth.completePasswordReset({ token, newPassword })

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

المستخدم يتلقى رابطًا يحتوي على Query Parameter الـ token. مرّر هذا الـ Token وكلمة المرور الجديدة لإكمال الإعادة.

await sdk.auth.completePasswordReset({
  token: 'reset_token_from_email_link',
  newPassword: 'NewSecurePass456!',
});

---

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

SDK: sdk.auth.verifyEmail(token)

REST: POST /api/v1/auth/verify-email

بريد التحقق يحتوي على Query Parameter الـ token. مرّره لتأكيد عنوان البريد:

const params = new URLSearchParams(window.location.search);
await sdk.auth.verifyEmail(params.get('token')!);

---

إعادة إرسال بريد التحقق

SDK: sdk.auth.resendVerification(email)

REST: POST /api/v1/auth/resend-verification

await sdk.auth.resendVerification('[email protected]');

الـ Response دائمًا 200 OK بغض النظر عن وجود البريد أو كونه محققًا مسبقًا.

---

تسجيل الدخول Passwordless (Magic Link)

تسجيل الدخول Passwordless يُرسل Magic Link لمرة واحدة لبريد المستخدم. لا حاجة لكلمة مرور.

الخطوة 1 — طلب الـ Magic Link

SDK: sdk.auth.loginPasswordless({ email })

REST: POST /api/v1/auth/passwordless/start

await sdk.auth.loginPasswordless({ email: '[email protected]' });

الخطوة 2 — التحقق من الـ Token

SDK: sdk.auth.verifyPasswordless({ token })

REST: POST /api/v1/auth/passwordless/verify

المستخدم يضغط على الرابط في بريده. الرابط يحتوي على Query Parameter الـ token. مرّره لإكمال المصادقة:

const params = new URLSearchParams(window.location.search);
const session = await sdk.auth.verifyPasswordless({
  token: params.get('token')!,
});

sdk.setAccessToken(session.accessToken);

---

تسجيل الدخول الاجتماعي (OAuth / Federated)

أعد توجيه المستخدم لرابط تسجيل الدخول الاجتماعي. SDK يوفر Helper لبناء رابط الـ Redirect:

REST: GET /api/v1/auth/social/{provider}/login

const loginUrl = sdk.auth.getSocialLoginUrl({
  provider: 'google',
  redirectUri: 'https://yourapp.com/auth/callback',
});

window.location.href = loginUrl;

بعد مصادقة المستخدم مع الـ Provider، يُعاد توجيهه لـ redirectUri مع Parameter الـ code. الـ Backend يتعامل مع OAuth Callback في GET /api/v1/auth/social/{provider}/callback ويصدر الـ Tokens.

الـ Providers المدعومون يُهيّؤون لكل Tenant في الإعدادات > مزودو الهوية. استدعِ GET /api/v1/auth/social/providers لعرض الـ Providers المفعّلين:

const providers = await sdk.auth.listSocialProviders();
// [{ provider: 'google', name: 'Google', iconUrl: '...' }, ...]

---

تغيير كلمة المرور

SDK: sdk.auth.changePassword(params)

REST: POST /api/v1/auth/change-password (يتطلب مصادقة)

await sdk.auth.changePassword({
  oldPassword: 'OldPass123!',
  newPassword: 'NewPass456!',
});

Parameters:

الاسم	النوع	مطلوب	الوصف
oldPassword	string	نعم	كلمة المرور الحالية.
newPassword	string	نعم	كلمة المرور الجديدة. يجب أن تستوفي سياسة كلمة المرور الخاصة بالـ Tenant.

---

مصادقة M2M (Machine-to-Machine)

SDK: sdk.auth.clientCredentials(clientId, clientSecret, scope?)

REST: POST /oauth/token (root origin، ليس versioned path)

لعمليات الـ Server-to-Server بدون مستخدم، استخدم OAuth 2.0 Client Credentials. الـ scope الافتراضي هو 'openid':

const tokens = await sdk.auth.clientCredentials(
  process.env.ITHBAT_CLIENT_ID!,
  process.env.ITHBAT_CLIENT_SECRET!,
);

sdk.setAccessToken(tokens.access_token);

بديل: استخدم sdk.authenticate() التي تستدعي هذه الدالة وتطبّق الـ Token تلقائيًا:

await sdk.authenticate(
  process.env.ITHBAT_CLIENT_ID!,
  process.env.ITHBAT_CLIENT_SECRET!,
);

Returns: ClientCredentialsResponse

interface ClientCredentialsResponse {
  access_token: string;
  token_type: string;
  expires_in: number;
  scope?: string;
}

---

MFA (المصادقة متعددة العوامل)

إعداد MFA وإدارته يتم عبر نطاق sdk.mfa. راجع الدوال الإدارية للمرجع الكامل.

إعداد TOTP

const setup = await sdk.mfa.setup({
  method: 'totp',
  password: 'CurrentPass123!',
});

console.log(setup.qrCode);   // Render as <img> for the user to scan
console.log(setup.secret);   // Manual entry fallback

تأكيد إعداد TOTP

const result = await sdk.mfa.verifySetup({
  code: '123456',
  method: 'totp',
});

إعادة إنشاء Backup Codes

const { backupCodes } = await sdk.mfa.regenerateBackupCodes({
  password: 'CurrentPass123!',
});

تعطيل MFA

await sdk.mfa.disable({
  password: 'CurrentPass123!',
});