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

# تسجيل الدخول الأصلي في ديسكتوب (RFC 8252)

> كيف يسجّل تطبيق مبيان ديسكتوب الدخول إلى بوابة محمية عبر متصفح النظام وPKCE، بلا متصفح مدمج ولا ملفات تعريف ارتباط للجلسة

عندما يتصل تطبيق مبيان ديسكتوب بـ**بوابة محمية** (لوحة مستضافة أو ذاتية الاستضافة تقف خلف مزوّد OAuth) فهو يستطيع تسجيل الدخول بطريقتين:

1. **تسجيل الدخول الأصلي (RFC 8252)**: يفتح التطبيق **متصفح النظام الحقيقي**، وتوافق أنت داخل المتصفح الذي تثق به أصلاً، ثم يستلم التطبيق رموزاً يحفظها كملفات يقرؤها مالك الحساب فقط داخل مجلد بيانات المستخدم (ويمكن تشفيرها بسلسلة مفاتيح نظام التشغيل من الإعدادات ← البوابة). **بلا متصفح مدمج وبلا ملفات تعريف ارتباط للجلسة.** هذه هي الطريقة الافتراضية متى ما دعمتها البوابة.
2. **تسجيل الدخول المدمج (بديل قديم)**: يفتح التطبيق نافذة متصفح صغيرة داخله ويلتقط ملف تعريف ارتباط جلسة البوابة. يُستخدم تلقائياً عندما تكون البوابة بإصدار أقدم لا يعلن دعم التسجيل الأصلي.

أنت لا تختار بين الطريقتين؛ يكتشف التطبيق ما تدعمه البوابة ويختار الأفضل. توضح هذه الصفحة ما يحدث ولماذا.

## لماذا التسجيل الأصلي

تضمين متصفح داخل تطبيق أصلي لإتمام OAuth له سلبيات معروفة: صفحة الدخول لا ترى جلسة متصفحك الحالية فتعيد كتابة بياناتك وتكرر التحقق بخطوتين، ومديرو كلمات المرور ومفاتيح المرور (passkeys) غالباً لا تعمل، ويعتمد التطبيق على قراءة ملف تعريف ارتباط من متصفح مدمج خاص. أما RFC 8252 («OAuth 2.0 للتطبيقات الأصلية») فهو أفضل ممارسة في الصناعة لتجنب ذلك كله: **تتم المصادقة في متصفح النظام ثم يُسلَّم التطبيق رموزه الخاصة.**

وبالنسبة لمبيان تحديداً يعني التسجيل الأصلي:

* **لا متصفح مدمج.** تتم المصادقة في Safari أو Chrome أو Firefox أو Edge، أياً كان ما تستخدمه، مع حساباتك وإضافاتك ومفاتيح المرور كما هي.
* **لا ملفات تعريف ارتباط للجلسة.** يحتفظ التطبيق بـ**رمز وصول** OAuth (قصير العمر) و**رمز تحديث**، محفوظين كملفات لا يقرؤها غير المالك، ومشفّرين أثناء التخزين عبر سلسلة مفاتيح النظام (Electron `safeStorage`) عند تفعيل خيار سلسلة المفاتيح في الإعدادات ← البوابة. وتُوثَّق طلبات REST وتذاكر WebSocket بترويسة `Authorization: Bearer` وليس بملفات تعريف ارتباط.

## كيف يعمل

```
Desktop app                Gateway (/auth/native/*)          Identity provider (IDP)
   │ 1. open loopback 127.0.0.1:<random port>
   │ 2. system browser ─►  /auth/native/authorize
   │    (PKCE challenge)    (starts the normal PKCE login) ─► /oauth/authorize
   │                        ◄──── code ──── /auth/callback ◄──┘
   │                        3. mint one-time gateway code
   │ ◄─ 302 127.0.0.1/cb?code=… ─┘
   │ 4. POST /auth/native/token (code + PKCE verifier)
   │ ◄─ 5. { access_token, refresh_token, expires_at } ───────┘
   │ 6. store in local token store; use Bearer for REST + WS tickets
```

