إضافة تلميحات وطلبات المصدر ذي الصلة وتسلسل JSON لـ WebAuthn في Chrome

يقدّم الإصداران 128 و129 من Chrome ميزات جديدة ومثيرة لبروتوكول WebAuthn، وهو واجهة برمجة التطبيقات الأساسية لإنشاء أنظمة مصادقة مستندة إلى مفتاح المرور.

Eiji Kitamura

  • التلميحات: تمنح التلميحات الجهات الموثوق بها (RP) إمكانية التحكّم بشكل أفضل في واجهة مستخدم WebAuthn في المتصفّح. وهي مفيدة بشكل خاص لمستخدمي المؤسسات الذين يريدون استخدام مفاتيح الأمان.
  • طلبات المصادر ذات الصلة: باستخدام طلبات المصادر ذات الصلة، يمكن لمسؤولي الحسابات جعل مفاتيح المرور صالحة في نطاقات متعددة. إذا كنت تملك عدة مواقع إلكترونية، يمكنك الآن السماح للمستخدمين بإعادة استخدام مفتاح المرور على جميع مواقعك الإلكترونية، ما يزيل أي مشاكل في تسجيل الدخول.
  • تسلسل JSON: تتيح لك واجهات برمجة التطبيقات لتسلسل JSON تبسيط رمز الواجهة الأمامية لمسؤول المعالجة من خلال ترميز الخيارات وفك ترميزها، وكذلك بيانات الاعتماد التي يتم تمريرها إلى WebAuthn API ومنها.

تلميحات

باستخدام hints، يمكن الآن للأطراف المعتمِدة (RP) تحديد الإعدادات المفضّلة لواجهة المستخدم لإنشاء مفتاح مرور أو المصادقة باستخدام مفتاح مرور.

في السابق، عندما أراد مقدّم الخدمة (RP) تقييد معرّف الهوية الذي يمكن للمستخدم استخدامه ل إنشاء مفتاح مرور أو للمصادقة، كان بإمكانه استخدام authenticatorSelection.authenticatorAttachment لتحديد "platform" أو "cross-platform". وتقتصر المصادقة على مصادقة منصّة أو مصادقة أثناء التجول، على التوالي. باستخدام hints، يمكن أن تكون هذه المواصفات أكثر مرونة.

يمكن أن يستخدم موفِّر المحتوى hints اختياريًا في PublicKeyCredentialCreationOptions أو PublicKeyCredentialRequestOptions لتحديد "security-key" "client-device" و"hybrid" بترتيب مفضّل في صفيف.

في ما يلي مثال على طلب إنشاء بيانات اعتماد يفضّل "cross-platform" مصادقة "security-key" كاقتراح. يطلب هذا الإجراء من Chrome عرض واجهة مستخدم تركّز على مفتاح الأمان لمستخدمي المؤسسات.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: *****,
    hints: ['security-key'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});
من خلال تحديد security-key كاقتراح، يعرض المتصفّح مربّع حوار تركّز على مفتاح الأمان.
من خلال تحديد "مفتاح الأمان" كاقتراح، يعرض المتصفّح مربّع حوار تركّز على مفتاح الأمان.

عندما يريد مقدّم الخدمة منح الأولوية لسيناريو إثبات الهوية على جميع الأجهزة، يمكنه إرسال طلب مصادقة يفضّل "cross-platform" مصادقة مع "hybrid" كإشارة.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: *****,
    residentKey: true,
    hints: ['hybrid']
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});
من خلال تحديد "متعدّد الأجهزة" كاقتراح، يعرض المتصفّح مربّع حوار يركّز على تسجيل الدخول على جميع الأجهزة.
من خلال تحديد "متعدّد الأجهزة" كاقتراح، يعرض المتصفّح مربّع حوار يركّز على تسجيل الدخول على جميع الأجهزة.

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

يجب أن تحدِّد جميع طلبات WebAuthn رقم تعريف الطرف الموثوق به (رقم تعريف RP)، وتكون جميع مفاتيح المرور مرتبطة برقم تعريف RP واحد. في العادة، لا يمكن للمصدر تحديد سوى معرّف طرف موثوق استنادًا إلى نطاقه، لذا في هذه الحالة، يمكن أن يحدّد www.example.co.uk معرّف الطرف الموثوق example.co.uk، ولكن ليس example.com. باستخدام طلبات Related Origin Requests، يمكن التحقّق من رقم تعريف موفِّر الموارد الذي تمّت المطالبة به من خلال جلب ملف JSON معروف جيدًا يقع على العنوان /.well-known/webauthn من النطاق المستهدَف. وبالتالي، يمكن أن يستخدم كلّ من example.co.uk (وexample.in وexample.de وما إلى ذلك) رقم تعريف موفّر المحتوى التالي: example.com إذا حدّده example.com بالشكل التالي:

عنوان URL: https://example.com/.well-known/webauthn

{
  "origins": [
    "https://example.co.uk",
    "https://example.de",
    "https://example.sg",
    "https://example.net",
    "https://exampledelivery.com",
    "https://exampledelivery.co.uk",
    "https://exampledelivery.de",
    "https://exampledelivery.sg",
    "https://myexamplerewards.com",
    "https://examplecars.com"
  ]
}

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

تسلسل JSON

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

يوفّر WebAuthn الآن واجهات برمجة تطبيقات لتحليل كائنات طلب WebAuthn PublicKeyCredentialCreationOptions و PublicKeyCredentialRequestOptions من تنسيق JSON مباشرةً، وتسلسل استجابة PublicKeyCredential إلى تنسيق JSON مباشرةً. يتم تلقائيًا تحويل كل الحقول التي تحتوي على قيمة ArrayBuffer والتي تحمل بيانات ثنائية خامة من قيمها المشفَّرة باستخدام Base64URL أو إليها. تتوفّر واجهات برمجة التطبيقات هذه اعتبارًا من الإصدار 129 من Chrome.

قبل إنشاء مفتاح مرور، احصل على عنصر PublicKeyCredentialCreationOptions بترميز JSON من الخادم وفك ترميزه باستخدام PublicKeyCredential.parseCreationOptionsFromJSON().

Browser Support

  • Chrome: 129.
  • Edge: 129.
  • Firefox: 119.
  • Safari: 18.4.

Source

export async function registerCredential() {

  // Fetch encoded `PublicKeyCredentialCreationOptions`
  // and JSON decode it.
  const options = await fetch('/auth/registerRequest').json();

  // Decode `PublicKeyCredentialCreationOptions` JSON object
  const decodedOptions = PublicKeyCredential.parseCreationOptionsFromJSON(options);  

  // Invoke the WebAuthn create() function.
  const cred = await navigator.credentials.create({
    publicKey: decodedOptions,
  });
  ...

بعد إنشاء مفتاح مرور، يمكنك ترميز بيانات الاعتماد الناتجة باستخدام toJSON() لكي تتمكّن من إرسالها إلى الخادم.

Browser Support

  • Chrome: 129.
  • Edge: 129.
  • Firefox: 119.
  • Safari: 18.4.

Source

  ...
  const cred = await navigator.credentials.create({
    publicKey: options,
  });

  // Encode the credential to JSON and stringify
  const credential = JSON.stringify(cred.toJSON());

  // Send the encoded credential to the server
  await fetch('/auth/registerResponse', credential);
  ...

قبل المصادقة باستخدام مفتاح مرور، يمكنك جلب PublicKeyRequestCreationOptions بترميز JSON من الخادم وفك ترميزه باستخدام PublicKeyCredential.parseRequestOptionsFromJSON().

Browser Support

  • Chrome: 129.
  • Edge: 129.
  • Firefox: 119.
  • Safari: 18.4.

Source

export async function authenticate() {

  // Fetch encoded `PublicKeyCredentialRequestOptions`
  // and JSON decode it.
  const options = await fetch('/auth/signinRequest').json();

  // Decode `PublicKeyCredentialRequestOptions` JSON object
  const decodedOptions = PublicKeyCredential.parseRequestOptionsFromJSON(options);

  // Invoke the WebAuthn get() function.
  const cred = await navigator.credentials.get({
    publicKey: options
  });
  ...

بعد المصادقة باستخدام مفتاح مرور، يجب ترميز بيانات الاعتماد الناتجة باستخدام طريقة toJSON() حتى يمكن إرسالها إلى الخادم.

Browser Support

  • Chrome: 129.
  • Edge: 129.
  • Firefox: 119.
  • Safari: 18.4.

Source

  ...
  const cred = await navigator.credentials.get({
    publicKey: options
  });

  // Encode the credential to JSON and stringify
  const credential = JSON.stringify(cred.toJSON());

  // Send the encoded credential to the server
  await fetch(`/auth/signinResponse`, credential);
  ...

مزيد من المعلومات

لمزيد من المعلومات حول WebAuthn ومفاتيح المرور، يُرجى الاطّلاع على المراجع التالية: