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

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

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

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

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

تضمين متصفح داخل تطبيق أصلي لإتمام 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 والأجهزة البعيدة: نمط callback على loopback لتسجيل OAuth الخاص بالمزوّدين وخوادم MCP على أجهزة بعيدة.
الاتصال بخلفية بعيدة

تطبيق ديسكتوب

البداية

استخدام مبيان

الميزات

منصات المراسلة

التكاملات

الأدلة والدروس

دليل المطوّر

المرجع

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

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

كيف يعمل

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

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

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

انظر أيضاً

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

​كيف يعمل

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

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

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

​انظر أيضاً

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

كيف يعمل

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

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

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

انظر أيضاً