تعمل البوابة **وسيطاً** في هذا المسار: فهي خادم التفويض *بالنسبة لتطبيق ديسكتوب*، وعميل OAuth *بالنسبة لمزوّد الهوية في الأعلى*. هذا ضروري لأن `client_id` الخاص بالمزوّد وعناوين إعادة التوجيه المسموحة مرتبطة بأصل البوابة نفسها، فلا يستطيع تطبيق سطح المكتب أن يكون عميلاً مباشراً للمزوّد. ومع ذلك يحصل ديسكتوب على تجربة RFC 8252 كاملة: زوج PKCE خاص به، وإعادة توجيه loopback خاصة به، ورموز يملكها.

يحمي **PKCE (RFC 7636)** قفزة loopback: رمز البوابة ذو الاستخدام الواحد لا قيمة له بدون مُحقِّق الرمز (code verifier) الذي لا يغادر التطبيق أبداً. والرمز لمرة واحدة وقصير العمر.

## اكتشاف القدرات والبديل

يقرأ ديسكتوب نقطة النهاية العامة `/api/status` في البوابة، والتي تعلن مصفوفة `auth_flows`:

| قيمة `auth_flows` | المعنى |
| - | - |
| `["cookie", "native_pkce"]` | البوابة تدعم التسجيل الأصلي ← يستخدمه التطبيق |
| `["cookie"]` | البوابة تدعم المسار القديم فقط ← يستخدم التطبيق المتصفح المدمج |
| *(الحقل غير موجود)* | بوابة أقدم ← يستخدم التطبيق المتصفح المدمج |

إذا أُعلن التسجيل الأصلي لكنه فشل لسبب محلي، مثل أن تحجب أداة أمان مستمع loopback أو أن تغلق تبويب المتصفح، **يرجع التطبيق تلقائياً إلى المسار المدمج** لتتمكن من تسجيل الدخول على أي حال.

## دورة حياة الرموز

* **رمز الوصول**: قصير العمر (دقائق). يُرسل بترويسة `Authorization: Bearer` مع كل طلب REST وعند إصدار تذكرة WebSocket.
* **رمز التحديث**: أطول عمراً ويتجدد بالتدوير. عندما يقترب رمز الوصول من الانتهاء يستدعي التطبيق `/auth/native/refresh` لتدوير الرمزين ثم يحدّث مخزن الرموز.
* **الانتهاء النهائي**: إذا انتهى رمز التحديث (منتهي الصلاحية أو أُلغي أو اكتُشف إعادة استخدامه) يمسح التطبيق رموزه المخزّنة ويطلب تسجيل دخول جديداً.
* **تسجيل الخروج**: يمسح الرموز الأصلية المخزّنة وأي ملف تعريف ارتباط قديم لتلك البوابة.

## لمشغّلي البوابات

يتوفر التسجيل الأصلي تلقائياً على أي بوابة محمية فيها مزوّد جلسات تفاعلي مسجَّل. لا حاجة لأي إعداد: مسارات `/auth/native/*` وإعلان `auth_flows` جزء من نظام مصادقة اللوحة. مزوّدو OAuth يتوسطون إعادة التوجيه إلى مزوّد الهوية في الأعلى، أما مزوّدو كلمات المرور (مثل إضافة **basic-auth** المضمّنة) فيُنزلون متصفح النظام على نموذج بيانات الاعتماد `/login` في البوابة، وهذا ما يتيح لمديري كلمات المرور في النظام (مثل Passwords في macOS) تعبئة النموذج تلقائياً، وهو ما لا يقدر عليه أي متصفح مدمج. أما بيانات الاعتماد المعتمدة على رمز فقط (مثل drain) فليست تسجيل دخول تفاعلياً ولا تعلن `native_pkce`.

نقاط النهاية ذات الصلة (كلها عامة وتعمل قبل المصادقة، مثل مسارات `/auth/*` الحالية الخاصة بـOAuth):

* `GET /auth/native/authorize` يبدأ تسجيل PKCE بالوساطة
* `POST /auth/native/token` يبدّل رمز loopback والمُحقِّق برموز
* `POST /auth/native/refresh` يدوّر الرموز انطلاقاً من رمز التحديث لدى التطبيق

## انظر أيضاً

* [OAuth عبر SSH والأجهزة البعيدة](/desktop/guides/oauth-over-ssh): نمط callback على loopback لتسجيل OAuth الخاص بالمزوّدين وخوادم MCP على أجهزة بعيدة.
* [الاتصال بخلفية بعيدة](/ar/desktop/user-guide/multi-connection-desktop)


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