تحديثات FedCM: واجهة برمجة تطبيقات حالة تسجيل الدخول لموفِّر الهوية وتلميح تسجيل الدخول والمزيد

يتضمّن الإصدار 116 من Chrome إمكانات FedCM، مثل Login Hint API وUser Info API وRP Context API، ويبدأ تجربة المصدر لواجهة IdP Sign-In Status API.

في الإصدار 116 من Chrome، سيتم طرح الميزات الثلاث الجديدة التالية في إدارة بيانات الاعتماد الموحّدة (FedCM):

بالإضافة إلى ذلك، سيطلق Chrome تجربة أصل IdP Sign-In Status API. إنّ واجهة برمجة التطبيقات IdP Sign-in Status API هي شرط أساسي، وستكون تغييرًا غير متوافق مع الإصدارات السابقة عند طرحها. إذا كان لديك تطبيق حالي لواجهة FedCM، احرص على المشاركة في التجربة الأصلية.

Login Hint API

عند تفعيل FedCM، يعرض المتصفّح الحساب الذي تم تسجيل الدخول إليه من موفِّر الهوية المحدّد. عندما تتيح خدمة IdP حسابات متعددة، فإنّها تدرج جميع الحسابات التي تم تسجيل الدخول إليها.

مربّع حوار FedCM يعرض حسابات مستخدمين متعدّدة
مربع حوار FedCM يعرض عدة حسابات مستخدمين

بعد تسجيل دخول المستخدم، يطلب منه الطرف المعتمد (RP) أحيانًا إعادة المصادقة. ولكن قد لا يكون المستخدم متأكدًا من الحساب الذي كان يستخدمه. إذا كان بإمكان الجهة المعتمدة تحديد الحساب الذي سيتم تسجيل الدخول إليه، سيسهّل ذلك على المستخدم اختيار حساب. سيتم طرح تلميح تسجيل الدخول في الإصدار 116 من Chrome، وبفضله، يمكن لموقع RP حصر القائمة في خيار واحد.

تضيف هذه الإضافة مجموعة من login_hints في استجابة accounts list endpoint من موفر الهوية، مع جميع أنواع الفلاتر الممكنة التي يتيحها موفر الهوية. على سبيل المثال، يمكن أن يبدو ردّ الحسابات على النحو التالي عندما يتيح موفّر الهوية إمكانية الفلترة حسب البريد الإلكتروني والمعرّف:

{
  "accounts": [{
    "id": "demo1",
    "email": "demo1@example.com",
    "name": "John Doe",
    "login_hints": ["demo1", "demo1@example.com"],
    ...
  }, {
    "id": "demo2",
    "email": "demo2@example.com",
    "name": "Jane Doe",
    "login_hints": ["demo2", "demo2@example.com"],
    ...
  }, ...]
}

من خلال تمرير login_hints في قائمة الحسابات، يمكن لجهة الاعتماد استدعاء navigator.credentials.get() مع السمة loginHint كما هو موضّح في نموذج الرمز التالي لعرض الحساب المحدّد بشكل انتقائي:

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

User Info API

أصبحت أزرار تسجيل الدخول التي تحمل شعار موفِّر الهوية وتتيح للمستخدمين تسجيل الدخول باستخدام ميزة "اتحاد الهوية" شائعة الآن. ومع ذلك، فإنّ تزيين الزر باستخدام رمز الملف الشخصي للمستخدم ومعلوماته يسهّل عملية تسجيل الدخول، خاصةً إذا سبق للمستخدم الاشتراك في هذا الموقع الإلكتروني باستخدام موفّر خدمة تحديد الهوية.

زر "تسجيل الدخول باستخدام حساب Google"
زر "تسجيل الدخول باستخدام حساب Google"
زر مخصّص لميزة "تسجيل الدخول باستخدام حساب Google"
زر "تسجيل الدخول باستخدام حساب Google" المخصّص

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

توفّر واجهة برمجة التطبيقات User Info API، التي سيتم طرحها في الإصدار 116 من Chrome، طريقة لموفّر خدمة تحديد الهوية للحصول على معلومات المستخدم العائد من الخادم بدون الاعتماد على ملفات تعريف الارتباط التابعة لجهات خارجية.

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

  • سبق للمستخدم تسجيل الدخول إلى الطرف المعتمَد باستخدام موفِّر الهوية من خلال FedCM على مثيل المتصفّح نفسه ولم تتم محو البيانات.
  • سجَّل المستخدم الدخول إلى موفِّر الهوية على مثيل المتصفّح نفسه.
