دليل تكامل واجهة برمجة تطبيقات TOTP: المصادقة الثنائية (2FA) لتطبيقات الولايات المتحدة (2026)

كلمة المرور لمرة واحدة المستندة إلى الوقت (TOTP) هي العامل الثاني الذي يدعم بهدوء معظم مصادقة الشركات والمستهلكين المهتمين بالأمان في عام 2026. يتم إنشاؤها من جانب العميل من سر مشترك، صالحة لمدة 30 ثانية، مجانية لكل استخدام، ومحصنة ضد هجمات ضخ الرسائل القصيرة (SMS pumping) وهجمات SS7. المشكلة: يجب على المستخدمين تثبيت تطبيق مصادقة وإكمال عملية تسجيل لمرة واحدة. إذا تم تنفيذها بشكل جيد، فإن TOTP هي العامل الثاني المناسب للمستخدمين العائدين بكثرة والخطوة الطبيعية التالية بعد كلمة المرور لمرة واحدة عبر الرسائل القصيرة (SMS OTP). يغطي هذا الدليل تكامل واجهة برمجة تطبيقات TOTP للتطبيقات الأمريكية في عام 2026، والمعيار، والمكتبات، وتجربة المستخدم للتسجيل، وأنماط الإنتاج.

ما هو TOTP؟

TOTP هو رمز مكون من 6-8 أرقام يتم إنشاؤه بواسطة تطبيق مصادقة (Google Authenticator, Authy, 1Password, Microsoft Authenticator) من سر مشترك تقوم بإعداده عند التسجيل، وهو صالح لمدة 30 ثانية. يتغير الرمز كل 30 ثانية. يقوم كل من تطبيق المصادقة الخاص بالمستخدم والخادم الخاص بك بحساب نفس الرمز من نفس السر، و تنجح عملية التحقق إذا تطابقا ضمن نافذة الصلاحية.

المعيار هو RFC 6238، تم نشره في عام 2011 وهو مستقر منذ ذلك الحين. توجد تطبيقات له في كل لغة برمجة رئيسية. التحقق مجاني لكل استخدام لأنه لا يتم إرسال أي رسالة؛ يقوم كلا الطرفين بحساب الرمز محليًا.

TOTP مقابل SMS OTP: متى تستخدم كل منهما

المعياركلمة المرور لمرة واحدة عبر الرسائل القصيرة (SMS OTP)TOTPإعداد المستخدملا شيء (كل مستخدم لديه رسائل قصيرة)تسجيل لمرة واحدة بمسح رمز QR (حوالي 30 ثانية)وقت تحقق المستخدمقراءة الرسالة القصيرة، إدخال الرمز (10-30 ثانية)فتح التطبيق، قراءة الرمز، إدخاله (10-15 ثانية)التكلفة لكل استخدام0.01-0.04 دولار أمريكي في الولايات المتحدة0 دولار (لا يتم إرسال رسالة)مستوى الأمان (NIST)مقيّدمسموح بهعرضة لهجمات SS7/تبديل الشريحةنعملا مقاومة التصيد الاحتياليعرضة للهندسة الاجتماعيةأفضل قليلاً ولكنه ليس محصنًا ضد التصيد الاحتياليعمل دون اتصاللا (يحتاج إلى رسائل قصيرة خلوية)نعم (يتم إنشاء الرموز محليًا)الاسترداد في حالة فقدان الجهازسهل (لا يزال لديك رقم الهاتف)يتطلب رموز استرداد تم إنشاؤها مسبقًا عند التسجيلالتغطية في الولايات المتحدة~99% (عالمي)~30-40% من المستخدمين المستهلكين لديهم تطبيق مصادقة

البنية الصحيحة: كلمة المرور لمرة واحدة عبر الرسائل القصيرة (SMS OTP) عند التسجيل لتغطية عالمية، حث المستخدمين العائدين على التسجيل في TOTP كـ "ترقية"، التحويل الافتراضي إلى TOTP للمستخدمين الذين قاموا بالتسجيل. دليل المصادقة الثنائية (2FA) الخاص بنا يغطي النمط الطبقي.

تكامل TOTP: كيف يعمل

ثلاث خطوات شاملة:

الخطوة 1: إنشاء سر عند التسجيل

# بايثون مع مكتبة pyotp
import pyotp
secret = pyotp.random_base32()  # سر مشفر بـ base32 مكون من 32 حرفًا

