> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# دليل تكامل المصادقة: البنية والإطلاق إلى الإنتاج

> شرح كيفية عمل تكامل Didit للمصادقة في الإنتاج: الصفحات المستضافة أو المخصصة، تخزين الرموز، فحوص الخادم، الجلسات، التطبيقات الأصلية والإطلاق.

يشرح هذا الدليل كيف يترابط تكامل مصادقة Didit في بيئة الإنتاج، بدءاً من أول إعادة توجيه وصولاً إلى قائمة التحقق قبل الإطلاق.
ابدأ بـ[دليل البدء السريع](https://docs.didit.me/ar/authentication/quickstart.md) إذا لم تقم بعد بتسجيل دخول أي شخص، واستخدم أدلة البدء السريع الخاصة بالمنصة للاطلاع على شيفرة كل SDK.

## البنية

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

تشارك أربعة أجزاء في هذه العملية:

| الجزء | مسؤولياته |
| - | - |
| تطبيقك | بدء تسجيل الدخول، والاحتفاظ بـ PKCE verifier وقيمة `state`، وحفظ الرموز، وإرسال رمز الوصول إلى الخادم الخلفي الخاص بك. تتولى حزم SDK كل هذه المهام. |
| مصدر تسجيل الدخول الخاص بك | `https://<slug>.auth.didit.me` (أو [النطاق المخصص](https://docs.didit.me/ar/authentication/branding-and-custom-domain.md#النطاق-المخصص) الخاص بك): الصفحات المستضافة، والـ endpoint الخاص بـ token، والجلسة، والاكتشاف، ومفاتيح التوقيع. |
| الخادم الخلفي الخاص بك | التحقق من رمز الوصول في كل طلب محميٍّ، والتحقق من الجلسة قبل الإجراءات الحساسة، وتحديد ما يحق للشخص القيام به. |
| وحدة تحكم Didit وwebhooks | الإعدادات، والأشخاص وجلساتهم، وأحداث تسجيل الدخول، وwebhook `auth.*` التي يشترك فيها خادمك. |

لا يجب أن يحتوي تطبيقك أبداً على مفتاح API الخاص بـ Didit ولا على أي سر؛ فالمفتاح القابل للنشر عام، وتتم حماية تبادل الرمز عبر PKCE بدلاً من سر العميل.

## الصفحات المستضافة أو شاشاتك الخاصة

اختر المكان الذي يُدخل فيه الأشخاص بريدهم الإلكتروني أو كلمة المرور أو الرمز.
الإعداد هو `sign_in_ui` (القيمة الافتراضية `hosted`، أو `own`)، ويمكنك تغييره لاحقاً.

| | الصفحات المستضافة (موصى بها) | شاشاتك الخاصة |
| - | - | - |
| ما تبنيه | زر تسجيل دخول وصفحة الاستدعاء. | كل شاشة وكل خطوة وسيطة. |
| الطرق | جميعها، بما في ذلك الروابط السحرية وتسجيل الدخول الموحّد للشركات ومفاتيح المرور. | كلمة المرور ورمز البريد الإلكتروني ورمز الهاتف والمصادقة متعددة العوامل (MFA) وتحديات الحماية، عبر الطرق التي تعمل دون واجهة في حزم SDK. تعمل الروابط السحرية على الصفحات المستضافة فقط. |
| الخطوات التالية | تتم معالجتها نيابةً عنك: المصادقة متعددة العوامل، وتسجيل MFA، وتحديات الحماية، والتحقق عند التسجيل. | تتولى شاشاتك التعامل مع `mfa_required` و`mfa_enrollment_required` و`protection_required` و`verification_required`. راجع [طرق تسجيل الدخول](https://docs.didit.me/ar/authentication/sign-in-methods.md). |
| العلامة التجارية | شعارك وألوانك ونصوصك من [العلامة التجارية](https://docs.didit.me/ar/authentication/branding-and-custom-domain.md). | خاضعة لك بالكامل. |
| الإعداد | عناوين إعادة التوجيه. | عناوين إعادة التوجيه، بالإضافة إلى أصل الويب الخاص بك في **Allowed origins**. |

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

## اختر حزمة SDK الخاصة بك

| تطبيقك | الحزمة | مكان تخزين الرموز |
| - | - | - |
| تطبيق ويب من صفحة واحدة | [`@didit-protocol/auth`](https://docs.didit.me/ar/authentication/quickstarts/javascript) أو [`@didit-protocol/auth-react`](https://docs.didit.me/ar/authentication/quickstarts/react) | تخزين الويب أو الذاكرة في المتصفح. حافظ على سياسة أمان محتوى صارمة (Content Security Policy). |
| تطبيق ويب يُعرض من الخادم | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/ar/authentication/quickstarts/nextjs) | ملفات تعريف ارتباط HttpOnly يضبطها خادمك. الصفحة لا ترى الرموز أبدًا. |
| iOS | [`DiditAuth`](https://docs.didit.me/ar/authentication/quickstarts/ios) | Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/ar/authentication/quickstarts/android) | تخزين محمي بواسطة Android Keystore. |
| React Native أو Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/ar/authentication/quickstarts/react-native) أو [`didit_auth`](https://docs.didit.me/ar/authentication/quickstarts/flutter) | التخزين المحمي للمنصة، من خلال الوحدات الأصلية. |
| أي خادم خلفي | [حزم SDK للخادم](https://docs.didit.me/ar/integration/server-sdks/overview.md)، أو `verifyToken` من `@didit-protocol/auth/server`، أو أي مكتبة JWT | لا يوجد ما يُخزَّن: تتحقق الحزمة من الرمز الذي تستقبله. |

إذا لم تستخدم SDK، فنفّذ مسار رمز التفويض مع PKCE بنفسك. يوضح [دليل البدء السريع لـ JavaScript](https://docs.didit.me/ar/authentication/quickstarts/javascript.md#بدون-sdk) العقد الكامل.

## حماية الخادم الخلفي

يتحكم فحص الجلسة في الواجهة الأمامية فيما يُعرض فقط.
يتخذ خادمك الخلفي كل قرار استناداً إلى token الوصول الذي تم التحقق منه.

1. **تحقّق من token الوصول في كل طلب.** تحقّق من توقيع ES256 مقابل JWKS الخاص بمُصدِرك، ثم من `iss` و`aud` و`exp` و`typ: at+jwt`، وارفض token إذا كانت قيمة `act` غير `null`، إلا إذا كان المسار يقبل [وكلاء الذكاء الاصطناعي](https://docs.didit.me/ar/authentication/agent-access.md). راجع [التحقق من الرمز على خادمك](https://docs.didit.me/ar/authentication/tokens-and-jwks.md#التحقق-من-رمز-على-الخادم-لديك).
2. **تحقّق من الجلسة الفعلية قبل أي إجراء حساس.** يبقى token الوصول صالحاً حتى تنتهي مدة صلاحيته، ولا تتجاوز هذه المدة 5 دقائق. يفشل `GET /session/` فوراً إذا أُلغيت الجلسة أو أصبحت خاملة أو انتهت، أو إذا حُظر المستخدم النهائي، أو إذا لم تعد الجلسة تستوفي سياسة MFA لديك. راجع [التحقق من الجلسة](https://docs.didit.me/ar/authentication/tokens-and-jwks.md#التحقق-من-الجلسة).
3. **اطلب تحققاً إضافياً عندما يكون الإجراء محفوفاً بالمخاطر.** قبل أي دفعة صادرة أو إضافة حساب بنكي جديد أو تغيير البريد الإلكتروني أو رقم الهاتف، اسأل Didit عما إذا كان على المستخدم النهائي التحقق مجدداً. لا تتصرف إلا بناءً على تحقق إضافي بحالة `approved` قرأه خادمك الخلفي بنفسه. راجع [التحقق الإضافي قبل الإجراءات الحساسة](https://docs.didit.me/ar/authentication/verified-identity.md#خطوة-التحقق-الإضافي-قبل-الإجراءات-الحساسة).
4. **خذ `vendor_data` من token الوصول الذي تم التحقق منه، أبداً من أي حقل أرسله المتصفح**، واستخدمه في عمليات التحقق والمعاملات الخاصة بالمستخدم النهائي.

## الجلسات

| الحدث | ما الذي يحدث |
| - | - |
| تسجيل الدخول | تبدأ جلسة جديدة. تساوي مدتها القيمة المحددة في `session_lifetime` (30 يومًا افتراضيًا)، وتنتهي مبكرًا بعد مرور `idle_timeout` دون نشاط (يوم واحد افتراضيًا). |
| كل بضع دقائق | يقوم SDK بتحديث رمز الوصول، وتبلغ مدة صلاحيته 5 دقائق كحد أقصى. يتغيّر رمز التحديث باستمرار: يُستخدم كل رمز منه مرة واحدة فقط. |
| إرسال رمز تحديث سبق استخدامه | تعامل Didit ذلك على أنه سرقة وتنهي الجلسة. نفّذ عملية تحديث واحدة في كل مرة لكل جلسة. |
| تسجيل الدخول من جهاز آخر | مع `multiple_sessions: false`، تنتهي جلسات المستخدم الأخرى. |
| إعادة تعيين كلمة المرور | تنتهي كل الجلسات عند تفعيل `revoke_on_password_change` (وهو الإعداد الافتراضي). |
| تسجيل الخروج | تنهي `DELETE /session/` الجلسة، ويوجّه تطبيقك المستخدم إلى `post_logout_redirect_uri`. |
| يتدخل فريقك | تتيح وحدة التحكم إلغاء جلسة واحدة، أو تسجيل خروج المستخدم من كل مكان، أو حظره. راجع [دليل وحدة التحكم](https://docs.didit.me/ar/authentication/console.md#تسجيلات-الدخول-والجلسات). |

غيّر مدد الجلسات من **Authentication > Security and sessions**، أو عبر واجهة برمجة التطبيقات من خلال [إعدادات التطبيق](https://docs.didit.me/ar/authentication/overview.md#إعدادات-التطبيق).

![عرض جلسات تسجيل الدخول النشطة في Didit Business Console، ويسرد جلسات تسجيل الدخول مع الجهاز والموقع ووقت البدء وآخر نشاط ووقت الانتهاء وزر Revoke](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions، مع زر الإلغاء في كل جلسة.

## التطبيقات الأصلية

يعيد Didit المستخدمين إلى تطبيق أصلي عبر إعادة توجيه HTTPS فقط، ولا يقبل أي مخططات URL مخصصة.

* **iOS:** اجعل إعادة التوجيه نطاقًا مرتبطًا مع `webcredentials` في ملف `apple-app-site-association` الخاص بك.
* **Android:** اجعل إعادة التوجيه رابط تطبيق باستخدام ملف `assetlinks.json` الخاص بك.
* سجّل كل عنوان URL لإعادة التوجيه ضمن **Authentication > Security and sessions**، تمامًا كما تسجّل رابط الاستدعاء للويب.

لمفاتيح المرور في تطبيقك، سجّل التطبيقات التي تشارك مفاتيح المرور الخاصة بتطبيقك باستخدام `PUT native-apps/` عبر [واجهة برمجة تطبيقات الإدارة الخاصة بالمصادقة](https://docs.didit.me/ar/authentication/set-up-by-api.md).
يدرج Didit بعد ذلك هذه التطبيقات في ملف `apple-app-site-association` وملف `assetlinks.json` اللذين يقدّمهما على أصل تسجيل الدخول الخاص بك.
يمثل `MANAGEMENT_BASE` عنوان واجهة برمجة تطبيقات الإدارة الخاصة بتطبيقك، ويمكن لمفتاح API يملك النطاق `authentication` بصلاحية **الكتابة** إجراء هذا الاستدعاء.
يستبدل الاستدعاء القائمتين كلتيهما، لذا أرسلهما معًا:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| الحقل | القاعدة |
| - | - |
| `ios_app_ids` | حتى 10 إدخالات، كل منها Team ID الخاص بك ومعرّف الحزمة، على سبيل المثال `ABCDE12345.com.example.app`. |
| `android_apps` | حتى 10 تطبيقات، لكل منها `package_name` الخاص به و1 إلى 5 بصمات SHA-256 لشهادة توقيع التطبيق. |

توضّح أدلة البدء السريع لـ[iOS](https://docs.didit.me/ar/authentication/quickstarts/ios.md) و[Android](https://docs.didit.me/ar/authentication/quickstarts/android.md) الجانب الخاص بالتطبيق.

## ربط التحقق من الهوية ومراقبة المعاملات

لكل شخص قيمة `vendor_data` واحدة، تظهر في token الخاص به وفي جلسته.
استخدمها بوصفها `vendor_data` عند [إنشاء جلسة تحقق](https://docs.didit.me/ar/sessions-api/create-session.md) أو [إرسال معاملة](https://docs.didit.me/ar/transaction-monitoring/transactions.md)، وتعرض وحدة التحكم عمليات تسجيل الدخول وعمليات التحقق والمعاملات الخاصة بالشخص نفسه.

* للتحقق من الأشخاص عند التسجيل أو قبل الصرف مجددًا دون بناء مسار تحقق خاص بك، استخدم [الهوية المتحقق منها](https://docs.didit.me/ar/authentication/verified-identity.md).
* تصل أحداث تسجيل الدخول إلى [قواعد الأحداث](https://docs.didit.me/ar/transaction-monitoring/event-rules.md) وواجهات الاحتيال تلقائيًا. لا ترسل أحداث `auth.login` خاصة بك لعمليات تسجيل الدخول نفسها.
* لا يعني نجاح تسجيل الدخول أبدًا الموافقة على عملية تحقق أو معاملة: تعامل مع قرار كل منتج على حدة.

راجع [الحفاظ على الشخص نفسه عبر المنتجات](https://docs.didit.me/ar/authentication/overview.md#الحفاظ-على-شخص-واحد-عبر-المنتجات).

## استقبال أحداث تسجيل الدخول

اشترك في أنواع `auth.*` التي تحتاجها، مثل `auth.new_device` أو `auth.account_locked`، باستخدام [وجهة webhook](https://docs.didit.me/ar/integration/webhooks.md).
أزِل التكرار اعتمادًا على `auth_event.event_id`، وتحقّق من التوقيع كما تفعل مع كل webhook من Didit.
راجع [الأحداث وwebhook](https://docs.didit.me/ar/authentication/events-and-webhooks.md) للاطلاع على كل نوع وpayload الخاص به.

## نقل المستخدمين الحاليين

إذا كان لدى مستخدميك حسابات بالفعل على منصة هوية أخرى أو في قاعدة بياناتك الخاصة، فـ[استوردهم](https://docs.didit.me/ar/authentication/migration.md) قبل أن تبدّل تسجيل الدخول.
استورِد تجزئات كلمات المرور الخاصة بهم متى وفّرها المصدر، واحتفظ بروابط حساباتهم الاجتماعية، واحتفظ بمعرّفات المستخدمين لديك كقيم في الحقل `external_id`، الذي يصبح `vendor_data` الخاص بهم.
لا يتغيّر شيء بالنسبة إليهم حتى تبدّل تطبيقك إلى Didit.

## قائمة التحقق قبل الإطلاق

1. المصادقة مفعّلة لتطبيق Live الخاص بك في صفحة **Products**.
2. عناوين إعادة التوجيه `https://` الخاصة بالإنتاج والأصول المسموح بها مسجّلة على تطبيق Live. لا يقبل تطبيق Live أي عناوين `http://`.
3. تستخدم كل طريقة لتسجيل الدخول عبر الشبكات الاجتماعية معرّف العميل والسر الخاصين بتطبيقك: بيانات اعتماد الاختبار من Didit تعمل في البيئة التجريبية فقط.
4. تحتوي إعدادات الإنتاج لديك على مفتاح النشر الخاص ببيئة Live (`pk_live_`) والمُصدِر الخاص ببيئة Live.
5. سياسة المصادقة متعددة العوامل (MFA) ومدة الجلسة ومهلة الخمول وطول كلمة المرور وسياسة التسجيل مضبوطة وفق ما تريد. راجع [إعدادات التطبيق](https://docs.didit.me/ar/authentication/overview.md#إعدادات-التطبيق).
6. [الحماية من الروبوتات](https://docs.didit.me/ar/authentication/bot-protection.md) مفعّلة، مع فحص كلمات المرور المسرّبة.
7. يتحقق الخادم الخلفي لديك من كل token للوصول، ويستدعي `GET /session/` قبل الإجراءات الحساسة.
8. الهوية البصرية ونصوص الصفحات وروابط الشروط والخصوصية مضبوطة. إذا كنت تخطط لاستخدام [نطاق مخصص](https://docs.didit.me/ar/authentication/branding-and-custom-domain.md#النطاق-المخصص)، ففعّله قبل أن يبدأ المستخدمون بإضافة مفاتيح المرور.
9. وجهة webhook الخاصة بك مشتركة في الأنواع `auth.*` التي تتعامل معها.
10. اختبرت على تطبيق Live: التسجيل، وتسجيل الدخول للمستخدمين العائدين، والإلغاء، واستعادة كلمة المرور عند نسيانها، والمصادقة متعددة العوامل (MFA)، وانتهاء صلاحية الجلسة، وتسجيل الخروج، والجلسة المسحوبة.

## استكشاف الأخطاء وإصلاحها

| العرض | السبب والحل |
| - | - |
| تُرجع كل مسارات التشغيل `404` | المصادقة معطّلة للتطبيق، أو أن العنوان يخلط بين مصدر تجريبي ومصدر إنتاج. فعّلها من صفحة **Products**، واستخدم المصدر الذي يحدده المفتاح القابل للنشر. |
| تُرجع صفحة تسجيل الدخول `400` وتطلب منك تسجيل عنوان، أو يُرجع `POST /authorize/` الخطأ `invalid_redirect_uri` | لم يُسجَّل `redirect_uri` بالضبط كما هو: يجب أن تتطابق المخطط والمضيف والمنفذ والمسار والاستعلام حرفاً بحرف. راجع [روابط إعادة التوجيه](https://docs.didit.me/ar/authentication/overview.md#عناوين-إعادة-التوجيه). |
| يُرجع استدعاء من المتصفح إلى مصدر تسجيل الدخول الخطأ `403` مع `origin_not_allowed` | مصدر الويب الخاص بك غير موجود في **Allowed origins**. أضفه بدون مسار وبدون شرطة مائلة في النهاية. |
| يُرجع `POST /token/` الخطأ `invalid_grant` | الرمز استُخدم من قبل، أو أن عمره يتجاوز 60 ثانية، أو أُرسل مع مُتحقِّق PKCE أو `redirect_uri` مختلفين. في حالة التجديد، سبق استخدام token التجديد، وهذا يُنهي الجلسة. ابدأ تسجيل الدخول من جديد. |
| يُرجع تسجيل الدخول بكلمة المرور الخطأ `invalid_credentials` مع كلمة المرور الصحيحة | البريد الإلكتروني غير مُتحقَّق منه، أو أن الحساب مقفل أو محظور. تعطي Didit الإجابة نفسها عمداً. تحقق من الشخص في **Users**. |
| يُرجع `GET /session/` الخطأ `401` | أُلغيت الجلسة، أو خمَلت أو انتهت صلاحيتها، أو حُظر الشخص، أو استُبدل token بـ token التحديث، أو لم تعد الجلسة تستوفي سياسة MFA الخاصة بك. جدِّد الـtoken، أو أعد تسجيل دخول الشخص. |
| إضافة مفتاح مرور أو وسيلة مصادقة يُرجع `403 reauthentication_required` | يتطلب ذلك جلسة أُنشئت خلال آخر 5 دقائق. أعد تسجيل دخول الشخص أولاً. |
| يُرجع رمز الهاتف الخطأ `503 delivery_unavailable` | تعذّر تسليم الرمز. اسمح للشخص بإعادة المحاولة، أو اعرض عليه طريقة أخرى. |
| يُرجع استدعاء الخطأ `429` | تجاوزت حد المعدل. أعد المحاولة بعد المدة المذكورة في `Retry-After`. راجع [حدود المعدل](https://docs.didit.me/ar/authentication/bot-protection.md#حدود-المعدل). |
| يُرجع استدعاء الإعداد بمفتاح API الخطأ `409 product_disabled` | المصادقة معطّلة للتطبيق. يفعّلها شخص من وحدة التحكم. |
| يُرجع استدعاء الخطأ `403 plan_required` | الميزة، مثل الأدوار المخصصة أو روابط إعداد SSO للشركات، تتطلب خطة Scale أو Enterprise. تطبيقات البيئة التجريبية مفعّلة لها في أي خطة. |
| تفشل token بعد تفعيل نطاق مخصص | تغيّرت الجهة المُصدِرة والمفتاح القابل للنشر. انسخ المفتاح الجديد إلى تطبيقك، وحدّث الجهة المُصدِرة التي يتحقق منها الخادم الخلفي. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.