إثبات ملكية أرقام الهواتف على الويب باستخدام WebOTP API

مساعدة المستخدمين في ما يتعلّق بكلمات المرور لمرة واحدة التي يتم تلقّيها من خلال الرسائل القصيرة

Eiji Kitamura

ما هي WebOTP API؟

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

تتوفّر طرق متنوعة لتأكيد أرقام الهواتف، ولكن إحدى أكثر الطرق شيوعًا هي إرسال كلمة مرور صالحة لمرة واحدة (OTP) تم إنشاؤها عشوائيًا عبر رسالة SMS. ويُثبت إرسال هذا الرمز إلى خادم المطوّر أنّك تتحكّم في رقم الهاتف.

تم تطبيق هذه الفكرة في العديد من السيناريوهات لتحقيق ما يلي:

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

تتسبّب العملية الحالية في إزعاج المستخدمين. يُعدّ العثور على كلمة مرور صالحة لمرة واحدة داخل رسالة SMS ثم نسخها ولصقها في النموذج أمرًا مرهقًا، ما يؤدي إلى انخفاض معدّلات الإحالات الناجحة في رحلات المستخدمين المهمة. وقد كان تسهيل هذه العملية من الطلبات القديمة التي تلقّيناها من العديد من أكبر المطوّرين في العالم. يتضمّن Android واجهة برمجة تطبيقات تنفّذ هذه العملية بالضبط. وينطبق الأمر نفسه على iOS و Safari.

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

أمثلة واقعية

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

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

تم توضيح العملية بأكملها في الرسم البياني أدناه.

مخطّط WebOTP API

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

  1. انتقِل إلى https://chrome.dev/web-otp-demo في الإصدار 84 من Chrome أو إصدار أحدث على جهاز Android.
  2. أرسِل الرسالة النصية القصيرة التالية إلى هاتفك من هاتف آخر.
Your OTP is: 123456.

@chrome.dev #123456

هل تلقّيت الرسالة النصية القصيرة وظهرت لك رسالة تطلب منك إدخال الرمز في مساحة الإدخال؟ هذه هي طريقة عمل WebOTP API للمستخدمين.

يتألف استخدام WebOTP API من ثلاثة أجزاء:

  • علامة <input> تمّت إضافة التعليقات التوضيحية إليها بشكلٍ صحيح
  • JavaScript في تطبيق الويب
  • نص الرسالة المنسَّق الذي تم إرساله عبر الرسائل القصيرة SMS

سأشرح العلامة <input> أولاً.

إضافة تعليق توضيحي إلى علامة <input>

تعمل WebOTP بدون أي تعليق توضيحي بتنسيق HTML، ولكن لضمان التوافق مع جميع المتصفحات، أنصحك بشدة بإضافة autocomplete="one-time-code" إلى علامة <input> التي تتوقّع أن يدخل فيها المستخدم كلمة مرور صالحة لمرة واحدة.

يتيح ذلك لمتصفّح Safari 14 أو الإصدارات الأحدث اقتراح ملء حقل <input> تلقائيًا برمز OTP عندما يتلقّى المستخدم رسالة SMS بالتنسيق الموضّح في تنسيق رسالة SMS، حتى إذا كان المتصفّح لا يتوافق مع WebOTP.

HTML

<form>
  <input autocomplete="one-time-code" required/>
  <input type="submit">
</form>

استخدام WebOTP API

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

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    const ac = new AbortController();
    const form = input.closest('form');
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.log(err);
    });
  });
}

رصد الميزات

إنّ عملية رصد الميزات هي نفسها كما هو الحال مع العديد من واجهات برمجة التطبيقات الأخرى. سيؤدي الاستماع إلى حدث DOMContentLoaded إلى الانتظار إلى أن تصبح شجرة DOM جاهزة للاستعلام.

JavaScript

if ('OTPCredential' in window) {
  window.addEventListener('DOMContentLoaded', e => {
    const input = document.querySelector('input[autocomplete="one-time-code"]');
    if (!input) return;
    …
    const form = input.closest('form');
    …
  });
}

معالجة كلمة المرور الصالحة لمرة واحدة

إنّ واجهة برمجة التطبيقات WebOTP بسيطة بما يكفي. استخدِم navigator.credentials.get() للحصول على كلمة المرور لمرة واحدة. تضيف WebOTP الخيار الجديد otp إلى هذه الطريقة. يحتوي هذا العنصر على سمة واحدة فقط هي transport، ويجب أن تكون قيمتها مصفوفة تتضمّن السلسلة 'sms'.

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
    …