# قم بتخزين السر في سجل المستخدم الخاص بك (مشفرًا في حالة السكون)
user.totp_secret = encrypt(secret)
user.save()



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

الخطوة 2: إنشاء URI التوفير ورمز الاستجابة السريعة (QR)

# إنشاء URI otpauth وفقًا لمعيار RFC 6238
uri = pyotp.totp.TOTP(secret).provisioning_uri(
   name=user.email,
   issuer_name='YourApp'
)
# التنسيق: otpauth://totp/YourApp:user@example.com?secret=ABC...&issuer=YourApp

# إنشاء رمز QR يمسحه المستخدم باستخدام تطبيق المصادقة الخاص به
import qrcode
qr_image = qrcode.make(uri)
return qr_image  # عرض للمستخدم



يفتح المستخدم تطبيق المصادقة الخاص به، وينقر على "مسح رمز QR"، ويقرأ التطبيق URI. يستخرج التطبيق السر ويبدأ في إنشاء رموز لذلك الحساب.

الخطوة 3: التحقق من رمز أدخله المستخدم

# التحقق من الرمز عند تسجيل الدخول
def verify_totp(user, user_entered_code):
   secret = decrypt(user.totp_secret)
   totp = pyotp.TOTP(secret)
   # valid_window=1 يعني قبول النافذة السابقة والتالية ذات الـ 30 ثانية
   # في حالة اختلاف التوقيت بين الخادم وجهاز المستخدم
   return totp.verify(user_entered_code, valid_window=1)



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

تجربة مستخدم للتسجيل تعمل بفعالية

خمسة أنماط لتجربة المستخدم تميز تسجيل TOTP الجيد عن المحبط:

عرض رمز الاستجابة السريعة (QR) والسر كنص

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

التحقق من التسجيل فورًا

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

إنشاء رموز استرداد عند التسجيل

‍أنشئ 8-10 رموز استرداد للاستخدام مرة واحدة يحفظها المستخدم قبل إكمال التسجيل. بدونها، لا يمكن للمستخدمين الذين يفقدون أجهزتهم استعادة حساباتهم. قم بتخزين رموز الاسترداد مجزأة في قاعدة بياناتك؛ وضع علامة على كل رمز بأنه مستخدم بعد استهلاكه.

السماح بتطبيقات مصادقة متعددة

‍يستخدم بعض المستخدمين Google Authenticator على الهاتف و Authy على سطح المكتب. يدعم معيار TOTP نفس السر المسجل في تطبيقات متعددة في وقت واحد. يجب أن يوضح سير عمل التسجيل الخاص بك هذا الأمر.

إظهار التطبيق الذي يجب تثبيته

‍معظم المستخدمين لم يروا TOTP من قبل. اعرض التطبيقات الأربعة الأكثر شيوعًا (Google Authenticator, Microsoft Authenticator, Authy, 1Password) مع روابط التنزيل أثناء التسجيل.

مرجع المكتبات: TOTP في اللغات الرئيسية

LanguageLibraryInstallNode.js / TypeScriptotplibnpm install otplibPythonpyotppip install pyotpJavajava-otpMaven: com.eatthepath:java-otpPHPotphpcomposer require spomky-labs/otphpGootpgo get github.com/pquerna/otpRubyrotpgem install rotpRusttotp-rsCargo: totp-rs.NETOtp.NETNuGet: Otp.NET

جميعها تطبق معيار RFC 6238 بنفس الطريقة. اختر المكتبة المناسبة للغتك؛ واجهة برمجة التطبيقات متطابقة بشكل أساسي (إنشاء سر، بناء URI، التحقق من الرمز).

أخطاء التنفيذ الشائعة

تخزين السر بنص واضح

‍السر هو المفتاح المشترك؛ يمكن لأي شخص يمتلكه حساب رموز المستخدم. قم بتشفيره في حالة السكون باستخدام مفاتيح يديرها المزود أو يديرها العميل.

تخطي خطوة رموز الاسترداد

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

عدم تحمل انحراف التوقيت

‍إذا انحرف توقيت خادمك وتوقيت جهاز المستخدم بأكثر من 30 ثانية، فسيفشل التحقق. استخدم valid_window=1 (لقبول النوافذ السابقة والتالية) لتحمل الانحرافات الصغيرة. لتحمل أعلى، استخدم valid_window=2.

السماح بالتحقق من نفس الرمز مرتين

