واجهة برمجة تطبيقات إشارة WebAuthn: تحديث وحذف مفاتيح المرور من جانب العميل

Looking for a dev-focused passkey reference? Download our Passkeys Cheat Sheet. Trusted by dev teams at Ally, Stanford CS & more.

Get Cheat Sheet

آخر تحديث: 4 نوفمبر 2025

نظرة سريعة على دعم واجهة برمجة تطبيقات إشارة WebAuthn (WebAuthn Signal API) عبر المنصات المختلفة:

⚠️ مشكلة معروفة: يحتوي Safari 26+ على خطأ حيث لا يتم حل الوعد (promise) بشكل صحيح (WebKit Bug #298951). الإصلاح بانتظار الدمج.

يتطور نظام مفاتيح المرور (Passkeys) البيئي باستمرار. لتسهيل التغيير، يتطور معيار WebAuthn الأساسي بسرعة. غالبًا ما تبدأ الميزات الجديدة بشرح تقني في GitHub ثم تتطور إلى طلب سحب (pull request) في المعيار عندما يتم مناقشتها بشكل كافٍ. مؤخرًا، تمت إضافة طلب السحب هذا إلى مسودة المعيار باسم واجهة برمجة تطبيقات إشارة WebAuthn. في هذه المقالة، سنغطي:

• لماذا نحتاج إلى واجهة برمجة تطبيقات إشارة WebAuthn: ما هي حالات الاستخدام التي تدعمها هذه الواجهة؟
• كيف تعمل واجهة برمجة تطبيقات إشارة WebAuthn: كيف تعمل بالضبط؟ وما هي التوصيات للأطراف المعتمدة (Relying Parties)؟

في وقت كتابة هذا التقرير، تم تفعيل واجهة برمجة تطبيقات إشارة WebAuthn افتراضيًا منذ إصدار Chrome 132، وكانت تُعرف سابقًا باسم Reporting API قبل إعادة تسميتها لتجنب التعارض مع واجهة برمجة تطبيقات أخرى تحمل نفس الاسم.

تعالج واجهة برمجة تطبيقات إشارة WebAuthn حالات استخدام محددة تتعلق بإدارة مفاتيح المرور (Passkeys) من جانب العميل. وتحديدًا، تساعد في الحفاظ على مزامنة المعلومات بين الطرف المعتمد (RP) و أدوات المصادقة (Authenticators) التي تُعد جزءًا من أنظمة التشغيل من جانب العميل. توجد حالات الاستخدام الهامة التالية:

Subscribe to our Passkeys Substack for the latest news.

Subscribe

عند إنشاء مفتاح مرور، فإنه يتضمن عدة أجزاء من المعلومات: user.id، user.name، و user.displayName. يتم تحديد مفتاح المرور نفسه عبر معرف الاعتماد (Credential ID) الفريد.

• user.id: هو معرف فريد يمثل الحساب الذي يرتبط به مفتاح المرور. يُعد user.id هذا أمرًا بالغ الأهمية لأنه يُستخدم للمطابقة الفعلية لمفتاح المرور مع حساب المستخدم.
• user.name و user.displayName: هي بيانات وصفية تُستخدم فقط لأغراض العرض في واجهة المستخدم.

يوضح الرسم التوضيحي التالي هيكل قاعدة بيانات بسيط ونموجي يشرح المعلومات التي يتم تخزينها عادةً داخل كل حقل:

من المهم أن نفهم أنه بينما يساعد user.name (غالبًا عنوان بريد إلكتروني) و user.displayName (اسم أكثر ودية وقابلية للقراءة) المستخدم في التعرف على حسابه في واجهة الاختيار، فإن الارتباط الحقيقي بين مفتاح المرور والحساب يتم الحفاظ عليه من خلال user.id و معرف الاعتماد (Credential ID):

• يمكن أن يحتوي الحساب على مفاتيح مرور متعددة، ولكن يتم تحديد كل مفتاح مرور بشكل فريد ومطابقته مع الحساب باستخدام user.id
• كل مفتاح مرور بحد ذاته له معرف اعتماد فريد يتم إنشاؤه بواسطة أداة المصادقة

تنشأ مشكلة عندما يتغير user.name، الذي يمكن أن يكون عنوان بريد إلكتروني. حاليًا، لا توجد آلية لتحديث هذا التغيير على أداة المصادقة من جانب العميل مباشرةً. يمكن أن يتغير user.name لأسباب مختلفة، مثل قيام المستخدم بتحديث عنوان بريده الإلكتروني. على الرغم من هذا التغيير في البيانات الوصفية للحساب من جانب الخادم، سيستمر user.name القديم في الظهور في واجهة اختيار بيانات الاعتماد، مما قد يسبب ارتباكًا للمستخدمين.

الحل البديل لهذه المشكلة هو إنشاء مفتاح مرور جديد بـ user.name المحدث ونفس user.id، ثم استبدال مفتاح المرور الموجود. ومع ذلك، فإن هذا النهج غير مريح لعدة أسباب:

1. التكرار: يمكن لأداة المصادقة تخزين مفتاح مرور واحد فقط لكل user.id لمعرف طرف معتمد محدد. هذا يعني أنه يجب استبدال مفتاح المرور القديم بآخر جديد لتحديث البيانات الوصفية، وهي خطوة إضافية.
2. تجربة المستخدم: لن يفهم المستخدمون سبب حاجتهم لإنشاء مفتاح مرور جديد. ولهذا السبب لا يُستخدم هذا الحل البديل على نطاق واسع.
3. التعقيد: إدارة إنشاء مفاتيح المرور واستبدالها لمجرد تحديث البيانات الوصفية يُعد تعقيدًا غير ضروري.

تتغير عناوين البريد الإلكتروني وأرقام الهواتف والمعرفات الأخرى بانتظام. وبدون طريقة مباشرة لتحديث user.name و user.displayName مباشرة على أداة المصادقة، قد يواجه المستخدمون مشكلة مستمرة حيث يرون ويضطرون لاختيار مفتاح مرور مرتبط بعنوان بريدهم الإلكتروني القديم. هذا الموقف يقوض التجربة السلسة التي تهدف مفاتيح المرور إلى توفيرها. تهدف واجهة برمجة تطبيقات إشارة WebAuthn إلى حل هذه المشكلة من خلال السماح للأطراف المعتمدة بالإبلاغ عن تحديثات البيانات الوصفية لمفاتيح المرور دون الحاجة إلى إنشاء مفاتيح جديدة. قبل أن نشرح كيفية تنفيذ Signal API، سنستكشف حالة الاستخدام المهمة الثانية التي تعالجها.

Become part of our Passkeys Community for updates & support.

Join

حالة استخدام حاسمة أخرى هي حذف مفاتيح المرور من أداة المصادقة من جانب العميل. بمرور الوقت، قد يقوم المستخدمون بإلغاء بيانات الاعتماد عبر قائمة إدارة مفاتيح المرور أو حذف حساباتهم، ويصبح من الضروري ضمان إزالة بيانات الاعتماد هذه من أداة المصادقة من جانب العميل لمنع ظهورها في واجهات اختيار بيانات الاعتماد المستقبلية (واجهة المستخدم الشرطية / الملء التلقائي لمفاتيح المرور).

تنشأ الحاجة لهذه الوظيفة في عدة سيناريوهات:

1. حذف مفتاح المرور عبر إعدادات الحساب: عندما تصبح بيانات الاعتماد غير صالحة، مثل بعد قيام المستخدم بحذفها صراحةً عبر إعدادات الحساب:

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

2. حذف الحساب: عندما يقوم المستخدم بحذف حسابه، يجب إزالة جميع مفاتيح المرور المرتبطة به أيضًا.

3. السياسات الأمنية: قد يكون لدى الأطراف المعتمدة سياسات أمنية تتطلب إلغاء بيانات الاعتماد بعد فترات من عدم النشاط أو بسبب مشكلات أمنية مكتشفة.

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

شاهد هذا الفيديو حول كيفية حذف مفاتيح المرور من جانب الخادم في وحدة تحكم إدارة Corbado Connect:

يتضمن تنفيذ واجهة برمجة تطبيقات إشارة WebAuthn عدة خطوات واعتبارات لضمان تكامل الوظائف بشكل صحيح وآمن. تسمح Signal API للأطراف المعتمدة (RPs) بتحديث أو حذف مفتاح المرور من أداة المصادقة من جانب العميل. يوضح هذا القسم الاعتبارات الرئيسية وخطوات التنفيذ.

عند تنفيذ واجهة برمجة تطبيقات إشارة WebAuthn، من الضروري وضع الاعتبارات التالية في الاعتبار:

• الحفاظ على الخصوصية: تم تصميم واجهة برمجة تطبيقات إشارة WebAuthn للحفاظ على خصوصية المستخدم حيث أنها أحد أسس WebAuthn. هذا يعني عدم تقديم أي ملاحظات للطرف المعتمد (RP) حول ما إذا كان التغيير المطلوب قد تمت معالجته أم لا. تعمل الواجهة بصمت لمنع أي تسرب محتمل للمعلومات حول حالة بيانات الاعتماد.

• توفر أداة المصادقة: تعتمد فعالية واجهة برمجة تطبيقات إشارة WebAuthn على توفر أداة المصادقة. ويشمل ذلك التوفر المادي ودعم البرمجيات (مثل توافق المتصفح ونظام التشغيل). يمكن للمتصفح تنفيذ الإجراءات فقط إذا كانت أداة المصادقة قابلة للوصول وتدعم العمليات اللازمة دون الحاجة إلى مصادقة بيومترية.

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

• معرف الاعتماد (Credential ID) كمفتاح: عند الإشارة إلى مفاتيح المرور، يُعد معرف الاعتماد هو المفتاح الأساسي الذي تستخدمه واجهة برمجة تطبيقات إشارة WebAuthn. يحدد هذا المعرف مفتاح المرور بشكل فريد على أداة المصادقة من جانب العميل. تسمح الواجهة للطرف المعتمد بتغيير البيانات الوصفية المرتبطة بمفاتيح المرور أو الإشارة إلى أنه لا ينبغي الوصول إلى مفاتيح مرور معينة بعد الآن، ولكن فقط من خلال معرف الاعتماد. في حال كانت أداة المصادقة لا تعرف معرف اعتماد معين، فستتجاهله بصمت.

تعتبر هذه الاعتبارات ضرورية لفهم أهم جوانب عمل واجهة برمجة تطبيقات إشارة WebAuthn بشكل صحيح.

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

تحديث البيانات الوصفية باستخدام signalCurrentUserDetails(options)

تم تصميم طريقة signalCurrentUserDetails(options) في Signal API خصيصًا لتحديث البيانات الوصفية لمفاتيح المرور. تسمح هذه الطريقة للأطراف المعتمدة بتوفير القيم الحالية لـ user.name و user.displayName.

إليك كيفية سير العملية (راجع أيضًا معيار WebAuthn Level 3).

1. هيكل الطريقة: تتضمن طريقة signalCurrentUserDetails(options) كلًا من rp.id و user.id والقيم المحدثة لـ user.name و user.displayName.

PublicKeyCredential.signalCurrentUserDetails({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    name: "New user name",
    displayName: "New display name",
});

2. تحديث البيانات الوصفية المحلية: يتم البحث عن بيانات الاعتماد المتاحة محليًا (على أداة المصادقة) والتي تتطابق مع rpId و userId. بالنسبة لجميع بيانات الاعتماد المطابقة، ستقوم أداة المصادقة بتحديث name و displayName لبيانات الاعتماد.

3. الحفاظ على الخصوصية: تم تصميم العملية لتكون حافظة للخصوصية. لا تقدم Signal API أي ملاحظات للطرف المعتمد حول ما إذا كانت التحديثات قد عولجت بنجاح، مما يمنع أي تسرب للمعلومات حول حالة بيانات الاعتماد.

4. الاتساق عبر الأجهزة: من خلال تشغيل طرق signalCurrentUserDetails(options) بانتظام، يمكن للأطراف المعتمدة التأكد من أن البيانات الوصفية لمفاتيح المرور تظل متسقة عبر الأجهزة والمنصات المختلفة التي قد يقوم المستخدم بالمصادقة عليها. يقلل هذا النهج من فرص عرض معلومات قديمة أو غير صحيحة في واجهة اختيار بيانات الاعتماد.

في لقطة الشاشة أعلاه، يمكنك رؤية كيف يشير Google Chrome إلى مثل هذا التحديث للمستخدم. تُعد واجهة برمجة تطبيقات إشارة WebAuthn جزءًا من Chrome ويمكن اختبارها باستخدام مدير كلمات مرور Google على سطح المكتب.

توفر واجهة برمجة تطبيقات إشارة WebAuthn آليات للأطراف المعتمدة (RPs) للإشارة إلى حذف مفاتيح المرور من أدوات المصادقة من جانب العميل. هذا ضروري لضمان عدم ظهور بيانات الاعتماد القديمة أو غير الصالحة في واجهة اختيار بيانات الاعتماد، وبالتالي الحفاظ على تجربة مستخدم مبسطة وآمنة. هناك طريقتان لحذف مفاتيح المرور محليًا: signalUnknownCredential(options) و signalAllAcceptedCredentials)(options). يمكن استخدام الأولى في المواقف التي لا يكون فيها المستخدم قيد تسجيل الدخول، بينما يمكن استخدام الثانية عندما يكون المستخدم قيد تسجيل الدخول. لذلك، يفضل استخدام الطريقة الثانية لأسباب تتعلق بالخصوصية.

