تعديلات FedCM: واجهة برمجة التطبيقات الخاصة بحالة تسجيل الدخول وواجهة برمجة التطبيقات لخطأ وواجهة برمجة تطبيقات الإبلاغ التلقائية المحددة

يشحن Chrome 120 Login Status API لخدمة FedCM. تسمح واجهة برمجة تطبيقات حالة تسجيل الدخول (المعروفة سابقًا باسم IdP Sign-in Status API) للمواقع الإلكترونية، خصوصًا موفِّري الهوية، بإرسال إشارة إلى المتصفِّح عندما يسجّل المستخدمون الدخول والخروج. ويستخدم برنامج FedCM هذه الإشارة لمعالجة مشكلة هجوم التوقيت الصامت، وبالتالي، يسمح للأداة FedCM بالعمل بدون ملفات تعريف الارتباط التابعة لجهة خارجية. يعالج هذا التعديل آخر التغييرات المتبقية غير المتوافقة مع الأنظمة القديمة والتي حدّدناها سابقًا في النية الأصلية للشحن من قِبل FedCM، كجزء من نطاق عملنا.

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

بالإضافة إلى ذلك، يشحن Chrome ميزتَي إدارة بيانات الاعتماد الفيدراليّة (FedCM) الجديدتَين:

  • Error API: إشعار المستخدمين عند تعذّر محاولة تسجيل الدخول باستخدام واجهة مستخدم أصلية استنادًا إلى استجابة الخادم من نقطة نهاية تأكيد المعرّف، إن وجدت.
  • Auto-Selected Flag API: إرسال إشعار إلى موفّر الهوية والطرف المعتمد (RP) في حال تم اختيار بيانات اعتماد تلقائيًا في المسار.

واجهة برمجة التطبيقات لحالة تسجيل الدخول

واجهة برمجة تطبيقات حالة تسجيل الدخول هي آلية يُعلِم فيها الموقع الإلكتروني، خاصةً موفِّر الهوية، المتصفِّح بحالة تسجيل دخول المستخدم على موفِّر الهوية (IdP). باستخدام واجهة برمجة التطبيقات هذه، يمكن للمتصفّح تقليل الطلبات غير الضرورية إلى موفِّر الهوية والحدّ من هجمات التوقيت المحتملة.

إبلاغ المتصفّح بحالة تسجيل دخول المستخدم

يمكن لموفِّر الهوية إرسال إشارة إلى المتصفِّح بحالة تسجيل دخول المستخدم من خلال إرسال عنوان HTTP أو من خلال استدعاء واجهة برمجة تطبيقات JavaScript عند تسجيل المستخدم الدخول في موفِّر الهوية أو عند تسجيل خروج المستخدم من جميع حسابات موفِّر الهوية. بالنسبة إلى كل موفِّر هوية (IdP) (يتم تحديده من خلال عنوان URL للإعدادات الخاص به)، يحتفظ المتصفّح بمتغير الحالة الثلاثية الذي يمثّل حالة تسجيل الدخول مع القيم المحتملة logged-in وlogged-out وunknown. الحالة التلقائية هي unknown.

للإشارة إلى أنّ المستخدم قد سجّل الدخول، أرسِل عنوان HTTP يتضمّن العنصر Set-Login: logged-in في شريط التنقّل على المستوى الأعلى أو في طلب مورد فرعي من المصدر نفسه:

Set-Login: logged-in

يمكنك بدلاً من ذلك استدعاء واجهة برمجة تطبيقات JavaScript navigator.login.setStatus('logged-in') من مصدر IdP:

navigator.login.setStatus('logged-in');

تسجِّل هذه المكالمات حالة تسجيل دخول المستخدم على أنّها logged-in. عند ضبط حالة تسجيل دخول المستخدم على logged-in، يُجري الجهة المحظورة التي تطلب خدمة FedCM طلبات إلى نقطة نهاية قائمة حسابات موفِّر الهوية ويعرض الحسابات المتاحة للمستخدم في مربّع حوار FedCM.