‍بمجرد استخدام الرمز، قم بوضع علامة على معرف التحقق بأنه مستهلك. وإلا، يمكن للمهاجم الذي يتجسس على الرمز استخدامه خلال نافذة الـ 30 ثانية.

عدم تحديد معدل محاولات التحقق

‍يمكن اختراق رمز مكون من 6 أرقام بالقوة الغاشمة إذا لم تكن هناك قيود على المعدل. حدد 5 محاولات لكل جلسة، ثم طبق تراجعًا أسيًا.

متى تنتقل من TOTP إلى مفتاح المرور (Passkey)

TOTP أقوى بكثير من كلمة المرور لمرة واحدة عبر الرسائل القصيرة (SMS OTP) ولكنه أضعف من مفاتيح المرور (passkeys). مسار النضج النموذجي هو:

1. كلمة المرور لمرة واحدة عبر الرسائل القصيرة (SMS OTP) عند التسجيل لتغطية شاملة (الجميع لديهم رسائل قصيرة).
2. حث المستخدمين المهتمين بالأمان على التسجيل في TOTP خلال أول 30-90 يومًا.
3. بمجرد أن يصبح TOTP شائعًا بين قاعدة المستخدمين لديك، حث على التسجيل في مفتاح المرور (passkey) كترقية تالية.
4. بالنسبة لإجراءات الإدارة عالية المخاطر، اطلب مفاتيح أجهزة FIDO2 بغض النظر عن العوامل الأخرى.

الـ FIDO Alliance تنشر خطة عمل الهجرة إلى مفتاح المرور متعددة السنوات. دليلنا لمقارنة مفتاح المرور بكلمة المرور لمرة واحدة (OTP) يغطي المفاضلات.

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

لماذا نستخدم TOTP إذا كانت مفاتيح المرور أفضل؟‍

يتمتع TOTP بانتشار أوسع بين المستخدمين اليوم مقارنة بمفاتيح المرور (المستخدمون الذين لديهم Google Authenticator أو Authy مثبتًا شائعون؛ المستخدمون الذين سجلوا مفاتيح مرور في خدمتك نادرون في عام 2026). TOTP هو أيضًا الخطوة الوسيطة الطبيعية بين SMS OTP ومفاتيح المرور للمستخدمين الذين لا يثقون بعد بمفاتيح المرور أو الذين لا تدعم أجهزتهم ذلك. النمط: دعم الثلاثة جميعًا.

هل يتطلب TOTP واجهة برمجة تطبيقات (API) لكلمة المرور لمرة واحدة (OTP) على الإطلاق؟‍

ليس للتحقق نفسه — يتم حساب الرموز من جانب العميل والتحقق منها من جانب الخادم باستخدام مكتبة قياسية. ولكنك عادةً ما تستخدم واجهة برمجة تطبيقات OTP جنبًا إلى جنب مع TOTP من أجل: (أ) عامل SMS OTP الأولي عند التسجيل (التحقق من أن المستخدم يمتلك الهاتف قبل السماح بالتسجيل في TOTP)، (ب) استعادة الحساب عبر الرسائل القصيرة عندما يفقد المستخدم جهاز TOTP الخاص به، (ج) عامل احتياطي على الأجهزة التي لا يتوفر فيها TOTP.

كم يجب أن يكون طول رمز TOTP؟‍

يدعم RFC 6238 أرقامًا مكونة من 6 أو 7 أو 8 خانات. ستة أرقام هي الافتراضي العالمي — كل تطبيق مصادقة يعرض رموزًا من 6 أرقام، وكل مستخدم يتوقعها. ثمانية أرقام تضيف أمانًا هامشيًا بتكلفة كبيرة على تجربة المستخدم. التزم بستة أرقام.

أضف TOTP كطبقة ضمان عالية في نظامك

TOTP مجاني لكل عملية تحقق، ومقاوم للتصيد الاحتيالي، وهو العامل الثاني المناسب للمستخدمين العائدين المهتمين بالأمان. أضفه جنبًا إلى جنب مع تكامل SMS OTP الحالي لديك كخيار "ترقية" للمستخدمين الذين يرغبون في أمان أقوى. VerifyNow for USA يتعامل مع طبقة الرسائل القصيرة (SMS) باستخدام مسارات 10DLC ومعرفات المرسل المعتمدة مسبقًا (ابدأ الإرسال في أقل من 5 دقائق)؛ قم بإقرانه بمكتبة TOTP التي تختارها لطبقة الضمان العالية. أرصدة اختبار مجانية، لا تتطلب بطاقة ائتمان.