// Iframe displaying a page from the https://idp.example origin
const user_info = await IdentityProvider.getUserInfo({
    configUrl: "https://idp.example/fedcm.json",
    clientId: "client1234"
});

// IdentityProvider.getUserInfo returns an array of user information.
if (user_info.length > 0) {
  // Chrome puts returning accounts first, so the first account received is guaranteed to be a returning account.
  const name = user_info[0].name;
  const given_name = user_info[0].given_name;
  const display_name = given_name ? given_name : name;
  const picture = user_info[0].picture;
  const email = user_info[0].email;
  // Renders the personalized sign-in button with the information above.
}

يُرجى العِلم أنّه للسماح باستدعاء IdentityProvider.getUserInfo() من داخل إطار iframe له المصدر نفسه الذي يستخدمه موفّر خدمة تحديد الهوية، يجب أن يسمح رمز HTML المضمّن بذلك بشكل صريح باستخدام identity-credentials-get سياسة الأذونات.

<iframe src="https://fedcm-demo-idp.dev" allow="identity-credentials-get"></iframe>

يمكنك الاطّلاع على كيفية عملها على https://fedcm-demo-rp.dev/active-mode.

RP Context API

تتيح واجهة برمجة التطبيقات RP Context API، التي سيتم طرحها في الإصدار 116 من Chrome، لمزوّد الهوية تعديل السلسلة في واجهة المستخدم لمربّع حوار FedCM، ما يتيح استيعاب سياقات المصادقة المحدّدة مسبقًا. اطّلِع على لقطات الشاشة التالية لمعرفة الخيارات المختلفة:

تم عرض مربّع حوار FedCM مع الرسالة &quot;تسجيل الدخول إلى ****&quot;.
يتم عرض مربّع حوار FedCM مع الرسالة "تسجيل الدخول إلى ****". هذا هو الخيار التلقائي في حال عدم تحديد RP Context.
تم عرض مربّع حوار FedCM باستخدام
عرض مربّع حوار FedCM مع "الاشتراك في ****"
تم عرض مربّع حوار FedCM باستخدام
تم عرض مربّع حوار FedCM مع "متابعة إلى ****"
عرض مربّع حوار FedCM مع الرسالة &quot;استخدام ****&quot;
عرض مربّع حوار FedCM مع "استخدام ****"

طريقة الاستخدام بسيطة، ما عليك سوى تقديم السمة identity.context مع إحدى القيم التالية: "signin" (القيمة التلقائية) أو "signup" أو "use" أو "continue".

const credential = await navigator.credentials.get({
  identity: {
    // "signin" is the default, "signup", "use" and "continue" 
    // can also be used
    context: "signup", 
    providers: [{
      configURL: "https://idp.example/fedcm.json",
      clientId: "1234",
    }],
  }
});

مرحلة التجربة والتقييم لواجهة IdP Sign-In Status API

يبدأ Chrome تجربة IdP Sign-In Status API على الكمبيوتر المكتبي من الإصدار 116 من Chrome، ثم على Chrome لنظام Android لاحقًا. تتيح لك مراحل التجربة والتقييم استخدام ميزة جديدة أو تجريبية لإنشاء وظائف يمكن للمستخدمين تجربتها لفترة محدودة قبل إتاحة الميزة للجميع.

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

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

يمكن لموفّري الهوية إرسال إشارة إلى المتصفّح بشأن حالة تسجيل الدخول الخاصة بالمستخدم عن طريق إرسال عنوان HTTP أو عن طريق طلب بيانات من واجهة برمجة تطبيقات JavaScript، وذلك عندما يكون المستخدم مسجّلاً الدخول إلى موفّر الهوية أو عندما يكون مسجّلاً الخروج من جميع حساباته على موفّر الهوية. يسجّل المتصفّح الحالة على أنّها إحدى الحالات التالية: "تسجيل الدخول" أو "تسجيل الخروج" أو "غير معروف" (تلقائي).