إليك كيفية عمل الطريقتين:

1. هيكل الطريقة: تتضمن طريقة signalUnknownCredential(options) كلًا من rpId (معرف الطرف المعتمد) و credentialId (المعرف الفريد لبيانات الاعتماد المراد حذفها).

PublicKeyCredential.signalUnknownCredential({
    rpId: "example.com",
    credentialId: "aabbcc", // credential id the user just tried, base64url
});

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

3. معالجة الطريقة: عند استدعاء طريقة signalUnknownCredential(options)، تحاول أداة المصادقة من جانب العميل العثور على بيانات الاعتماد التي تتطابق مع rpId و credentialID المحدد للحذف. اعتمادًا على قدرات أداة المصادقة، تتم إزالة بيانات الاعتماد أو استخدام إجراء خاص بأداة المصادقة لإخفاء بيانات الاعتماد في عمليات المصادقة المستقبلية.

1. هيكل الطريقة: تتضمن طريقة signalAllAcceptedCredentials(options) كلًا من rpId (معرف الطرف المعتمد)، userId وقائمة بجميع معرفات الاعتماد الصالحة allAcceptedCredentialIds (قائمة بالمعرفات الفريدة لبيانات الاعتماد التي يجب الاحتفاظ بها).

PublicKeyCredential.signalAllAcceptedCredentials({
    rpId: "example.com",
    userId: "aabbcc", // user handle, base64url.
    allAcceptedCredentialIds: ["bb"],
});