يؤدي ذلك إلى تشغيل مسار طلب الإذن من المتصفّح عند وصول رسالة SMS. إذا تم منح الإذن، سيتم حلّ الوعد الذي تم عرضه باستخدام عنصر OTPCredential.

محتوى العنصر OTPCredential الذي تم الحصول عليه

{
  code: "123456" // Obtained OTP
  type: "otp"  // `type` is always "otp"
}

بعد ذلك، مرِّر قيمة كلمة المرور الصالحة لمرة واحدة إلى الحقل <input>. سيؤدي إرسال النموذج مباشرةً إلى إلغاء الخطوة التي تتطلّب من المستخدم النقر على زر.

JavaScript

    …
    navigator.credentials.get({
      otp: { transport:['sms'] }
      …
    }).then(otp => {
      input.value = otp.code;
      if (form) form.submit();
    }).catch(err => {
      console.error(err);
    });
    …

إلغاء الرسالة

في حال أدخل المستخدم رمز OTP يدويًا وأرسل النموذج، يمكنك إلغاء طلب get() باستخدام مثيل AbortController في العنصر options.

JavaScript 

    …
    const ac = new AbortController();
    …
    if (form) {
      form.addEventListener('submit', e => {
        ac.abort();
      });
    }
    …
    navigator.credentials.get({
      otp: { transport:['sms'] },
      signal: ac.signal
    }).then(otp => {
    …

تنسيق رسالة SMS

يجب أن تبدو واجهة برمجة التطبيقات بسيطة بما يكفي، ولكن هناك بعض الأمور التي يجب معرفتها قبل استخدامها. يجب إرسال الرسالة بعد طلب navigator.credentials.get()، ويجب تلقّيها على الجهاز الذي تم فيه طلب get(). أخيرًا، يجب أن تلتزم الرسالة بالتنسيق التالي:

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

على سبيل المثال:

Your OTP is: 123456.

@www.example.com #123456

في ما يلي أمثلة سيئة:

مثال على رسالة SMS نصية غير صالحة سبب عدم نجاح هذه الاستراتيجية
Here is your code for @example.com #123456 من المتوقّع أن يكون @ هو الحرف الأول من السطر الأخير.
Your code for @example.com is #123456 من المتوقّع أن يكون @ هو الحرف الأول من السطر الأخير.
Your verification code is 123456

@example.com\t#123456		 يجب ترك مسافة واحدة بين @host و#code.
Your verification code is 123456

@example.com  #123456		 يجب ترك مسافة واحدة بين @host و#code.
Your verification code is 123456

@ftp://example.com #123456		 لا يمكن تضمين مخطط عنوان URL.
Your verification code is 123456

@https://example.com #123456		 لا يمكن تضمين مخطط عنوان URL.
Your verification code is 123456

@example.com:8080 #123456		 لا يمكن تضمين المنفذ.
Your verification code is 123456

@example.com/foobar #123456		 لا يمكن تضمين المسار.
Your verification code is 123456

@example .com #123456		 لا يمكن استخدام مسافات بيضاء في النطاق.
Your verification code is 123456

@domain-forbiden-chars-#%/:<>?@[] #123456		 يجب ألا يتضمّن النطاق أي أحرف محظورة.
@example.com #123456

Mambo Jumbo		 من المتوقّع أن يكون @host و#code هما السطر الأخير.
@example.com #123456

App hash #oudf08lkjsdf834		 من المتوقّع أن يكون @host و#code هما السطر الأخير.
Your verification code is 123456

@example.com 123456		 السمة # غير متوفّرة.
Your verification code is 123456

example.com #123456		 السمة @ غير متوفّرة.
Hi mom, did you receive my last text السمتان @ و# غير متوفّرتَين.

العروض التوضيحية

جرِّب رسائل مختلفة باستخدام العرض التوضيحي: https://chrome.dev/web-otp-demo

يمكنك العثور على رمز المصدر هنا: https://github.com/GoogleChromeLabs/web-identity-demos/tree/main/web-otp-demo.

استخدام WebOTP من إطار iframe متعدد المصادر

يُستخدم إدخال كلمة مرور صالحة لمرة واحدة (OTP) يتم تلقّيها عبر رسالة SMS في إطار iframe من مصادر متعددة عادةً لتأكيد الدفع، خاصةً مع بروتوكول 3D Secure. من خلال توفير التنسيق الشائع الذي يتيح استخدام إطارات iframe المتعددة المصادر، تقدّم WebOTP API رموز OTP المرتبطة بالمصادر المتداخلة. على سبيل المثال:

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

لاستخدام WebOTP API من داخل إطار iframe من مصادر متعددة، عليك إجراء ما يلي:

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

يمكنك تجربة العرض التوضيحي على الرابط https://web-otp-iframe-demo.stackblitz.io.

إضافة تعليقات توضيحية إلى المصادر المرتبطة في الرسالة النصية القصيرة

عند طلب WebOTP API من داخل إطار iframe، يجب أن تتضمّن الرسالة النصية القصيرة (SMS) مصدر الإطار العلوي مسبوقًا بـ @، ثم رمز OTP مسبوقًا بـ #، ثم مصدر إطار iframe مسبوقًا بـ @ في السطر الأخير.

Your verification code is 123456

@shop.example #123456 @bank.exmple

ضبط "سياسة الأذونات"

لاستخدام WebOTP في إطار iframe من مصادر متعددة، يجب أن يمنح برنامج التضمين إذن الوصول إلى واجهة برمجة التطبيقات هذه من خلال سياسة الأذونات الخاصة بـ otp-credentials لتجنُّب السلوك غير المقصود. بشكل عام، هناك طريقتان لتحقيق هذا الهدف:

عبر عنوان HTTP:

Permissions-Policy: otp-credentials=(self "https://bank.example")

عبر السمة allow في إطار iframe:

<iframe src="https://bank.example/…" allow="otp-credentials"></iframe>

مزيد من الأمثلة حول كيفية تحديد سياسة الأذونات

استخدام WebOTP على الكمبيوتر

في Chrome، تتيح WebOTP الاستماع إلى الرسائل القصيرة الواردة على الأجهزة الأخرى لمساعدة المستخدمين في إكمال عملية تأكيد رقم الهاتف على الكمبيوتر.

WebOTP API على الكمبيوتر

تتطلّب هذه الإمكانية أن يسجّل المستخدم الدخول إلى حساب Google نفسه على كل من متصفّح Chrome على الكمبيوتر وChrome على Android.

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

يمكنك الاطّلاع على مزيد من التفاصيل في المقالة تأكيد رقم الهاتف على الكمبيوتر باستخدام WebOTP API.

الأسئلة الشائعة

لا يظهر مربّع الحوار على الرغم من أنّني أرسل رسالة منسَّقة بشكل صحيح. ما هي المشكلة؟

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

  • إذا كان رقم هاتف المُرسِل مضمّنًا في قائمة جهات الاتصال الخاصة بالمستلِم، لن يتم تشغيل واجهة برمجة التطبيقات هذه بسبب تصميم واجهة برمجة التطبيقات الخاصة بموافقة المستخدم على تلقّي الرسائل القصيرة الأساسية.
  • إذا كنت تستخدم ملف عمل على جهاز Android ولم تعمل ميزة WebOTP، جرِّب تثبيت Chrome واستخدامه في ملفك الشخصي بدلاً من ذلك (أي الملف الشخصي نفسه الذي تتلقّى فيه الرسائل القصيرة).

راجِع التنسيق لمعرفة ما إذا كانت رسالتك النصية القصيرة منسَّقة بشكل صحيح.

هل تتوافق واجهة برمجة التطبيقات هذه مع المتصفحات المختلفة؟

اتفق Chromium وWebKit على تنسيق الرسائل النصية القصيرة، وأعلنت Apple أنّ متصفّح Safari سيتوافق معه بدءًا من الإصدار 14 من iOS والإصدار Big Sur من macOS. على الرغم من أنّ Safari لا يتوافق مع WebOTP JavaScript API، يمكنك إضافة تعليق توضيحي إلى عنصر input باستخدام autocomplete=["one-time-code"]، ما يؤدي إلى اقتراح لوحة المفاتيح التلقائية تلقائيًا بإدخال كلمة المرور لمرة واحدة إذا كانت رسالة SMS متوافقة مع التنسيق.

هل من الآمن استخدام الرسائل القصيرة كوسيلة للمصادقة؟

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

أين يمكنني الإبلاغ عن الأخطاء في تنفيذ Chrome؟

هل عثرت على خطأ في تنفيذ Chrome؟

  • يمكنك الإبلاغ عن الخطأ على crbug.com. ويُرجى تضمين أكبر قدر ممكن من التفاصيل، وتعليمات بسيطة لإعادة إنتاج الخطأ، وضبط المكوّنات على Blink>WebOTP.

كيف يمكنني المساعدة في تحسين هذه الميزة؟

هل تخطّط لاستخدام WebOTP API؟ يساعدنا دعمك العلني في تحديد أولويات الميزات، ويوضّح لمورّدي المتصفّحات الآخرين مدى أهمية توفيرها. يمكنك إرسال تغريدة إلى ‎@ChromiumDev باستخدام الهاشتاغ #WebOTP وإخبارنا بمكان استخدامك لهذه الميزة وكيفية استخدامها.

الموارد