للإشارة إلى تسجيل خروج المستخدم من جميع حساباته، أرسِل عنوان HTTP يتضمّن العنصر Set-Login: logged-out في التنقّل على المستوى الأعلى أو طلب مورد فرعي من المصدر نفسه:

Set-Login: logged-out

ويمكنك بدلاً من ذلك استدعاء واجهة برمجة تطبيقات JavaScript navigator.login.setStatus('logged-out') من أصل IdP:

navigator.login.setStatus('logged-out');

تسجِّل هذه المكالمات حالة تسجيل دخول المستخدم على أنّها logged-out. عندما تكون حالة تسجيل دخول المستخدم هي logged-out، يتعذّر الاتصال بـ FedCM بدون إرسال طلب إلى نقطة نهاية قائمة حسابات موفِّر الهوية.

يتم ضبط الحالة unknown قبل أن يرسل موفِّر الهوية إشارة باستخدام واجهة برمجة التطبيقات لحالة تسجيل الدخول. لقد قدّمنا هذه الحالة لتحسين عملية النقل، لأنّه يُحتمل أن يكون المستخدم قد سجّل الدخول من قبل إلى موفِّر الهوية عند شحن واجهة برمجة التطبيقات هذه. قد لا تُتاح الفرصة لموفِّر الهوية (IdP) لإرسال إشارة إلى ذلك إلى المتصفِّح عند استدعاء FedCM لأول مرة. وفي هذه الحالة، نقدِّم طلبًا إلى نقطة نهاية قائمة حسابات موفِّر الهوية ونعدِّل الحالة استنادًا إلى الاستجابة من نقطة نهاية قائمة الحسابات:

  • إذا عرضت نقطة النهاية قائمة بالحسابات النشطة، عدِّل الحالة إلى logged-in وافتح مربّع حوار FedCM لعرض هذه الحسابات.
  • إذا لم تعرض نقطة النهاية أي حسابات، يمكنك تعديل الحالة إلى logged-out بدون تعذُّر تنفيذ طلب FedCM.

ماذا لو انتهت صلاحية جلسة المستخدم؟ دع المستخدم يسجِّل الدخول من خلال تدفق تسجيل دخول ديناميكي!

وعلى الرغم من أن موفِّر الهوية يُعلِم المتصفِّح بحالة تسجيل دخول المستخدم باستمرار، قد تكون الحالة غير متزامنة، مثل انتهاء صلاحية الجلسة. يحاول المتصفّح إرسال طلب معتمَد إلى نقطة نهاية قائمة الحسابات عندما تكون حالة تسجيل الدخول هي logged-in، ولكن لا يعرض الخادم أي حسابات لأنّ الجلسة لم تعُد متوفّرة. في هذا السيناريو، يمكن للمتصفِّح السماح للمستخدم بتسجيل الدخول إلى موفِّر الهوية ديناميكيًا من خلال نافذة مربّع حوار.

يعرض مربع حوار FedCM رسالة تقترح تسجيل الدخول، كما هو موضّح في الصورة التالية.

مربّع حوار في برنامج FedCM يقترح تسجيل الدخول إلى موفِّر الهوية.
مربّع حوار لبرنامج FedCM يقترح تسجيل الدخول إلى موفِّر الهوية.

عندما ينقر المستخدم على الزر متابعة، يفتح المتصفِّح مربّع حوار لصفحة تسجيل الدخول إلى موفِّر الهوية.

مثال لمربّع حوار
مثال لمربّع حوار يظهر بعد النقر على تسجيل الدخول إلى زر موفِّر الهوية.

يتم تحديد عنوان URL لصفحة تسجيل الدخول مع login_url كجزء من ملف إعداد موفِّر الهوية.

{
  "accounts_endpoint": "/auth/accounts",
  "client_metadata_endpoint": "/auth/metadata",
  "id_assertion_endpoint": "/auth/idtokens",
  "login_url": "/login"
  }
}

مربع الحوار هو نافذة متصفح عادية تحتوي على ملفات تعريف الارتباط للطرف الأول. أيًا كان ما يحدث داخل مربّع الحوار، يعود إلى موفِّر الهوية، ولا تتوفّر أي معرِّفات نوافذ لتقديم طلب اتصال من مصادر متعددة إلى صفحة الجهة المحظورة. بعد تسجيل دخول المستخدم، ينبغي لموفِّر الهوية إجراء ما يلي:

  • أرسِل عنوان Set-Login: logged-in أو استدعِ واجهة برمجة التطبيقات navigator.login.setStatus("logged-in") لإبلاغ المتصفّح بأنّ المستخدم سجّل الدخول.
  • يمكنك الاتصال بـ IdentityProvider.close() لإغلاق مربع الحوار.
يسجِّل أحد المستخدمين الدخول إلى جهة محظورة بعد تسجيل الدخول إلى موفِّر الهوية باستخدام برنامج FedCM.
يسجّل أحد المستخدمين الدخول إلى جهة محظورة بعد تسجيل الدخول إلى موفِّر الهوية باستخدام برنامج FedCM.

يمكنك تجربة سلوك Login Status API في عرضنا التوضيحي.

  1. انقر على الزر الانتقال إلى موفِّر الهوية وتسجيل الدخول.
  2. سجِّل الدخول باستخدام حساب عشوائي.
  3. اختر انتهت الجلسة من القائمة المنسدلة حالة الحساب.
  4. اضغط على زر تعديل المعلومات الشخصية.
  5. انقر على الزر الانتقال إلى الجهة المحظورة لتجربة بروتوكول FedCM.

من المفترض أن تتمكّن من مراقبة عملية تسجيل الدخول إلى موفِّر الهوية من خلال سلوك الوحدة.

واجهة برمجة التطبيقات للخطأ

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

من خلال Error API، يُرسِل Chrome إشعارًا إلى المستخدم عن طريق عرض واجهة مستخدم أصلية تتضمّن معلومات الخطأ التي يوفّرها موفِّر الهوية.

مربّع حوار في برنامج FedCM يعرض رسالة الخطأ بعد تعذُّر محاولة تسجيل دخول المستخدم. ترتبط السلسلة بنوع الخطأ.
مربع حوار في FedCM يعرض رسالة الخطأ بعد تعذُّر محاولة تسجيل دخول المستخدم. ترتبط السلسلة بنوع الخطأ.

واجهة برمجة تطبيقات HTTP لـ IdP

في استجابة id_assertion_endpoint، يمكن لموفِّر الهوية عرض رمز مميّز إلى المتصفِّح في حال كان من الممكن إصداره عند الطلب. في هذا الاقتراح، في حال تعذُّر إصدار رمز مميّز، يمكن لموفِّر الهوية عرض استجابة "خطأ"، والتي تتضمّن حقلَين اختياريَين جديدَين:

  1. code
  2. url
// id_assertion_endpoint response
{
  "error": {
     "code": "access_denied",
     "url": "https://idp.example/error?type=access_denied"
  }
}

بالنسبة إلى الرموز، يمكن لموفِّر الهوية اختيار أحد الأخطاء المعروفة من قائمة أخطاء OAuth 2.0 المحدَّدة [invalid_request وunauthorized_client وaccess_denied وserver_error وtemporarily_unavailable] أو استخدام أي سلسلة عشوائية. إذا كان الخيار الثاني هو Chrome، سيعرض Chrome واجهة المستخدم الخاصة بالأخطاء، مع رسالة خطأ عامة، ويمرر الرمز إلى الجهة المحظورة.

وبالنسبة إلى url، تحدّد الأداة صفحة ويب يمكن للإنسان فهمها وتحتوي على معلومات عن الخطأ، وذلك بهدف توفير معلومات إضافية للمستخدمين حول الخطأ. هذا الحقل مفيد للمستخدمين لأن المتصفحات لا يمكنها تقديم رسائل خطأ منسّقة في واجهة مستخدم أصلية. على سبيل المثال، روابط للخطوات التالية ومعلومات الاتصال بخدمة العملاء وما إلى ذلك. إذا أراد المستخدم الاطّلاع على مزيد من المعلومات حول تفاصيل الخطأ وكيفية إصلاحه، يمكنه الانتقال إلى الصفحة المقدّمة من واجهة المستخدم في المتصفّح للاطّلاع على مزيد من التفاصيل. يجب أن يكون عنوان URL للموقع الإلكتروني نفسه الخاص بموفِّر الهوية configURL.

try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: 'https://idp.example/manifest.json',
          clientId: '1234',
        },
      ],
    }
  });
} catch (e) {
  const code = e.code;
  const url = e.url;
}

واجهة برمجة التطبيقات للإعلانات المحدّدة تلقائيًا

mediation: optional هو سلوك توسّط المستخدم التلقائي في واجهة برمجة تطبيقات إدارة بيانات الاعتماد، ويُشغِّل إعادة المصادقة التلقائية متى أمكن. ومع ذلك، قد تكون ميزة إعادة المصادقة التلقائية غير متاحة لأسباب لا يعرفها أحد سوى المتصفّح. وفي حال عدم توفّر هذه الميزة، قد يُطلب من المستخدم تسجيل الدخول باستخدام توسّط صريح للمستخدم، وهو مسار يتضمّن خصائص مختلفة.

  • من منظور المتصل في واجهة برمجة التطبيقات، عندما يتلقّى رمزًا مميّزًا للمعرّف، لا تتوفّر له إمكانية معرفة ما إذا كان ذلك نتيجة عملية إعادة المصادقة التلقائية. وهذا ما يصعّب عليهم تقييم أداء واجهة برمجة التطبيقات وتحسين تجربة المستخدم وفقًا لذلك.
  • ومن منظور موفِّر الهوية، يتعذّر عليه أيضًا معرفة ما إذا كانت إعادة المصادقة التلقائية قد حدثت أم لا لتقييم الأداء. بالإضافة إلى ذلك، ما إذا كان قد تم استخدام توسّط صريح للمستخدم قد يساعد المستخدمين في توفير المزيد من الميزات المرتبطة بالأمان. على سبيل المثال، قد يفضل بعض المستخدمين مستوى أمان أعلى يتطلب توسط المستخدم صراحةً في المصادقة. في حال تلقّى موفِّر الهوية طلب رمز مميّز بدون هذا التوسّط، يمكنه معالجة الطلب بشكل مختلف. على سبيل المثال، يمكنك عرض رمز خطأ ليتمكّن الجهة المحظورة من استدعاء واجهة برمجة تطبيقات FedCM مرة أخرى باستخدام mediation: required.

لهذا السبب، قد يستفيد المطوّرون من إمكانية الاطّلاع على خطوات إعادة المصادقة التلقائية.

من خلال واجهة برمجة التطبيقات لميزة Flag API التي تم اختيارها تلقائيًا، يشارك Chrome ما إذا كان قد تم الحصول على إذن صريح من المستخدم من خلال النقر على زر متابعة باسم مع كل من موفِّر الهوية والجهة المحظورة، عند حدوث إعادة المصادقة التلقائية أو حدوث توسّط صريح. لا تحدث المشاركة إلا بعد منح إذن المستخدم للتواصل مع موفِّر الهوية (IdP) / الجهة المحظورة.

المشاركة مع موفِّر الهوية

لمشاركة المعلومات مع إذن المستخدم لنشر موفّر الهوية، يُدرج Chrome is_auto_selected=true في طلب POST الذي تم إرساله إلى id_assertion_endpoint:

POST /fedcm_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

account_id=123&client_id=client1234&nonce=Ct0D&disclosure_text_shown=true&is_auto_selected=true

مشاركة الجهة المحظورة

يمكن للمتصفِّح مشاركة المعلومات إلى الجهة المحظورة في isAutoSelected من خلال IdentityCredential:

const cred = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://idp.example/manifest.json',
      clientId: '1234'
    }]
  }
});

if (cred.isAutoSelected !== undefined) {
  const isAutoSelected = cred.isAutoSelected;
}

التفاعل مع الملاحظات ومشاركتها

إذا كانت لديك ملاحظات أو واجهت أي مشاكل أثناء الاختبار، يمكنك مشاركتها على crbug.com.

صورة فتاة ترتدي قبعة حمراء على قناة Unsplash