انتقل إلى المحتوى الرئيسي

Passwordless Authentication

Passwordless تتيح للمستخدم تسجيل الدخول بنقرة على رابط يصله على البريد الإلكتروني. لا توجد كلمة مرور يتذكرها، ولا كلمة مرور تُسرق. Ithbat IAM يصدر Magic Link أحادي الاستخدام ومحدود المدة، وعندما يضغطه المستخدم تكتمل المصادقة وتُرجع الـ Tokens.

آلية العمل​

  1. المستخدم يدخل بريده الإلكتروني في تطبيقك.
  2. تطبيقك يرسل POST /api/v1/auth/passwordless/start.
  3. Ithbat IAM يولّد Token عشوائي مشفر، يحفظه مؤقتًا، ويرسل Magic Link على البريد.
  4. المستخدم يضغط الرابط في بريده.
  5. تطبيقك يستخرج الـ Token من الرابط ويرسل POST /api/v1/auth/passwordless/verify.
  6. Ithbat IAM يتحقق من الـ Token ويرجع Access Token و Refresh Token و ID Token.
sequenceDiagram
    participant User
    participant App as Your App
    participant Ithbat as Ithbat IAM
    participant Email as Email Service

    User->>App: Enter email address
    App->>Ithbat: POST /api/v1/auth/passwordless/start { email }
    Ithbat->>Ithbat: Generate single-use token
    Ithbat->>Email: Send magic link email
    Ithbat-->>App: 200 { message }

    App-->>User: "Check your email"
    Email-->>User: Magic link (e.g. https://app.example.com/verify?token=...)

    User->>App: Click magic link
    App->>Ithbat: POST /api/v1/auth/passwordless/verify { token }
    Ithbat->>Ithbat: Validate token (one-time, expiry check)
    Ithbat-->>App: 200 { accessToken, refreshToken, idToken, user }
    App-->>User: Signed in

بدء Passwordless Login​

POST /api/v1/auth/passwordless/start

الـ Request​

{
  "email": "[email protected]",
  "tenant_id": "ten_01J8X..."
}
الحقلالنوعمطلوبالوصف
emailstringنعمالبريد الإلكتروني للمستخدم
tenant_idstringلاUUID المستفيد. إذا ما أرسلته، يُحدّد من domain البريد

الـ Response — 200 OK​

{
  "message": "Magic link sent to your email address"
}
ملاحظة

الـ Response دائمًا 200 OK بغض النظر عن وجود البريد في النظام. هذا يمنع email enumeration.

POST /api/v1/auth/passwordless/verify

الـ Request​

{
  "token": "a1b2c3d4e5f6...",
  "tenant_id": "ten_01J8X..."
}
الحقلالنوعمطلوبالوصف
tokenstringنعمالـ Token المستخرج من Magic Link URL
tenant_idstringلاUUID المستفيد. عادةً يكون مضمّن في Magic Link URL

الـ 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",
    "familyName": "Al-Rashidi",
    "displayName": "Sara Al-Rashidi",
    "roles": ["member"],
    "permissions": ["profile:read", "profile:write"]
  }
}

الـ Magic Link في البريد يشير لـ URL في تطبيقك أنت، ليس مباشرة على Ithbat IAM API. تطبيقك يستقبل الـ Token كـ query parameter، وبعدين يرسل verify Request.

صيغة الرابط الموصى بها:

https://app.example.com/auth/magic-link?token=a1b2c3d4e5f6...

الـ handler في تطبيقك عند /auth/magic-link يستخرج الـ token parameter ويرسل verify API call.

اعتبارات أمنية​

انتهاء صلاحية الـ Token​

Magic Link Tokens أحادية الاستخدام وتنتهي صلاحيتها بعد فترة قصيرة. الـ Tokens المستهلكة أو المنتهية ترجع error. فترة الصلاحية تُهيّأ لكل مستفيد في إعدادات الأمان.

تحذير

لا تسجّل Magic Link URLs أو Tokens في الـ logs. هي بمثابة كلمات مرور لـ Session مصادقة واحدة.

الاستخدام لمرة واحدة​

كل Token يُلغى فور التحقق منه بنجاح. الضغط على الرابط مرة ثانية يرجع error. هذا يمنع replay attacks.

أمان تسليم الرابط​

  • Magic Links آمنة بقدر أمان حساب البريد الإلكتروني للمستخدم.
  • فكّر في إلزام المستخدمين ذوي الأدوار الحساسة بأسلوب أقوى (TOTP أو WebAuthn).
  • تسليم البريد يستخدم TLS أثناء النقل.

نطاق الـ Token​

Magic Link Tokens مرتبطة بالمستفيد. Token مُنشأ لمستفيد معين لا يعمل للمصادقة عند مستفيد آخر.

أمثلة الكود​

cURL — بدء Passwordless​

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

cURL — التحقق من الـ Token​

curl -X POST https://api.ithbat.io/api/v1/auth/passwordless/verify \
  -H "Content-Type: application/json" \
  -d '{
    "token": "a1b2c3d4e5f6...",
    "tenant_id": "ten_01J8X..."
  }'

JavaScript SDK​

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

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

// Step 1: Request magic link
await ithbat.auth.startPasswordless({ email: '[email protected]' });
// Show: "Check your inbox for a sign-in link"

// Step 2: Handle magic link callback in your app
// URL: https://app.example.com/auth/magic-link?token=...
const urlParams = new URLSearchParams(window.location.search);
const token = urlParams.get('token');

if (token) {
  const session = await ithbat.auth.verifyPasswordless({ token });
  console.log('Signed in as:', session.user.displayName);
  // Store session.accessToken and session.refreshToken
}

مثال React​

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

const ithbat = new IthbatSDK({ tenantId: 'ten_01J8X...' });

function PasswordlessLoginForm() {
  const [email, setEmail] = useState('');
  const [sent, setSent] = useState(false);

  const handleSubmit = async (e) => {
    e.preventDefault();
    await ithbat.auth.startPasswordless({ email });
    setSent(true);
  };

  if (sent) {
    return <p>Check your inbox — a sign-in link is on its way.</p>;
  }

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Enter your email"
        required
      />
      <button type="submit">Send Sign-in Link</button>
    </form>
  );
}

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

HTTP StatusError Codeالسبب
400VALIDATION_ERRORحقل email أو token ناقص
401UNAUTHORIZEDالـ Token غير صالح أو منتهي أو مستخدَم
403FORBIDDENحساب المستخدم موقوف
429RATE_LIMITEDRequests كثيرة لهذا البريد

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