2. استدعاء الطريقة: تستدعي الأطراف المعتمدة هذه الطريقة كلما اكتشفت أنه يجب حذف بيانات اعتماد وتقوم بالإشارة إلى قائمة ببيانات الاعتماد الصالحة. يجب تفضيل هذه الطريقة على signalUnknownCredential(options) لحذف بيانات الاعتماد.

3. معالجة الطريقة: عند استدعاء طريقة signalAllAcceptedCredentials(options)، تقوم أداة المصادقة من جانب العميل بمطابقة rpId و userId. ثم تبحث أداة المصادقة عن جميع بيانات الاعتماد المحلية التي تتطابق مع rpId و userId. تتم مقارنة النتيجة بـ allAcceptedCredentialIds. إذا كانت هناك بيانات اعتماد محلية غير موجودة في allAcceptedCredentialIds، فسيتم إزالة بيانات الاعتماد هذه محليًا (أو إخفاؤها حسب أداة المصادقة).

4. إلغاء إخفاء بيانات الاعتماد: إذا تم إخفاء بيانات اعتماد فقط (حسب أداة المصادقة) وأصبحت الآن جزءًا من allAcceptedCredentialIds، فستكون بيانات الاعتماد هذه موجودة في عمليات المصادقة المستقبلية مرة أخرى.

