مفاتيح المرور في التطبيقات الأصلية: التنفيذ الأصلي مقابل WebView

الورقة البيضاء للمؤسسات حول Passkeys. إرشادات عملية وأنماط إطلاق ومؤشرات KPI لبرامج passkeys.

احصل على الورقة البيضاء

ملاحظة: غالباً ما يتم الجمع بين System و Embedded WebView حيث يتولى System WebView تسجيل الدخول (مع المشاركة التلقائية لبيانات الاعتماد)، ثم يعرض Embedded WebView إدارة مفاتيح المرور في الإعدادات.

عوامل القرار الرئيسية:

• تسجيل دخول قائم على OAuth؟ ← System WebView (ASWebAuthenticationSession، Chrome Custom Tabs)
• تريد إعادة استخدام مصادقة الويب في واجهة أصلية؟ ← Embedded WebView (WKWebView، Android WebView مع WebKit 1.12.1+)
• بناء تطبيق أصلي أولاً؟ ← التنفيذ الأصلي (Apple AuthenticationServices، Google Credential Manager)

توفر منصات الأجهزة المحمولة الحديثة ثلاثة أساليب متميزة لدمج مفاتيح المرور في تطبيقك الأصلي، ولكل منها مقايضات مختلفة لتجربة المستخدم والتعقيد الفني وتوافق OAuth:

1. التنفيذ الأصلي (Native Implementation): قم ببناء تدفقات مفتاح المرور مباشرة في تطبيقك باستخدام واجهات برمجة تطبيقات النظام الأساسي (iOS AuthenticationServices، Android Credential Manager). يوفر أفضل تجربة مستخدم مع مصادقة بيومترية سلسة، ولكنه يتطلب جهداً تقنياً متوسطاً إلى عالياً للتنفيذ.

2. System WebView: استخدم مكون متصفح المنصة (iOS ASWebAuthenticationSession / SFSafariViewController، Android Chrome Custom Tabs) للتعامل مع المصادقة. ممتاز لتدفقات تسجيل الدخول المستندة إلى OAuth ويشارك بيانات الاعتماد مع متصفح النظام.

3. Embedded WebView: قم بتضمين طريقة عرض ويب قابلة للتخصيص (iOS WKWebView، Android WebView) داخل تطبيقك لإعادة استخدام مصادقة الويب مع هيكل تطبيق أصلي. يوفر مظهراً يشبه الأصلي بدون أشرطة عناوين URL وتحكماً كاملاً في واجهة مستخدم عرض الويب. يتطلب إعداداً إضافياً بما في ذلك الأذونات والاستحقاقات (iOS)، وتكوين WebView مع AndroidX WebKit 1.12.1+ (Android) لتمكين وظيفة مفتاح المرور.

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

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

متى تختار التنفيذ الأصلي:

• بناء تطبيق أصلي جديد أو إعادة هيكلة المصادقة إلى الشاشات الأصلية
• تريد أفضل تجربة مستخدم ممكنة مع مصادقة فورية وصامتة
• مطالبات تلقائية بمفتاح المرور عند بدء تشغيل التطبيق: يمكن للتطبيقات الأصلية استخدام preferImmediatelyAvailableCredentials لـ عرض تراكب مفتاح المرور تلقائياً عند توفر مفاتيح المرور، مما يوفر أسرع تجربة تسجيل دخول دون الحاجة إلى إدخال معرف
• تحتاج إلى تحكم كامل في واجهة المستخدم وتدفق المصادقة
• على استعداد للاستثمار في التنفيذ الخاص بالمنصة (iOS Swift، Android Kotlin)

الميزة الرئيسية: preferImmediatelyAvailableCredentials()

يمكن لتطبيقات التنفيذ الأصلي الاستفادة من preferImmediatelyAvailableCredentials() لإنشاء تراكب مفتاح مرور تلقائي يظهر فور بدء تشغيل التطبيق عندما تتوفر مفاتيح المرور. يوفر هذا التدفق الخالي من اسم المستخدم أسرع تجربة تسجيل دخول ممكنة - يرى المستخدمون مفاتيح المرور الخاصة بهم على الفور دون إدخال معرف أولاً. هذه الإمكانية حصرية للتطبيقات الأصلية وغير متوفرة في متغيرات WebView.

يوضح المخطط أدناه كيف توفر المصادقة الأصلية رحلة مستخدم أسرع مقارنة بنهج Conditional UI في WebView:

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

نظرة عامة على المتطلبات الفنية:

يتطلب تكامل مفتاح المرور الأصلي ثقة التشفير بين تطبيقك ومجال الويب الخاص بك. بدونها، سيرفض نظام التشغيل جميع عمليات WebAuthn. المتطلبات الرئيسية:

1. ملفات ارتباط مجال التطبيق المستضافة في /.well-known/
2. معرف Relying Party الصحيح المطابق لمجال الويب الخاص بك
3. الإمكانات الخاصة بالمنصة (مفصلة في القسم 4)

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

يتضمن تنفيذ مفاتيح المرور محلياً على iOS إطار عمل AuthenticationServices من Apple، والذي يوفر واجهة برمجة تطبيقات لعمليات WebAuthn:

المكونات الرئيسية:

• ASAuthorizationController: يدير تدفق المصادقة
• ASAuthorizationPlatformPublicKeyCredentialProvider: ينشئ طلبات مفتاح المرور
• ثلاثة أوضاع متميزة لواجهة المستخدم للتعامل مع تسجيلات الدخول بمفتاح المرور:
  • تسجيل الدخول عبر حقل نصي: حقل اسم المستخدم التقليدي حيث يبدأ تسجيل الدخول بمفتاح المرور عند إرسال الزر
  • تراكب مفتاح المرور الشرطي: مربع حوار نظام التشغيل يسرد مفاتيح المرور المتاحة
  • Conditional UI: اقتراحات مفتاح المرور في شريط QuickType أعلى لوحة المفاتيح

نصائح التطوير

• التخزين المؤقت لـ AASA: تقوم Apple بتخزين ملف AASA مؤقتاً بقوة (تصل إلى 24 ساعة)، مما قد يحبط الاختبار. الحل: قم بتمكين وضع المطور (Developer Mode) على جهاز الاختبار الخاص بك وألحق ?mode=developer بعنوان URL الخاص بـ AASA لفرض جلب جديد
• اختبار الأداء: اختبر بحسابات iCloud تحتوي على مئات من بيانات الاعتماد لملاحظة زمن الوصول في العالم الحقيقي. قد يظهر تراكب النظام تأخيراً طفيفاً مع وجود العديد من مفاتيح المرور المخزنة

يستخدم التنفيذ الأصلي لمفتاح المرور في Android واجهة برمجة تطبيقات Credential Manager (أو واجهة برمجة تطبيقات FIDO2 الأقدم للتوافق مع الإصدارات السابقة):

المكونات الرئيسية:

• CredentialManager: واجهة برمجة التطبيقات المركزية لجميع عمليات بيانات الاعتماد
• CreatePublicKeyCredentialRequest: لتسجيل مفتاح المرور
• GetCredentialRequest: لمصادقة مفتاح المرور
• وضعان رئيسيان لواجهة المستخدم:
  • تسجيل الدخول عبر حقل نصي: حقل اسم المستخدم التقليدي حيث يبدأ تسجيل الدخول بمفتاح المرور عند إرسال الزر
  • تراكب مفتاح المرور الشرطي: مربع حوار نظام التشغيل يسرد مفاتيح المرور المتاحة

ملاحظة: يفتقر Android حالياً إلى اقتراحات لوحة المفاتيح Conditional UI الخاصة بـ iOS في التطبيقات الأصلية (على الرغم من أن Conditional UI يعمل في تطبيقات الويب)

يواجه تنفيذ مفاتيح المرور أصلياً تحديات ودروساً مستفادة مهمة: يمكن أن يؤدي التكامل على مستوى نظام التشغيل إلى ظهور مشكلات عبر أجهزة وإصدارات مختلفة من نظام التشغيل.

1. على سبيل المثال، واجه فريقنا مشكلات مثل التخزين المؤقت القوي لـ Apple لملف apple-app-site-association (المستخدم لربط بيانات اعتماد التطبيق/الويب) والاختلافات الدقيقة في واجهة المستخدم في مطالبات المقاييس الحيوية لبعض مصنعي الأجهزة الأصلية (OEM) في Android.
2. علاوة على ذلك، ضع في اعتبارك أنه في بعض سيناريوهات المؤسسات، قد يتم تعطيل مزامنة مفتاح المرور في الأجهزة المُدارة بواسطة السياسة. في بيئات الشركات حيث يتم إيقاف تشغيل مزامنة iCloud Keychain أو Google Password Manager، تصبح مفاتيح المرور مرتبطة بالجهاز ولن تتجول - وهو سيناريو مهم يجب التخطيط له (على سبيل المثال، ضمان قدرة المستخدمين على الاستمرار في تسجيل الدخول إذا حصلوا على هاتف جديد).
3. بالإضافة إلى ذلك، يمكن لتطبيقات إدارة بيانات الاعتماد التابعة لجهات خارجية التأثير على التدفق. على سبيل المثال، إذا كان لدى المستخدم مدير كلمات مرور مثل 1Password تم تعيينه كموفر نشط لبيانات الاعتماد، فسيقوم غالباً باعتراض إنشاء مفتاح المرور وتخزينه، مع أخذ الأولوية على مدير بيانات الاعتماد الأصلي للمنصة.

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

التوصية: بالنسبة للتطبيقات الأصلية، نوصي باستخدام حزم SDK الخاصة بـ Corbado (iOS Swift Passkey SDK، Android Kotlin Passkey SDK) والتي تتعامل مع العديد من الحالات الطرفية المكتشفة من خلال عمليات النشر الإنتاجية، وتوفر قياساً عن بعد إضافياً واختباراً.

Igor Gjorgjioski

Head of Digital Channels & Platform Enablement, VicRoads

We hit 80% mobile passkey activation across 5M+ users without replacing our IDP.

See how VicRoads scaled passkeys to 5M+ users — alongside their existing IDP.

Read the case study

تستخدم System WebViews مكون المتصفح الأصلي للمنصة للتعامل مع المصادقة داخل تطبيقك. على عكس التطبيقات الأصلية بالكامل، تعرض System WebViews محتوى الويب باستخدام متصفح النظام الفعلي (Safari على iOS، Chrome على Android)، مع الحفاظ على ملفات تعريف الارتباط المشتركة وبيانات الاعتماد المحفوظة ومؤشرات أمان المتصفح المألوفة.

متى تختار System WebView:

• يستخدم تطبيقك تسجيل الدخول المستند إلى OAuth: يعد System WebView النهج الموصى به لتدفقات OAuth2/OIDC، مما يوفر مصادقة آمنة
• مصادقة مستندة إلى الويب موجودة تريد إعادة استخدامها في تطبيقات الأجهزة المحمولة
• تحتاج إلى دعم طرق مصادقة متعددة (كلمات المرور، تسجيل الدخول الاجتماعي، مفاتيح المرور) دون إعادة البناء أصلياً
• تريد الحفاظ على قاعدة تعليمات برمجية واحدة للمصادقة عبر الويب والأجهزة المحمولة

المزايا الرئيسية:

• توافق OAuth: مصمم خصيصاً لتدفقات المصادقة OAuth/OIDC
• مؤشرات الأمان: يرى المستخدمون عنوان URL الفعلي وشهادات SSL، مما يبني الثقة
• جهد تنفيذ منخفض: مطلوب حد أدنى من التعليمات البرمجية الأصلية
• تجربة مستخدم متسقة: واجهة متصفح مألوفة يثق بها المستخدمون بالفعل

مكونات المنصة:

• iOS: ASWebAuthenticationSession (موصى به لتدفقات المصادقة) أو SFSafariViewController (للتصفح العام)
• Android: Chrome Custom Tabs (CCT)

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

يوفر iOS مكونين رئيسيين لـ System WebView للمصادقة:

ASWebAuthenticationSession (موصى به للمصادقة):

• مصمم خصيصاً لـ OAuth/OIDC وتدفقات تسجيل الدخول الآمنة
• يطالب المستخدم تلقائياً بأن التطبيق يريد المصادقة
• يشارك ملفات تعريف الارتباط وبيانات الاعتماد مع Safari
• يدعم مفاتيح المرور عبر iCloud Keychain

SFSafariViewController (للتصفح العام):

• تجربة Safari كاملة داخل التطبيق
• يعرض شريط URL ومؤشرات الأمان
• لا يشارك ملفات تعريف ارتباط Safari على iOS 11+؛ استخدم ASWebAuthenticationSession عندما تكون مشاركة جلسة Safari مطلوبة
• أقل قابلية للتخصيص ولكنه أكثر جدارة بالثقة للمستخدمين

إذا كان تطبيقك يستخدم تسجيل الدخول المستند إلى OAuth، فإن ASWebAuthenticationSession هو الخيار الموصى به لأنه مصمم خصيصاً لسيناريوهات المصادقة ويوفر أفضل توازن بين الأمان وتجربة المستخدم.

توفر Chrome Custom Tabs (CCT) تجربة مصادقة مدعومة من Chrome داخل تطبيقك:

الميزات الرئيسية:

• تشارك ملفات تعريف الارتباط وبيانات الاعتماد مع متصفح Chrome
• تعرض عنوان URL ومؤشرات الأمان
• يمكن تخصيص لون شريط الأدوات والعلامة التجارية
• التحمية المسبقة لأوقات تحميل أسرع

تكامل OAuth: تعد Chrome Custom Tabs بمثابة مكافئ Android لـ ASWebAuthenticationSession في iOS، مما يوفر دعماً ممتازاً لـ OAuth مع الحفاظ على الوصول إلى مفاتيح المرور المخزنة.

جرّب passkeys في عرض مباشر.

جرّب passkeys

توفر Embedded WebViews تحكماً كاملاً في عرض محتوى الويب داخل تطبيقك، مما يسمح بالمعالجة المباشرة لملفات تعريف الارتباط والجلسات والتنقل بدون شريط URL. ومع ذلك، يأتي هذا التحكم مع متطلبات فنية إضافية لتمكين وظيفة مفتاح المرور.

متى تختار Embedded WebView:

• تجربة تشبه الأصلية: يقوم تطبيقك بالفعل بتضمين المصادقة داخل طريقة عرض ويب مخصصة للحفاظ على شكل ومظهر أصليين، وتريد الحفاظ على تجربة المستخدم المتسقة هذه
• الحاجة إلى التحكم في الجلسة/ملفات تعريف الارتباط: يتطلب تطبيقك المعالجة المباشرة لرموز المصادقة وحالة الجلسة بعد اكتمال مصادقة OAuth
• تدفق مصادقة موجود حيث تُرجع مصادقة System WebView رمز مصادقة ولكن لا توجد جلسة في السياقات المضمنة
• يجب الحفاظ على حالة المصادقة عبر شاشات ويب مضمنة متعددة
• مصادقة الطرف الأول فقط: يتعامل تطبيقك مع المصادقة مباشرةً، لتطبيقات مفاتيح المرور التابعة لجهات خارجية انظر هنا
• AndroidX WebKit 1.12.1+ مع اكتشاف الميزات في وقت التشغيل
• قبول قيد Conditional UI لتسجيل الدخول (غير مدعوم في Embedded WebView)، غير ذي صلة بإعدادات الإدارة

سياق مهم:

تستخدم العديد من التطبيقات نهجاً هجيناً: يتعامل System WebView مع مصادقة OAuth الأولية (حيث تعمل مفاتيح المرور بسلاسة)، ثم ينتقل إلى Embedded WebView لما بعد المصادقة لإدارة مفاتيح المرور في الإعدادات. تنشأ التحديات عند محاولة استخدام مفاتيح المرور مباشرة داخل Embedded WebViews.

المتطلبات الفنية:

تتطلب Embedded WebViews إعداداً إضافياً مقارنة بـ System WebViews:

1. iOS: استحقاقات Associated Domains، وتكوين ملف AASA
2. Android: AndroidX WebKit 1.12.1+ مع تكوين WebAuthn لـ WebView (يتطلب اكتشاف الميزات)
3. كلاهما: ملفات ارتباط معروفة تم تكوينها بشكل صحيح و Digital Asset Links

مكونات المنصة:

• iOS: WKWebView
• Android: android.webkit.WebView

المقايضات:

• تعقيد متوسط: يتطلب تكوين WebView (Android WebKit 1.12.1+) وإعداد الاستحقاقات (iOS)
• اعتماد أقل لمفتاح المرور: قد يواجه المستخدمون احتكاكاً أكبر مقارنة بالتنفيذ الأصلي
• Conditional UI غير مدعوم: لا يعمل الملء التلقائي لمفتاح المرور في حقول الإدخال في Android Embedded WebView
• دعم محدود للمنصة: قد لا تعمل بعض الميزات بشكل متسق (مثل الإنشاء التلقائي لمفتاح المرور)

عند تنفيذ مفاتيح المرور عبر WebViews، فإن فهم التمييز بين System WebViews و Embedded WebViews أمر بالغ الأهمية. الأساليب الثلاثة الموضحة أعلاه (التنفيذ الأصلي، System WebView، و Embedded WebView) تخدم كل منها حالات استخدام مختلفة.

على iOS، لديك خيارات متعددة لعرض محتوى الويب داخل التطبيق:

• WKWebView هو WebView قابل للتخصيص يعد جزءاً من إطار عمل WebKit (تم تقديمه في iOS 8). يمنحك الكثير من التحكم في مظهر محتوى الويب وسلوكه.
• SFSafariViewController عبارة عن وحدة تحكم في العرض تقدمها Apple وتعمل كمتصفح Safari خفيف الوزن داخل تطبيقك. يستخدم محرك Safari. في نظام التشغيل iOS 11+، يحتوي على مخزن ملفات تعريف ارتباط منفصل ولا يشارك ملفات تعريف ارتباط Safari. استخدم ASWebAuthenticationSession عندما تكون مشاركة جلسة Safari مطلوبة.
• SFAuthenticationSession / ASWebAuthenticationSession عبارة عن جلسات مصادقة ويب متخصصة (متوفرة منذ iOS 11/12) مخصصة تحديداً لـ OAuth/OpenID أو تدفقات تسجيل الدخول الآمنة الأخرى. وتستفيد هذه أيضاً من Safari خلف الكواليس، ولكنها تركز على تدفقات المصادقة وتتعامل تلقائياً مع أشياء مثل ملفات تعريف الارتباط المشتركة وتسجيل الدخول الأحادي (SSO).

على Android، الخيارات الرئيسية هي:

• Android WebView هو أداة WebView القياسية (android.webkit.WebView)، وهي في الأساس متصفح صغير يمكن تضمينه في أنشطتك. إنها قابلة للتخصيص للغاية ولكنها تعمل في عملية تطبيقك.
• Chrome Custom Tabs (CCT) هي ميزة تفتح علامة تبويب مدعومة من Chrome ضمن سياق تطبيقك. تظهر Custom Tabs كجزء من تطبيقك ولكنها مدعومة من متصفح Chrome (إذا كان مثبتاً) بميزات مثل التحميل المسبق، وملفات تعريف الارتباط المشتركة، وشريط URL المألوف لثقة المستخدم.

في الأقسام التالية، سنتعمق قليلاً في أنواع WebView هذه لنظامي iOS و Android، ونناقش أيها قد يكون الأنسب لتدفقات مصادقة مفتاح المرور.

اشترك في Passkeys Substack للحصول على آخر الأخبار.

اشترك

توفر منصة Apple خيارات WebView الثلاثة المذكورة أعلاه. سيؤثر اختيارك على مدى سلاسة استخدام مفاتيح المرور داخل التطبيق:

لاختبار سلوك WebView المختلف في iOS، نوصي بالتطبيق WebView - WKWebView and UIWebView rendering.

WKWebView هو مكون WebView متعدد الاستخدامات لنظام iOS. يمكن للمطورين تضمين WKWebView لتقديم محتوى ويب بدرجة عالية من التحكم في واجهة المستخدم والسلوك. يستخدم WKWebView نفس محرك العرض مثل Safari، لذلك فهو عالي الأداء ويدعم ميزات الويب الحديثة. من الناحية النظرية، يمكن لـ WKWebView التعامل مع WebAuthn (وبالتالي مفاتيح المرور) إذا تم تكوينه بشكل صحيح، ولكن لاحظ أن بعض ميزات المتصفح المتقدمة قد تكون مقيدة لأسباب أمنية. أحد الأشياء التي يجب الانتباه إليها هو أن WKWebView افتراضياً لا يشارك ملفات تعريف الارتباط أو بيانات سلسلة المفاتيح مع Mobile Safari. قد يضطر المستخدمون إلى تسجيل الدخول من جديد لأن جلسة WebView الخاصة بهم معزولة عن جلسة Safari. أيضاً، نظراً لأن محتوى WKWebView يمكن تخصيصه بالكامل بواسطة التطبيق، لا يرى المستخدم شريط عنوان أو واجهة مستخدم Safari - وهو أمر رائع للعلامة التجارية، ولكنه يعني أن لدى المستخدم إشارات أقل للتحقق من شرعية الصفحة (مخاوف تتعلق بمكافحة التصيد الاحتيالي). أساءت بعض التطبيقات استخدام WKWebView لإدخال نصوص برمجية أو تغيير المحتوى (على سبيل المثال، لوحظ أن TikTok يقوم بإدخال JS تتبع عبر المتصفح داخل التطبيق)، لذلك يجب على المرء أن يكون حذراً لاستخدام WKWebView بطريقة آمنة وجديرة بثقة المستخدم.

يوفر SFSafariViewController تجربة Safari داخل التطبيق. عندما تفتح عنوان URL باستخدام SFSafariViewController، يكون الأمر أشبه بفتحه في متصفح Safari الحقيقي، باستثناء أن المستخدم يظل داخل واجهة مستخدم تطبيقك. الميزة بالنسبة لمفاتيح المرور كبيرة: نظراً لأنه Safari بشكل أساسي، يمكن الوصول إلى iCloud Keychain الخاص بالمستخدم ومفاتيح المرور المحفوظة. لاحظ أن ملفات تعريف الارتباط لا تتم مشاركتها على iOS 11+. وهذا يعني أنه إذا كان لدى المستخدم بالفعل مفتاح مرور لموقعك، فيمكن لـ Safari العثور عليه وحتى عرض الإكمال التلقائي لـ Conditional UI لتسجيل الدخول السهل. SFSafariViewController أقل قابلية للتخصيص (لا يمكنك تغيير شريط الأدوات الخاص به كثيراً)، ولكنه يتعامل تلقائياً مع الكثير من ميزات الأمان والخصوصية. يتم عرض شريط URL، مكتملاً برمز القفل لـ HTTPS، مما يمنح المستخدمين الثقة بأنهم على النطاق الصحيح. بشكل عام، يعتبر SFSafariViewController أكثر أماناً من WKWebView الخام وهو أسهل في التنفيذ (توفره Apple كمكون جاهز). المقايضة الرئيسية هي التضحية ببعض التحكم في الشكل والمظهر. بالنسبة لتدفق المصادقة، عادةً ما يكون هذا مقبولاً. الأولوية هنا هي الأمان وسهولة تسجيل الدخول، والتي يتفوق فيها SFSafariViewController باستخدام سياق Safari.

SFAuthenticationSession / ASWebAuthenticationSession – تم بناء هذه الفئات (والأخيرة هي الاسم الأحدث المتوافق مع Swift) خصيصاً لتدفقات تسجيل الدخول مثل OAuth أو OpenID Connect. عندما تحتاج إلى مصادقة مستخدم عبر صفحة ويب (ربما لمزود هوية IdP خارجي)، فإن هذه الجلسات هي الخيار الموصى به على iOS. إنها تشبه إلى حد كبير SFSafariViewController في أنها تستخدم متصفح Safari خلف الكواليس وتشارك ملفات تعريف الارتباط/التخزين مع Safari. يكمن الاختلاف الرئيسي في أن SFAuthenticationSession سيطالب المستخدم دائماً بأن التطبيق يريد المصادقة باستخدام صفحة ويب (لوعي المستخدم) وسيستخدم تلقائياً جلسة Safari الحالية للمستخدم إذا كانت متوفرة.

الفائدة هي تجربة SSO سلسة - إذا كان المستخدم مسجلاً الدخول بالفعل إلى المزود في Safari، يمكن لهذه الجلسة استخدام ملف تعريف الارتباط هذا لتجنب تسجيل دخول آخر. بالنسبة لمفاتيح المرور، يعد هذا مهماً لأنه يعني أنه يمكن استخدام أي بيانات اعتماد مفتاح مرور مخزنة في Safari/iCloud Keychain هنا أيضاً. إرشادات Apple الرسمية هي استخدام ASWebAuthenticationSession لأي شيء يشبه تدفق تسجيل الدخول. الايجابيات هي الخصوصية المعززة (لا يرى تطبيقك أبداً بيانات الاعتماد أو ملفات تعريف الارتباط، بل يتعامل Safari معها) ودعم SSO المدمج. السلبية هي أنها تقتصر على تدفقات المصادقة (لن تستخدمها فقط لتقديم محتوى ويب عشوائي في تطبيقك). باختصار، إذا اخترت نهج WebView على iOS، فإن ASWebAuthenticationSession هو الخيار الأفضل عادةً لتنفيذ مفاتيح المرور لأنه آمن ويشارك الحالة مع Safari ومصمم خصيصاً للمصادقة.

اطلع على عدد الأشخاص الذين يستخدمون passkeys فعلياً.

عرض بيانات الاعتماد

على Android، يكون قرار WebView بين WebView الكلاسيكي و Chrome Custom Tabs:

لاختبار سلوك WebView المختلف في Android، نوصي بالتطبيق WebView vs Chrome Custom Tabs.

Android WebView (android.webkit.WebView) هو مكون يتيح لك تضمين صفحات الويب في تخطيط نشاطك. إنه مشابه لـ WKWebView في أنه يمنحك التحكم الكامل: يمكنك اعتراض التنقل وإدخال JavaScript وتخصيص واجهة المستخدم وما إلى ذلك. يعمل أيضاً ضمن عملية تطبيقك. استخدام WebView لمفاتيح المرور يعني أن تطبيقك يُحمل صفحة تسجيل الدخول إلى الويب الخاصة بك، ويمكن أن تبدأ تلك الصفحة مراسم مفتاح مرور WebAuthn. يدعم Android WebView الحديث WebAuthn (شريطة أن يكون تنفيذ WebView للجهاز محدثاً عبر Android System WebView أو مكون Chrome). أحد الاعتبارات الرئيسية: افتراضياً، لا يشارك Android WebView ملفات تعريف الارتباط أو بيانات الاعتماد المخزنة مع متصفح Chrome الخاص بالمستخدم. لذا فإن أي مفتاح مرور يتم إنشاؤه أو استخدامه في WebView قد لا يكون معروفاً لمتصفح Chrome، والعكس صحيح. يمكن أن يكون هذا العزل مفيداً للأمان (لا يمكن لتطبيقك قراءة ملفات تعريف ارتباط المتصفح)، ولكنه قد يجبر المستخدمين على تسجيل الدخول مرة أخرى إذا تمت مصادقتهم بالفعل في Chrome. المشكلة الأخرى هي الثقة. لا يُظهر WebView العادي عنوان URL أو رمز قفل SSL، لذلك يجب على المستخدمين الوثوق بتطبيقك تماماً لعدم استهدافهم بالتصيد الاحتيالي. حظرت Google حتى استخدام WebView لتسجيل الدخول إلى Google OAuth بسبب مخاطر التصيد المحتملة. من ناحية الأداء، تعمل WebViews بشكل جيد، لكنها قد تكون أبطأ أو تستهلك ذاكرة أكثر من استخدام المتصفح الافتراضي للمستخدم، خاصة إذا كانت تحميل صفحات ثقيلة.

Chrome Custom Tabs (CCT) هي نهج هجين. إنها تسمح لتطبيقك بفتح صفحة معروضة بواسطة Chrome تبدو وكأنها جزء من تطبيقك. يمكنك تخصيص لون شريط الأدوات وإضافة شعار التطبيق وما إلى ذلك، ولكن يتم عرض المحتوى بواسطة Chrome في عملية منفصلة. بالنسبة لمفاتيح المرور، تمتلك CCTs العديد من الفوائد: فهي تشارك ملفات تعريف الارتباط وبيانات الاعتماد الخاصة بالمستخدم مع Chrome، مما يعني أنه إذا قام المستخدم بحفظ مفتاح مرور عبر Chrome (Google Password Manager)، فيمكن لعلامة التبويب المخصصة الوصول إليه. سيرى المستخدم أيضاً عنوان URL الفعلي ومؤشرات الأمان، مما يبني الثقة. غالباً ما يكون الأداء أفضل - يمكن "تحمية" Chrome في الخلفية للتحميل السريع. والأهم من ذلك، الأمان قوي: نظراً لأنه تطبيق Chrome بشكل أساسي، فإن أشياء مثل التصفح الآمن من Google تحمي الجلسة، ولا يمكن لتطبيقك إدخال نصوص برمجية عشوائية في الصفحة (مما يمنع هجمات معينة).

الجانب السلبي هو أنه يتطلب من المستخدم أن يكون لديه Chrome (أو متصفح مدعوم) مثبتاً ومحدثاً. يمتلكه معظم مستخدمي Android، ولكن في بعض الأجهزة في مناطق معينة، قد يكون هذا مشكلة. بشكل عام، إذا كنت تستخدم نهج ويب مضمن على Android، يوصى باستخدام Chrome Custom Tabs لتدفقات مفتاح المرور، لأنها توفر توازناً جيداً بين التكامل والأمان. في الواقع، إنها مماثلة لـ SFSafariViewController/ASWebAuthSession في iOS من نواح كثيرة - الاستفادة من المتصفح الافتراضي للمصادقة.

(ملاحظة جانبية: WKWebView مقابل SFSafariViewController الخاص بـ Apple و WebView مقابل CCT الخاص بـ Android لديهما العديد من أوجه التشابه. تشترك كل من Safari VC و Chrome Tabs في حالة المتصفح وتوفر أماناً أفضل، في حين تمنحك WKWebView/Android WebView تحكماً أكبر لكنها تعزل محتوى الويب. بالنسبة لمفاتيح المرور، عادة ما يكون من المستحسن مشاركة الحالة (ملفات تعريف الارتباط، مخازن بيانات الاعتماد) حتى يمكن الوصول إلى مفتاح المرور وإنشائه بسلاسة.)

بغض النظر عن نهج التنفيذ الذي تختاره، يجب استيفاء متطلبات فنية معينة لتمكين وظيفة مفتاح المرور. يوفر هذا القسم إرشادات شاملة حول تكوين ملفات الارتباط المعروفة، واستحقاقات iOS، وتكوين Android WebView.

ملاحظة حول الأجهزة المُدارة: يتغير سلوك مفتاح المرور بشكل كبير على الأجهزة المُدارة حيث تتحكم سياسات إدارة الأجهزة المحمولة (MDM) في تخزين بيانات الاعتماد. لاختبار مفاتيح المرور على الأجهزة المُدارة، راجع مفاتيح المرور على أجهزة iOS و Android المُدارة.

تتطلب تدفقات التنفيذ الأصلي و Embedded WebView ملفات ارتباط لإنشاء ثقة تشفير بين تطبيقك ومجال الويب الخاص بك. لا يتطلب System WebView (ASWebAuthenticationSession) و Chrome Custom Tabs ربط التطبيق بالموقع.

ينشئ ملف AASA الاتصال بين تطبيق iOS الخاص بك ومجال الويب الخاص بك، مما يتيح لمفاتيح المرور العمل عبر كلتا المنصتين.

موقع الملف: https://yourdomain.com/.well-known/apple-app-site-association

متطلبات التكوين:

• الاستضافة في /.well-known/apple-app-site-association على نطاقك
• تقديم عبر HTTPS بشهادة SSL صالحة
• Content-Type: application/json
• لا توجد عمليات إعادة توجيه على المسار .well-known
• قم بتضمين معرف الفريق (Team ID) ومعرف الحزمة (Bundle ID) لتطبيقك

مثال لملف AASA:

{
    "webcredentials": {
        "apps": ["TEAMID123.com.example.app"]
    }
}

التخزين المؤقت لـ AASA واختباره:

تقوم Apple بتخزين ملفات AASA مؤقتاً بقوة (من 24 إلى 48 ساعة) باستخدام CDN، مما قد يحبط عملية التطوير والاختبار. لتجاوز التخزين المؤقت أثناء التطوير:

1. قم بتمكين وضع المطور (Developer Mode) على جهاز الاختبار الخاص بك
2. أضف ?mode=developer إلى النطاق المرتبط في Xcode
3. هذا يجبر iOS على جلب أحدث ملف AASA مباشرة من خادمك

⚠️ هام: لا تستخدم ?mode=developer في إصدارات الإنتاج. هذه المعلمة مخصصة للتطوير فقط - استخدامها في الإنتاج سيمنع iOS من اكتشاف ملف AASA الخاص بك بشكل صحيح، مما يؤدي إلى كسر وظيفة مفتاح المرور.

التحقق من الصحة: استخدم أداة التحقق من AASA الخاصة بـ Apple للتحقق من تكوينك.

يستخدم Android روابط الأصول الرقمية (Digital Asset Links) للتحقق من العلاقة بين تطبيقك وموقع الويب الخاص بك.

موقع الملف: https://yourdomain.com/.well-known/assetlinks.json

متطلبات التكوين:

• الاستضافة في /.well-known/assetlinks.json على نطاقك
• تقديم عبر HTTPS بشهادة صالحة
• Content-Type: application/json
• قم بتضمين بصمة SHA256 لتطبيقك (من شهادة التوقيع)

مثال لملف assetlinks.json:

[
    {
        "relation": [
            "delegate_permission/common.handle_all_urls",
            "delegate_permission/common.get_login_creds"
        ],
        "target": {
            "namespace": "android_app",
            "package_name": "com.example.app",
            "sha256_cert_fingerprints": [
                "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
            ]
        }
    }
]

التحقق من الصحة: استخدم مولد روابط الأصول الرقمية من Google لإنشاء التكوين الخاص بك والتحقق منه.

تتطلب تطبيقات iOS استحقاقات (Entitlements) مناسبة للوصول إلى وظيفة مفتاح المرور. تختلف المتطلبات قليلاً بناءً على نهج التنفيذ الخاص بك.

يحدد ملف الاستحقاقات (غالباً ما يسمى Runner.entitlements في تطبيقات Flutter أو YourApp.entitlements في مشاريع iOS الأصلية) أذونات وقدرات خاصة يمنحها نظام Apple. بالنسبة لمفاتيح المرور، يقوم هذا الملف بتكوين النطاقات المرتبطة (Associated Domains).

موقع الملف: عادةً في مشروع Xcode الخاص بك في ios/Runner/Runner.entitlements

يتطلب التنفيذ الأصلي و Embedded WebView قدرة Associated Domains لربط تطبيقك بمجال الويب الخاص بك. لا يتطلب System WebView (ASWebAuthenticationSession) ذلك لأنه يعمل في سياق Safari.

الإعداد في Xcode:

1. افتح مشروعك في Xcode
2. حدد هدف (target) تطبيقك
3. انتقل إلى علامة التبويب "التوقيع والقدرات" (Signing & Capabilities)
4. انقر فوق "+ Capability" وأضف "Associated Domains"
5. أضف نطاقك بالبادئة webcredentials:

مثال على التكوين:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>com.apple.developer.associated-domains</key>
    <array>
        <string>webcredentials:yourdomain.com</string>
        <string>webcredentials:subdomain.yourdomain.com</string>
    </array>
</dict>
</plist>

نطاقات متعددة: إذا كان تطبيقك يحتاج إلى العمل مع نطاقات متعددة، فقد تحتاج إلى طلبات الأصل ذات الصلة (ROR).

تدعم Android Embedded WebViews مفاتيح المرور من خلال نهجين متميزين: النهج الأحدث المستند إلى WebKit (القسم 5.3.1) ونهج جسر JavaScript الأقدم (القسم 5.3.2). لا يتطلب System WebView (Chrome Custom Tabs) أي تكوين - تعمل بيانات الاعتماد تلقائياً.

يوفر Android عينات WebView رسمية لمفاتيح المرور توضح كلا نهجي التنفيذ.

تكامل WebKit الحديث مع التعامل الأصلي مع مفتاح المرور. يوفر هذا النهج دعماً أصلياً لـ WebAuthn دون الحاجة إلى رمز جسر مخصص.

عينة رسمية: Webkit WebView MainActivity

المتطلبات:

• AndroidX WebKit 1.12.1 أو أحدث (يُوصى بـ 1.14.0+)
• تكوين Digital Asset Links
• ملف WebView APK مع دعم WebAuthn (تحقق عبر اكتشاف الميزات)
• ملاحظة: مكتبة AndroidX Credentials ليست مطلوبة لـ WebView WebAuthn، فقط لعمليات التنفيذ الأصلية بالكامل

التنفيذ:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature
 
// تحقق مما إذا كانت مصادقة الويب مدعومة
if (WebViewFeature.isFeatureSupported(WebViewFeature.WEB_AUTHENTICATION)) {
    // تمكين مصادقة الويب
    WebSettingsCompat.setWebAuthenticationSupport(
        webView.settings,
        WebSettingsCompat.WEB_AUTHENTICATION_SUPPORT_FOR_APP
    )
 
    // تمكين JavaScript
    webView.settings.javaScriptEnabled = true
}

النقاط الرئيسية:

• لا حاجة إلى جسر JavaScript: يعمل WebAuthn محلياً في WebView
• يتطلب اكتشاف الميزات: تحقق دائماً من WebViewFeature.WEB_AUTHENTICATION في وقت التشغيل
• Conditional UI غير مدعوم: لا يعمل mediation:"conditional" (الملء التلقائي لمفتاح المرور في حقول الإدخال) في Embedded WebView
• استراتيجية احتياطية: إذا كانت الميزة غير متوفرة، استخدم Chrome Custom Tabs بدلاً من ذلك

ملاحظات الإصدار:

• استخدم WebKit 1.12.1 أو أحدث (واجه 1.12.0 مشكلة في توافر وقت التشغيل)
• يعتمد دعم الميزات على إصدار WebView APK الخاص بالمستخدم - لن تعرض ملفات APK الأقدم على الجهاز الميزة

قبل AndroidX WebKit 1.12.0، لم يكن دعم WebAuthn الأصلي موجوداً في Embedded WebView. يستخدم هذا النهج الأقدم جسراً بين الويب والنظام الأصلي للتعامل مع مفاتيح المرور للأجهزة التي لا تدعم Native WebView WebAuthn.

عينات رسمية:

• PasskeyWebListener (معالج الجسر)
• أدوات تشفير JavaScript

متى يتم استخدامه: دعم إصدارات Android الأقدم أو الأجهزة التي تحتوي على تطبيقات WebView القديمة.

كان على الفرق إما:

1. استخدام Chrome Custom Tabs أو Auth Tab (موصى به)
2. بناء جسر JavaScript مخصص

للحصول على تنفيذ مفصل، راجع دليل تكامل Android Credential Manager WebView. ومع ذلك، نوصي بشدة باستخدام نهج WebKit 1.12.1+ الأصلي للتطبيقات الحديثة.

التوصية: استخدم دعم WebAuthn الأصلي مع AndroidX WebKit 1.12.1+. إذا لم يكن متاحاً في وقت التشغيل، فارجع إلى Chrome Custom Tabs التي توفر دعماً ممتازاً لمفتاح المرور مع بيانات الاعتماد المشتركة.

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

بالنسبة للتطبيقات التي تستخدم نطاقاً واحداً (مثل kayak.com)، تحتاج إلى:

• ملف AASA واحد لنظام iOS في https://kayak.com/.well-known/apple-app-site-association
• ملف assetlinks.json واحد لنظام Android في https://kayak.com/.well-known/assetlinks.json
• استحقاق Associated Domains مكون مع webcredentials:kayak.com

الأصول ذات الصلة (ROR) هي ميزة WebAuthn تسمح لمجموعة واحدة من مفاتيح المرور بالعمل عبر نطاقات متعددة ذات صلة (مثل kayak.com، kayak.de، kayak.co.uk). يستخدم ROR نقطة النهاية /.well-known/webauthn على كل موقع لتحديد الأصول ذات الصلة، وليس ملفات AASA أو assetlinks.

النقاط الرئيسية:

• تكوين ROR: يستضيف كل مجال /.well-known/webauthn مع قائمة الأصول ذات الصلة
• ملفات ارتباط التطبيق (AASA/assetlinks): تُستخدم فقط لتعيين التطبيقات إلى مواقع الويب المقابلة لها
• iOS 18+ Embedded WebView: يدعم ROR عند تكوينه بشكل صحيح
• استحقاقات Associated Domains: قم بتضمين جميع المجالات التي يحتاجها تطبيقك للمصادقة معها

مثال على التكوين:

إذا كان تطبيقك يعمل مع kayak.com و kayak.de، فيجب على كلا النطاقين:

• استضافة ملفات AASA الخاصة بهما بنفس معرف الفريق ومعرف الحزمة
• أن تكون مدرجة في استحقاقات Associated Domains لتطبيقك
• أن تحتوي على ملفات معروفة مكونة بشكل صحيح ويمكن الوصول إليها

قبل البث المباشر، تحقق من تكوين ملفاتك المعروفة بشكل صحيح وإمكانية الوصول إليها. توفر Apple و Google عناوين URL لاختبار CDN للتحقق من توفر الملف:

استخدام عناوين URL للاختبار هذه:

• انقر فوق الروابط للتحقق مما إذا كان بإمكان Apple/Google جلب ملفاتك المعروفة
• تفرض معلمة ?nocache=1 من Apple استرداداً جديداً، متجاوزة ذاكرة التخزين المؤقت لـ CDN
• إذا تعذر الوصول إلى الملفات من خلال عناوين URL هذه، فلن تعمل وظيفة مفتاح المرور في تطبيقك
• استبدل kayak.com أو kayak.de بنطاقك الخاص في أنماط عناوين URL أعلاه

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

مزيد من المعلومات: معرف Relying Party لـ WebAuthn في التطبيقات الأصلية

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

يرشدك المخطط الانسيابي التالي خلال تحديد نهج التنفيذ الصحيح بناءً على متطلبات تطبيقك:

مرجع سريع لكل مسار:

• تسجيل دخول قائم على OAuth؟ ← System WebView (ASWebAuthenticationSession / Chrome Custom Tabs)
• إعادة استخدام مصادقة الويب في واجهة أصلية؟ ← Embedded WebView مع التكوين (WKWebView / Android WebView + WebKit 1.12.1+)
• بناء أصلي أولاً؟ ← التنفيذ الأصلي (AuthenticationServices / Credential Manager)
• مصادقة ويب حالية لإعادة استخدامها؟ ← System WebView للتنفيذ السريع؛ وإلا التنفيذ الأصلي للحصول على تجربة مستخدم مثالية

إليك كيفية أداء كل نهج عبر الأبعاد الرئيسية:

شروحات الأبعاد:

• إنشاء مفاتيح المرور: مدى سهولة قيام المستخدمين بإنشاء مفاتيح مرور من خلال هذا النهج
• استخدام مفاتيح المرور: تجربة المصادقة عند استخدام مفاتيح المرور الحالية
• إدارة مفاتيح المرور: كيف يعرض المستخدمون مفاتيح المرور أو يعدلونها أو يحذفونها
• التعقيد الفني: جهد التطوير والصيانة المستمرة
• دعم OAuth: مدى جودة تعامل النهج مع تدفقات المصادقة OAuth2/OIDC
• وقت الإعداد: الجدول الزمني النموذجي للتنفيذ

موصى به: System WebView

إذا كان تطبيقك يصادق عبر OAuth2 أو OIDC أو موفري تسجيل الدخول الاجتماعي (Google، GitHub، Microsoft، إلخ)، فإن System WebView هو الخيار الأمثل:

• iOS: تم تصميم ASWebAuthenticationSession خصيصاً لتدفقات OAuth
• Android: توفر Chrome Custom Tabs تكاملاً سلساً مع OAuth
• الفوائد: حد أدنى من التعليمات البرمجية الأصلية، مشاركة تلقائية لبيانات الاعتماد
• التنفيذ: أضف WebAuthn إلى صفحة مصادقة الويب الخاصة بك، ثم قم بتحميلها عبر System WebView

مثال: تستخدم تطبيقات السفر مثل kayak.com و kayak.de OAuth للمصادقة. يسمح لهم System WebView بالحفاظ على البنية التحتية الحالية لـ OAuth الخاصة بهم مع إضافة دعم مفتاح المرور من خلال صفحات مصادقة الويب الخاصة بهم.

موصى به: النهج الهجين

استخدم System WebView لمصادقة OAuth الأولية، ثم Embedded WebView لجلسات ما بعد المصادقة:

1. المصادقة الأولية: يتعامل System WebView مع OAuth + تسجيل الدخول بمفتاح المرور
2. إدارة الجلسة: قم بالتبديل إلى Embedded WebView لمحتوى الويب المصادق عليه حيث يلزم التحكم في ملفات تعريف الارتباط/الجلسة
3. الإعداد الفني: قم بتكوين متطلبات System و Embedded WebView - بالنسبة لنظام Android، تأكد من تضمين AndroidX WebKit 1.12.1+ (راجع القسم 5)

متى يتم الاستخدام: التطبيقات التي تصادق عبر OAuth ولكنها تحتاج بعد ذلك إلى عرض محتوى ويب مصادق عليه حيث تتطلب المعالجة المباشرة للجلسة.

موصى به: التنفيذ الأصلي

هل تبني من الصفر أو لديك شاشات أصلية؟ اذهب للأصلي بالكامل:

• iOS: استخدم إطار عمل AuthenticationServices
• Android: استخدم واجهة برمجة تطبيقات Credential Manager
• الفوائد: أفضل تجربة مستخدم، مصادقة فورية، تحكم كامل
• ميزة فريدة: استخدم preferImmediatelyAvailableCredentials لعرض تراكب مفتاح مرور تلقائي عند بدء التطبيق - حصري للتطبيقات الأصلية ويوفر أعلى معدلات التحويل
• توصية SDK: استخدم حزم SDK الخاصة بـ Corbado (iOS، Android) لتسريع التطوير من خلال التعامل مع الحالات الطرفية التي تم اختبارها في الإنتاج

للتطبيقات الجديدة: نوصي بشدة بإنشاء تسجيل دخول أصلي من اليوم الأول. يهيئك للحصول على تجربة مستخدم مثالية ويتجنب عمليات الترحيل المستقبلية من WebView إلى التطبيق الأصلي.

موصى به: الترحيل المرحلي

يوضح المخطط التالي مسار الترحيل المتزايد:

تعتمد كل مرحلة على المرحلة السابقة، مما يسمح بإجراء تحسينات تدريجية دون تعطيل المستخدمين الحاليين.

راجع القسم 5 للحصول على إرشادات التكوين التفصيلية.

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

فئات الاختبار الأساسية:

• الرحلات الأساسية: التسجيل، المصادقة، التدفقات عبر الأجهزة، حذف مفتاح المرور
• تغطية المنصة: iOS (أصلي)، Android (أصلي)، متصفحات الويب عبر إصدارات نظام التشغيل
• ربط النطاق: تحقق من إمكانية الوصول إلى ملفات AASA (iOS) و Digital Asset Links (Android)
• تدفقات الإلغاء: اختبار إلغاء المستخدم في مطالبات نظام التشغيل وشاشات المقاييس الحيوية
• معالجة الأخطاء: فشل الواجهة الخلفية، مهلات الشبكة، عدم تطابق بيانات الاعتماد
• الحالات الطرفية: قفل الشاشة معطل، iCloud/Google Password Manager معطل
• تدفقات OAuth: إكمال تكامل OAuth + مفتاح المرور من البداية إلى النهاية
• الأجهزة المُدارة: بيئات يتم التحكم فيها بواسطة MDM (راجع اختبار الأجهزة المُدارة)
• المديرون الخارجيون: التوافق مع 1Password، Bitwarden، Dashlane
• المصادقة عبر الأجهزة: تدفقات رمز الاستجابة السريعة (QR) واختبار النقل الهجين
• خاص بـ Embedded WebView: إذا كنت تستخدم Embedded WebView، فتحقق من تكوين WebKit 1.12.1+ على Android
• مراقبة الإنتاج: لوحة معلومات لمعدلات النجاح والفشل وزمن الوصول

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

فكر في مطالبة المستخدمين بإنشاء مفاتيح مرور بعد تسجيل الدخول التقليدي الناجح (كلمة المرور، OAuth). نهج التحويل التدريجي هذا:

• لا يعطل تدفقات المصادقة الحالية
• يسمح بتدهور سلس إذا رفض المستخدم
• يزيد من اعتماد مفتاح المرور بمرور الوقت دون فرض تغييرات
• يعمل بشكل جيد مع جميع طرق التنفيذ الثلاثة

مثال: بعد تسجيل الدخول عبر OAuth من خلال System WebView، اعرض مطالبة أصلية: "هل تريد تمكين تسجيل الدخول الأسرع باستخدام Face ID؟" في حالة القبول، أنشئ مفتاح مرور من خلال صفحة ويب محملة في System WebView.

يعد اتخاذ قرار بشأن كيفية تنفيذ مفاتيح المرور - عبر التنفيذ الأصلي أو System WebView أو Embedded WebView خياراً مهماً للتصميم يؤثر على الأمان وتجربة المستخدم وتعقيد التطوير. لا توجد إجابة واحدة تناسب الجميع.

بالنسبة للتطبيقات المستندة إلى OAuth: يعد System WebView (ASWebAuthenticationSession، Chrome Custom Tabs) نقطة البداية الموصى بها. إنه يوفر دعماً ممتازاً لـ OAuth، وجهداً أدنى في التنفيذ، ومشاركة تلقائية لبيانات الاعتماد.

بالنسبة للتطبيقات الأصلية أولاً: انتقل إلى التنفيذ الأصلي عاجلاً وليس آجلاً. يوفر تسجيل الدخول بمفتاح المرور الأصلي تجربة المستخدم الأكثر سلاسة مع إمكانات حصرية مثل preferImmediatelyAvailableCredentials، والتي تتيح التراكب التلقائي لمفتاح المرور عند بدء التطبيق - وهو أمر لا تستطيع تطبيقات WebView توفيره. مع توفير iOS و Android الآن دعماً من الدرجة الأولى لمفاتيح المرور، تظهر النجاحات في العالم الحقيقي اعتماداً عالياً. نضجت الأدوات (بما في ذلك حزم SDK مفتوحة المصدر ومكتبات المنصات) لجعل التكامل الأصلي قابلاً للتحقيق في أطر زمنية معقولة. بينما يجب أن تكون على دراية بسياسات إدارة الأجهزة، والمزامنة عبر الأجهزة، وموفري الجهات الخارجية، يمكن إدارة هذه التحديات بهندسة واختبار دقيقين. والنتيجة هي تسجيل دخول للتطبيق يسعد المستخدمين بسهولته وسرعته مع تحسين الأمان بشكل كبير.

لمتطلبات إطار Embedded WebView: يشيع استخدام Embedded WebView في سيناريوهين واقعيين. أولاً، غالباً ما تستخدم التطبيقات المستندة إلى OAuth طريقة System WebView لتدفق تسجيل الدخول الأولي، ثم تقوم بالتبديل إلى Embedded WebView لعرض خيارات إدارة مفتاح المرور في شاشات الإعدادات حيث يلزم التحكم في الجلسة - على الرغم من أن بعض التطبيقات تبسط ذلك من خلال الاحتفاظ بـ System WebView لكلا التدفقين. ثانياً، تستمر التطبيقات التي قامت بالفعل بتضمين تدفق المصادقة الخاص بها في إطارات WebView قبل اعتماد مفاتيح المرور في هذا النمط من أجل الاتساق. يتطلب Embedded WebView مع دعم WebAuthn الأصلي (AndroidX WebKit 1.12.1+) تكويناً وإعداداً (أذونات، استحقاقات، إعدادات WebView) ولكنه لم يعد يحتاج إلى رمز جسر JavaScript مخصص. لاحظ أن Conditional UI غير مدعوم في Embedded WebView. اختر هذا النهج عند الحفاظ على أنماط المصادقة المضمنة الحالية أو عندما تحتاج إلى التحكم في الجلسة/ملفات تعريف الارتباط لشاشات ما بعد المصادقة.

في النهاية، تمثل مفاتيح المرور في التطبيقات الأصلية قفزة هائلة إلى الأمام في كل من راحة المستخدم والأمان. سواء تم تنفيذها عبر النظام الأصلي، أو System WebView، أو Embedded WebView، فإنها تقضي على مخاطر التصيد الاحتيالي وأعباء إدارة كلمات المرور للمستخدمين. تثبت التطبيقات في العالم الحقيقي مثل دمج مفتاح مرور تطبيق VicRoads الأصلي أن الأساليب الأصلية أولاً تحقق أعلى نسبة اعتماد ورضا للمستخدم عند تنفيذها بشكل صحيح مع ميزات مثل التراكبات التلقائية لمفتاح المرور. باتباع أفضل الممارسات للمصادقة سهلة الاستخدام واختيار نهج التنفيذ الذي يطابق بنية تطبيقك - أصلي أولاً للتطبيقات الجديدة، أو System WebView لتدفقات OAuth، أو Embedded WebView للأنماط المضمنة الحالية - يمكنك تقديم عمليات تسجيل دخول بيومترية بدون كلمة مرور تدرك حقاً رؤية مفاتيح المرور: مصادقة بسيطة وآمنة وممتعة للجميع.

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

• تم تقديم الملفات عبر HTTPS بشهادة صالحة
• نوع MIME الصحيح: application/json
• لا توجد عمليات إعادة توجيه على المسار .well-known
• iOS: يتطابق معرف الفريق ومعرف الحزمة تماماً في ملف AASA
• Android: تتطابق بصمة SHA256 مع شهادة التوقيع الخاصة بك في assetlinks.json
• يتطابق معرف Relying Party مع نطاقك (بدون بروتوكول، بدون منفذ)
• لا توجد شرطات مائلة لاحقة في RP ID
• أصل WebAuthn هو: https://your-domain.com (ليس app://)

• iOS: تم تمكين قدرة Associated Domains في Xcode مع webcredentials:yourdomain.com
• Android: تم الإعلان عن Digital Asset Links في AndroidManifest.xml
• قام المستخدم بتمكين قفل الشاشة (بيومتري أو رقم تعريف شخصي)
• اختبر باستخدام AASA Validator من Apple وأداة Digital Asset Links من Google
• تحقق من أن ملف Runner.entitlements يحتوي على النطاقات المرتبطة الصحيحة

• iOS: استخدام ASWebAuthenticationSession (موصى به) أو SFSafariViewController
• Android: استخدام Chrome Custom Tabs (ليس WebView عادياً)
• iOS: تحقق من تكوين Associated Domains إذا لزم الأمر
• اختبر مشاركة ملفات تعريف الارتباط/بيانات الاعتماد مع متصفح النظام
• تحقق من أن صفحة مصادقة الويب تحتوي على تنفيذ WebAuthn الصحيح

• iOS: تم تكوينه باستحقاقات مناسبة
• iOS: تتضمن Associated Domains جميع النطاقات ذات الصلة
• iOS: ملف AASA يمكن الوصول إليه ومنسق بشكل صحيح
• iOS: اختبر باستخدام ?mode=developer أثناء التطوير (قم بإزالته للإنتاج)
• Android: تم تضمين AndroidX WebKit 1.12.1+ (أو أحدث) في المشروع
• Android: فحص ميزة وقت التشغيل لـ WebViewFeature.WEB_AUTHENTICATION
• Android: تم استدعاء setWebAuthenticationSupport() مع WEB_AUTHENTICATION_SUPPORT_FOR_APP
• Android: تم تمكين JavaScript في إعدادات WebView
• Android: يدعم إصدار WebView APK للمستخدم ميزة WebAuthn (استخدم اكتشاف الميزات، وليس إصدار نظام التشغيل)
• Conditional UI غير مستخدم (غير مدعوم في Embedded WebView)
• التراجع إلى Chrome Custom Tabs إذا كانت ميزة WebAuthn غير متوفرة

• تحقق مما إذا كان لدى المستخدم موفر بيانات اعتماد غير افتراضي نشط (1Password، Bitwarden، إلخ.)
• تحقق من أن الموفر يدعم مفاتيح المرور (لا تدعم جميع مديري كلمات المرور ذلك)
• اختبر مع مدير بيانات الاعتماد الأصلي للمنصة (iCloud Keychain، Google Password Manager)

"NotAllowedError: The request is not allowed by the user agent or the platform in the current context"

• يعني عادةً: استحقاقات مفقودة (iOS) أو ميزة WebView غير متوفرة/ممكنة (Android Embedded WebView)
• تحقق من: تكوين Associated Domains، إمكانية الوصول إلى ملف AASA، إصدار WebKit، اكتشاف الميزات، استدعاء setWebAuthenticationSupport()

لا تظهر أي مطالبة بمفتاح مرور

• قد يعني: عدم تحميل AASA/assetlinks.json، نوع WebView خاطئ، ملف AASA مخزن مؤقتاً
• جرب: التحقق من صحة ملفات الارتباط، استخدم ?mode=developer على iOS للاختبار، تحقق من نوع WebView

للحصول على تصحيح مفصل، راجع مقالتنا حول Relying Party IDs في التطبيقات الأصلية.

مأزق شائع: بيئات التجهيز ذات الوصول المقيد (إدراج عناوين IP في القائمة البيضاء، أو VPN فقط) ستفشل لأنه يجب أن تتمكن شبكات CDN التابعة لـ Apple و Google من جلب ملفات الارتباط الخاصة بك.

• ملفات AASA/assetlinks يمكن الوصول إليها بشكل عام (لا توجد قائمة بيضاء لـ IP، ولا توجد متطلبات VPN)
• تحقق من قدرة Apple CDN على الوصول إلى ملفك: https://app-site-association.cdn-apple.com/a/v1/your-staging-domain.com?nocache=1
• تحقق من قدرة Google على الوصول إلى ملفك: https://digitalassetlinks.googleapis.com/v1/statements:list/?source.web.site=https://your-staging-domain.com&relation=delegate_permission/common.handle_all_urls

نطاق فرعي للتجهيز مع rpID للإنتاج:

إذا كانت بيئة التجهيز الخاصة بك (مثل stg.login.example.com) تستخدم مجال الإنتاج كـ rpID (مثل example.com)، فإن بحث AASA يحدث على مجال rpID، وليس النطاق الفرعي للتجهيز الخاص بك. هذا يعني:

• أضف معرفات حزمة تطبيق التجهيز إلى ملف AASA الإنتاج الخاص بك
• انتبه إلى أن مفاتيح المرور التي تم إنشاؤها في التجهيز ستظهر في تدفقات تسجيل الدخول للإنتاج (ارتباك محتمل)

مثال (بيئات متعددة تشترك في AASA واحد):

{
    "webcredentials": {
        "apps": [
            "TEAMID123.com.example.app",
            "TEAMID123.com.example.app.dev",
            "TEAMID123.com.example.app.stg",
            "TEAMID123.com.example.app.pre"
        ]
    }
}

التوصية: استخدم rpID تجهيز منفصل يطابق مجال التجهيز الخاص بك لتجنب تداخل بيانات الاعتماد بين البيئات. يتطلب هذا ملفات AASA يمكن الوصول إليها بشكل عام على مجال التجهيز.

توضيح ?mode=developer:

تتخطى المعلمة ?mode=developer في Associated Domains ذاكرة التخزين المؤقت لـ CDN الخاصة بـ Apple ولكن لا تتخطى متطلبات إمكانية الوصول. لا يزال يجب أن يكون ملف AASA الخاص بك قابلاً للوصول من الجهاز (ليس من خلال CDN الخاص بـ Apple، ولكن بشكل مباشر). يساعد هذا أثناء التطوير عند تكرار تغييرات AASA، ولكنه لن يساعد إذا كان خادم التجهيز الخاص بك مدرجاً في القائمة البيضاء لـ IP.

حزم Corbado Native SDKs:

• iOS SDK (Swift)
• Android SDK (Kotlin)
• حزمة Flutter

وثائق المنصة:

• Apple: دعم مفاتيح المرور
• Google: Credential Manager

أدوات التحقق من الصحة:

• Apple AASA Validator
• Google Digital Asset Links Generator

حول Corbado

Corbado هي Passkey Intelligence Platform لفِرَق CIAM التي تُدير المصادقة الاستهلاكية على نطاق واسع. نُمكّنك من رؤية ما لا تستطيع سجلات IDP وأدوات التحليل العامة إظهاره: أي الأجهزة وإصدارات أنظمة التشغيل والمتصفحات ومديري بيانات الاعتماد تدعم passkeys، ولماذا لا تتحوّل عمليات التسجيل إلى عمليات دخول، وأين يفشل تدفق WebAuthn، ومتى يُعطّل تحديث نظام التشغيل أو المتصفح تسجيل الدخول بصمت — كل ذلك دون استبدال Okta أو Auth0 أو Ping أو Cognito أو IDP الداخلي لديك. منتجان: Corbado Observe يُضيف observability للـ passkeys وأي طريقة دخول أخرى. Corbado Connect يُقدّم managed passkeys مع تحليلات مدمجة (إلى جانب IDP الخاص بك). تُشغّل VicRoads passkeys لأكثر من 5 ملايين مستخدم مع Corbado (تفعيل passkey بنسبة +80%). تحدث مع خبير Passkey →

يعتمد الاختيار على بنية المصادقة الخاصة بك. إذا كان تطبيقك يستخدم OAuth2 أو OIDC، فإن System WebView (ASWebAuthenticationSession على iOS أو Chrome Custom Tabs على Android) يتطلب أقل جهد في التنفيذ ولا يتطلب إعداد ملف ربط. بالنسبة للتطبيقات الأصلية الجديدة، يوفر التنفيذ الأصلي تجربة مستخدم فائقة، بينما يناسب Embedded WebView التطبيقات التي تقوم بالفعل بتضمين المصادقة في إطار WebView وتحتاج إلى التحكم في الجلسة أو ملفات تعريف الارتباط بعد تسجيل الدخول.

يستفيد SFSafariViewController من محرك Safari، ويعرض شريط URL مع مؤشرات SSL ويوفر حماية من التصيد الاحتيالي، مما يجعله أكثر موثوقية لتدفقات المصادقة. يوفر WKWebView المزيد من تخصيص واجهة المستخدم ولكنه يحتوي على مخزن ملفات تعريف ارتباط معزول منفصل عن Safari، ويتطلب استحقاقات Associated Domains وملف AASA لتمكين مفاتيح المرور، ولا يعرض شريط URL، مما يقلل من إشارات ثقة المستخدم.

تشارك Chrome Custom Tabs ملفات تعريف الارتباط وبيانات الاعتماد المخزنة مع متصفح Chrome الخاص بالمستخدم، مما يعني أن مفاتيح المرور المحفوظة في Google Password Manager يمكن الوصول إليها أثناء المصادقة. يحتوي Android WebView القياسي على مخزن ملفات تعريف ارتباط معزول، ولا يعرض مؤشرات URL أو SSL، وقد حظرته Google صراحةً لتسجيلات الدخول إلى حساب Google بسبب مخاطر التصيد الاحتيالي.

إذا كان لدى المستخدم مدير بيانات اعتماد تابع لجهة خارجية مثل 1Password تم تعيينه كموفر نشط له، فغالباً ما يعترض إنشاء مفتاح المرور وتخزينه، مع إعطاء الأولوية على مدير بيانات الاعتماد الأصلي للمنصة (iCloud Keychain أو Google Password Manager). وهذا يعني أن مفاتيح المرور قد يتم تخزينها في تطبيق الطرف الثالث بدلاً من سلسلة مفاتيح المنصة، مما يؤثر على مزامنة الأجهزة المتعددة وسلوك إدارة مفتاح المرور.

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