للإشارة إلى أنّ المستخدم قد سجّل الدخول، أرسِل عنوان IdP-SignIn-Status: action=signin HTTP في عملية تنقّل عالية المستوى أو طلب مورد فرعي من المصدر نفسه:

IdP-SignIn-Status: action=signin

بدلاً من ذلك، يمكنك استدعاء JavaScript API IdentityProvider.login() من مصدر IdP:

IdentityProvider.login()

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

للإشارة إلى أنّ المستخدم قد سجّل خروجه من جميع حساباته، أرسِل عنوان HTTP IdP-SignIn-Status: action=signout-all في عملية تنقّل على مستوى أعلى أو طلب مورد فرعي من المصدر نفسه:

IdP-SignIn-Status: action=signout-all

بدلاً من ذلك، يمكنك استدعاء JavaScript API IdentityProvider.logout() من مصدر IdP:

IdentityProvider.logout()

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

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

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

ماذا يحدث إذا انتهت صلاحية جلسة المستخدم؟ السماح للمستخدم بتسجيل الدخول من خلال مسار تسجيل دخول ديناميكي

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

سيعرض مربّع حوار FedCM رسالة، كما هو موضّح في الصورة التالية:

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

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

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

يمكن تحديد عنوان URL لصفحة تسجيل الدخول (الذي يجب أن يكون مصدر موفِّر الهوية) باستخدام signin_url كجزء من ملف إعدادات موفِّر الهوية.

{
  "accounts_endpoint": "/auth/accounts",
  "client_metadata_endpoint": "/auth/metadata",
  "id_assertion_endpoint": "/auth/idtokens",
  "signin_url": "/signin"
  }
}

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

  • أرسِل العنوان IdP-SignIn-Status: action=signin أو استدعِ واجهة برمجة التطبيقات IdentityProvider.login() لإعلام المتصفّح بأنّه تم تسجيل دخول المستخدم.
  • يتم إغلاق النافذة المنبثقة تلقائيًا عند استدعاء IdentityProvider.close().
// User is signed in...
// Don't forget feature detection.
if (IdentityProvider) {
  // Signal to the browser that the user has signed in.
  IdentityProvider.close();
}
يسجّل المستخدم الدخول إلى الطرف المعتمَد بعد تسجيل الدخول إلى موفِّر الهوية باستخدام FedCM

يمكنك تجربة سلوك IdP Sign-In Status API في العرض التوضيحي. تنتهي صلاحية الجلسة بعد ثلاث دقائق من تسجيل الدخول إلى موفِّر الهوية التجريبي. بعد ذلك، يمكنك مراقبة عملية تسجيل الدخول إلى موفِّر الهوية من خلال سلوك النافذة المنبثقة.

المشاركة في التجربة الأصلية

يمكنك تجربة IdP Sign-In Status API محليًا من خلال تفعيل إحدى العلامات
chrome://flags#fedcm-idp-signin-status-api في Chrome
الإصدار 116 أو الإصدارات الأحدث.

يمكنك أيضًا تفعيل واجهة برمجة التطبيقات IdP Sign-In Status API من خلال تسجيل تجربة أصل مرتين:

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

تتوفّر مرحلة التجربة والتقييم لواجهة برمجة التطبيقات IdP Sign-In Status API من الإصدار 116 إلى الإصدار 119 من Chrome.

تسجيل تجربة أصلية لموفّر خدمة تحديد الهوية

  1. انتقِل إلى صفحة التسجيل في التجربة الأصلية.
  2. انقر على الزر تسجيل واملأ النموذج لطلب رمز مميز.
  3. أدخِل نقطة انطلاق موفّر خدمة تحديد الهوية على أنّها نقطة انطلاق الويب.
  4. انقر على إرسال.
  5. أضِف علامة origin-trial <meta> إلى رأس الصفحات التي تستخدم IdentityProvider.close(). على سبيل المثال، قد يبدو ذلك على النحو التالي:
    <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">.

تسجيل تجربة أصل تابعة لجهة خارجية في RP

  1. انتقِل إلى صفحة التسجيل في التجربة الأصلية.
  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 بالرمز المميز الخاص بك.

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

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

الصورة من Dan Cristian Pădureț على Unsplash