5. نصائح مفيدة:

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

في لقطة الشاشة أعلاه، يمكنك رؤية كيف يشير Google Chrome إلى عمليات الحذف. يمكن اختبار واجهة برمجة تطبيقات إشارة WebAuthn باستخدام مدير كلمات مرور Google على سطح المكتب.

لتنفيذ واجهة برمجة تطبيقات إشارة WebAuthn بفعالية وضمان مزامنة سلسة للبيانات الوصفية لمفاتيح المرور عبر أدوات المصادقة من جانب العميل، ضع التوصيات التالية في الاعتبار:

• راقب تحديثات واجهة برمجة تطبيقات إشارة WebAuthn والتنفيذ الفعلي: ابق على اطلاع بآخر التطورات والتحديثات المتعلقة بـ Signal API. تم تمكين واجهة برمجة تطبيقات إشارة WebAuthn مع Google Chrome 132، تليها متصفحات أخرى (مثل Safari الذي أعلن عن الدعم أيضًا). تحقق بانتظام من التقدم والتحديثات لضمان توافق تنفيذك مع أحدث المعايير والممارسات. سنقوم بتحديث هذه المقالة مع تطور المشهد.
• ابدأ بنهج signalAllAcceptedCredentials(options) بعد كل تسجيل دخول ناجح: يضمن هذا النهج تحديث جميع البيانات الوصفية ومعرفات الاعتماد في طريقة واحدة، مما يبسط العملية ويحافظ على الاتساق عبر الأجهزة والمنصات وفي نفس الوقت يلغي تنشيط بيانات الاعتماد المحذوفة أو القديمة.
• المراسلة الفورية باستخدام signalUnknownCredential(options) للنشر واسع النطاق: فكر في استخدام المراسلة الفورية مع طريقة signalUnknownCredential(options) في عمليات النشر واسعة النطاق أو عندما تكون هناك حاجة لتحديثات فورية. يمكن لهذه الطريقة تعزيز كفاءة ودقة إدارة بيانات الاعتماد، مما يضمن إزالة بيانات الاعتماد غير الصالحة أو القديمة فورًا من واجهة الاختيار.

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

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

• لماذا نحتاج إلى Signal API؟ تعد Signal API ضرورية لتحديث البيانات الوصفية لمفاتيح المرور وحذف مفاتيح المرور على أدوات المصادقة من جانب العميل. وهي تحل المشكلات المتعلقة بمعلومات user.name و user.displayName القديمة، والتي يمكن أن تسبب ارتباكًا عند عرض بيانات الاعتماد في واجهة الاختيار. بالإضافة إلى ذلك، تساعد في الحفاظ على واجهة اختيار بيانات اعتماد نظيفة وآمنة عن طريق إزالة مفاتيح المرور الملغاة أو المحذوفة.
• كيف تعمل Signal API؟ تعمل Signal API من خلال السماح للأطراف المعتمدة باستدعاء طرق حول الحالة الحالية لبيانات الاعتماد، بما في ذلك تحديثات البيانات الوصفية والإشارة إلى حذف مفاتيح المرور. تتم معالجة هذه التقارير بواسطة أداة المصادقة من جانب العميل، مما يضمن أن المعلومات المقدمة للمستخدمين دقيقة ومحدثة. تم تصميم الواجهة لتكون حافظة للخصوصية وتعمل دون تقديم ملاحظات للطرف المعتمد حول نجاح التحديثات.

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