تعديلات من خلال FedCM: مرحلة التجربة والتقييم في Button Mode API وCORS وSameSite

Eiji Kitamura

اعتبارًا من الإصدار 125 من Chrome، ستبدأ Button Mode API مرحلة تجربة وتقييم على أجهزة الكمبيوتر المكتبي. باستخدام واجهة برمجة التطبيقات Button Mode API، يمكن لموفّري الهوية استخدام واجهة برمجة التطبيقات FedCM API حتى إذا لم يكن لدى المستخدمين جلسات نشطة لموفّر الهوية عند طلب البيانات من واجهة برمجة التطبيقات. ويمكن للمستخدمين بعد ذلك تسجيل الدخول إلى موقع إلكتروني باستخدام حسابهم المُوحَّد بدون توجيههم إلى موقع موفِّر الهوية. إنّ واجهة مستخدم FedCM في وضع الزر أكثر بروزًا مقارنةً بواجهة المستخدم في مسار التطبيق المصغّر الحالي، لأنّها مقيّدة بحركة مستخدِم ويعكس ذلك بشكل أفضل نية المستخدِم لتسجيل الدخول.

Button Mode API

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

في وضع التطبيقات المصغّرة، يتم عرض مربّع حوار في أعلى يسار الشاشة على متصفّح Chrome لأجهزة الكمبيوتر المكتبي بدون تنشيط المستخدم.

تضيف واجهة برمجة التطبيقات الجديدة Button Mode API وضع واجهة مستخدم جديدًا يُسمى وضع الزر. على عكس وضع التطبيقات المصغّرة، لا يُقصد تفعيل وضع الزرّ فور وصول المستخدِم إلى النقطة المرجعية. بدلاً من ذلك، يُفترض أن يتمّ استدعاؤه عندما يبدأ المستخدم عملية تسجيل دخول، مثل الضغط على الزر "تسجيل الدخول باستخدام موفِّر الهوية".

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

في واجهة مستخدم وضع الأزرار، يكون مربّع حوار تسجيل الدخول المعروض أكبر مقارنةً بوضع التطبيقات المصغّرة، ويجب أن يكون رمز العلامة التجارية كذلك للحفاظ على الاتساق المرئي. في حين أنّ الحد الأدنى لحجم الرمز في وضع التطبيق المصغّر هو 25×25 بكسل، فإنّ الحد الأدنى لحجم الرمز في وضع الزر هو 40×40 بكسل. يسمح ملف العميل المعروف لموفِّر الهوية (IdP) بتحديد عناوين URL متعددة للرمز على النحو التالي:

{
  // ... Other settings (like endpoints) here
  "branding": {
    "icons": [
      {
        "url": "https://size-25px-image",
        "size": 25,
      },
      {
        "url": "https://size-40px-image",
        "size": 40
      }
    ]
  }
}

في وضع الأزرار، يتم عرض مربّع حوار مشروط في أعلى وسط شاشة Chrome على الكمبيوتر المكتبي، مع رمز أكبر.

يمكنك تجربته بنفسك باستخدام الإصدار 125 من Chrome على الرابط https://fedcm-rp-demo.glitch.me/button_flow.

يستخدم أحد المستخدمين واجهة برمجة التطبيقات Button Mode API لتسجيل الدخول إلى تطبيق الربط.

لاستخدام Button Mode API:

• فعِّل الميزة التجريبية FedCmButtonMode في chrome://flags.
• احرص على استدعاء واجهة برمجة التطبيقات التي تُجري تفعيلًا عابرًا للمستخدم، مثل النقر على زر.
• استخدِم مَعلمة mode لاستدعاء واجهة برمجة التطبيقات على النحو التالي:

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: "https://idp.example/config.json",
        clientId: "123",
        nonce:"456",
      }],
      mode: "button"
    }
  });

ملاحظة: لا يتيح Chrome استخدام "button" إلا في موقع mode الجديد في الوقت الحالي. ستتم إضافة علامات أخرى، مثل "widget"، عندما يطرح Chrome هذه الميزة.

سيُرسِل المتصفّح مَعلمة جديدة إلى نقطة نهاية mode=button لإثبات الهوية التي تمثّل نوع الطلب من خلال تضمين mode=button:

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=Ct60bD&disclosure_text_shown=true&is_auto_selected=false&mode=button

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

ملاحظة: يمكن للمستخدمين إيقاف وضع تطبيق مصغّر FedCM في إعدادات Chrome. لا يؤثر ذلك في Button Mode API لأنّ طلب تسجيل الدخول يبدأ من خلال لفتة المستخدِم، ومن المفترض أن يساعد المتصفّح المستخدِمين في إكمال عملية تسجيل الدخول.

رصد الميزات

لتحديد ما إذا كان المتصفّح مؤهّلاً لاستخدام وضع الزر، يمكنك فحصه باستخدام الرمز البرمجي التالي:

let supportsFedCmMode = false;
try {
  navigator.credentials.get({
    identity: Object.defineProperty(
      {}, 'mode', {
        get: function () { supportsFedCmMode = true; }
      }
    )
  });
} catch(e) {}

if (supportsFedCmMode) {
  // The button mode is supported.
}

استخدام خيار حساب آخر

يمكن أن يسمح مقدّم خدمات الربط للمستخدمين "باستخدام حسابات أخرى" في أداة اختيار الحسابات، مثلاً، عندما تتيح خدمات إدارة الهوية حسابات متعددة أو استبدال الحساب الحالي.

لتفعيل خيار استخدام حساب آخر:

• فعِّل الميزة التجريبية FedCmUseOtherAccount في chrome://flags أو سجِّل في التجربة التجريبية لواجهة برمجة التطبيقات Button Mode API.
• يحدِّد موفِّر الهوية ما يلي في ملف إعدادات موفِّر الهوية:

{
  "accounts_endpoint" : ...,
  "modes: {
    "button": {
      "supports_use_other_account": true,
    }
  }
}

المشاركة في الفترة التجريبية لإصدار التطبيق الأصلي

يمكنك تجربة واجهة برمجة التطبيقات Button Mode API على الجهاز من خلال تفعيل علامة Chrome chrome://flags#fedcm-button-mode على الإصدار 125 من Chrome أو الإصدارات الأحدث.

يمكن لموفّري خدمات المصادقة أيضًا تفعيل "وضع الأزرار" من خلال تسجيل فترة تجريبية للمصدر:

• سجِّل تجربة مصدر خارجي للمطوّر.

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

تتوفّر مرحلة التجربة والتقييم لواجهة برمجة التطبيقات Button Mode API من الإصدار 125 من Chrome وحتى الإصدار 130.

1. انتقِل إلى صفحة تسجيل الفترة التجريبية في Origin.
2. انقر على الزر تسجيل واملأ النموذج لطلب رمز مميّز.
3. أدخِل مصدر موفِّر خدمة المصادقة على أنّه مصدر الويب.
4. تحقَّق من مطابقة الجهات الخارجية لإدراج الرمز المميّز باستخدام JavaScript في موارد أخرى.
5. انقر على إرسال.
6. تضمين الرمز المميّز الصادر على موقع إلكتروني تابع لجهة خارجية

لتضمين الرمز المميّز على موقع إلكتروني تابع لجهة خارجية، أضِف الرمز التالي إلى مكتبة JavaScript أو حِزمة تطوير البرامج (SDK) لمزوّد خدمة تعريف الهوية التي يتم عرضها من مصدر مزوّد خدمة تعريف الهوية.

const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';
document.head.appendChild(tokenElement);

استبدِل TOKEN_GOES_HERE برمزك المميّز.

ملاحظة: إذا كان موفِّر المحتوى هو الذي يستدعي FedCM API وليس النص البرمجي الذي يتم تحميله من موفِّر الهوية، يجب أن يسجِّل موفِّر المحتوى مصدره بنفسه وأن يُجري اختباره للمصدر التابع للجهة الأولى.

سيُطلب استخدام سياسة مشاركة الموارد المشتركة المنشأ (CORS) وSameSite=None في الإصدار 125 من Chrome

CORS

سيفرض Chrome استخدام بروتوكول CORS على نقطة نهاية تأكيد هوية العميل بدءًا من الإصدار 125 من Chrome.

مشاركة الموارد المتعددة المصادر (CORS) هي نظام يتألف من إرسال عناوين HTTP، ويحدِّد ما إذا كانت المتصفّحات تحظر رمز JavaScript في الواجهة الأمامية من الوصول إلى الردود لطلبات المصادر المتعددة. يجب أن تستجيب نقطة نهاية تأكيد الهوية على خادم موفّر الهوية للطلب باستخدام عناوين إضافية. في ما يلي مثال على عنوان استجابة لطلب من https://fedcm-rp-demo.glitch.me:

Access-Control-Allow-Origin: https://fedcm-rp-demo.glitch.me
Access-Control-Allow-Credentials: true

ملاحظة: بما أنّه تم ضبط Access-Control-Allow-Credentials على true، يجب أن يعرض Access-Control-Allow-Origin نطاقًا بشكل صريح ولا يمكنه استخدام علامة wildcard التي يشير إليها *.

SameSite=None

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

في FedCM، يرسل Chrome ملفات تعريف الارتباط إلى نقطة نهاية الحسابات، نقطة نهاية بيان الهوية ونقطة نهاية إيقاف. اعتبارًا من Chrome 125، سيرسل Chrome هذه الطلبات التي تتضمّن بيانات الاعتماد باستخدام ملفات تعريف الارتباط المصنَّفة صراحةً على أنّها SameSite=None فقط.