DEV Community

Cover image for كيفية اختبار APIs التي تتطلب شهادات العميل (mTLS) في Apidog
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية اختبار APIs التي تتطلب شهادات العميل (mTLS) في Apidog

تصل إلى واجهة برمجة تطبيقات شريك (API)، وترسل طلبًا صحيحًا مع رمز مميز صالح، لكن مصافحة TLS تفشل. في هذه الحالة، لا تنتظر نقطة النهاية مفتاح API أو رأس Authorization فقط؛ بل تطلب من العميل إثبات هويته بشهادة قبل إرسال أي طلب HTTP. هذه هي مصادقة TLS المتبادل (mTLS).

جرّب Apidog اليوم

يوضح هذا الدليل كيفية إعداد شهادات العميل وشهادات المرجع المصدق (CA) في Apidog لاختبار واجهات API المحمية بـ mTLS. ستربط شهادة العميل والمفتاح بمضيف محدد، وتضيف CA للجذور ذاتية التوقيع، ثم ترسل طلبًا يرفق Apidog شهادته تلقائيًا. إذا كانت أخطاء الشهادات جديدة عليك، اقرأ أيضًا دليل التحقق من شهادة SSL. وللخلفية البروتوكولية، راجع مرجع MDN TLS.

ما هو TLS المتبادل (mTLS)؟

في HTTPS التقليدي، يقدم الخادم شهادته ويتحقق العميل منها، ثم يبدأ الاتصال المشفر. لا يثبت العميل هويته تشفيريًا على مستوى TLS؛ بل يعتمد الخادم عادةً على مفتاح API أو رمز حامل داخل الطلب.

في mTLS، تتحقق الثقة في الاتجاهين:

  1. يقدم الخادم شهادته للعميل.
  2. يطلب الخادم شهادة من العميل.
  3. يتحقق كل طرف من شهادة الطرف الآخر.
  4. إذا لم تكن شهادة العميل موثوقة لدى الخادم، تفشل المصافحة قبل إرسال الرؤوس أو جسم الطلب.

تظهر mTLS غالبًا في الحالات التالية:

  • الخدمات المصرفية والمدفوعات: قد تتطلب واجهات الخدمات المصرفية المفتوحة ومعالجات البطاقات شهادة عميل بالإضافة إلى OAuth. راجع وثائق Stripe كمثال على الاعتمادات متعددة الطبقات للخدمات الحساسة.
  • الاتصالات الداخلية وخدمة إلى خدمة: تستخدمها الأنظمة ذات نموذج الثقة الصفرية لإثبات هوية الخدمات بدل الاعتماد على محيط الشبكة.
  • واجهات API بين الشركات (B2B): قد يمنحك الشريك شهادة عميل أثناء الإعداد حتى تتمكن الأنظمة المسجلة فقط من الوصول إلى نقاط النهاية.

يمكن أن تعمل mTLS مع OAuth في الوقت نفسه. يوضح RFC 8705 كيفية ربط رموز OAuth بشهادة العميل في mTLS.

الشهادات تخص طبقة TLS، بينما مفاتيح API ورموز الحامل وOAuth تخص طبقة الطلب.

في Apidog:

  • اضبط mTLS من تبويب Certificates.
  • اضبط مفاتيح API وBearer Token وOAuth وBasic Auth من تبويب Authorization.

كيف يطابق Apidog الشهادات مع المضيف

يتم إعداد شهادات العميل وشهادات CA على مستوى عام في Apidog، وليس لكل طلب منفصل. تربط الشهادة بمضيف، ثم يرفقها Apidog تلقائيًا مع كل طلب HTTPS يطابق هذا المضيف.

هناك نوعان رئيسيان:

  • شهادة العميل: تقدمها للخادم لإثبات هويتك أثناء مصافحة mTLS.
  • شهادة المرجع المصدق (CA): تضيف جهة موثوقة إلى Apidog عندما تستخدم نقطة النهاية شهادة خادم موقعة ذاتيًا أو صادرة عن CA داخلي.

مثال على خطأ CA شائع:

SSL Error: Self signed certificate
Enter fullscreen mode Exit fullscreen mode

مفتاح نجاح الإعداد هو مطابقة المضيف بدقة. إذا لم يتطابق مضيف الطلب مع المضيف الذي سجلته للشهادة، فلن يرسل Apidog شهادة العميل.

إعداد شهادة عميل لواجهة API تستخدم mTLS

لنفترض أن شريك مدفوعات أعطاك شهادة عميل ومفتاحًا خاصًا للوصول إلى:

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

وتريد اختبار نقطة النهاية التالية:

GET /v1/settlements
Enter fullscreen mode Exit fullscreen mode

1. افتح إعدادات الشهادات

في Apidog:

  1. افتح Settings من أعلى اليمين.
  2. انتقل إلى تبويب Certificates.
  3. استخدم هذا القسم لإدارة شهادات العميل وCA حسب المضيف.

هذه الإعدادات لا ترتبط بطلب واحد؛ بل تطبق تلقائيًا على كل طلب يطابق المضيف.

2. أضف شهادة العميل

ضمن Client Certificates، اختر Add Certificate.

في حقل Host، أدخل النطاق فقط، من دون البروتوكول:

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

لا تدخل:

https://partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

إذا كانت الشهادة تغطي نطاقات فرعية متعددة، استخدم نمط wildcard:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

بهذا يمكن استخدام شهادة واحدة لعدة مضيفين مثل:

partner-api.acmebank.com
sandbox-api.acmebank.com
settlements-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

3. اضبط المنفذ عند الحاجة

اترك المنفذ فارغًا إذا كانت الخدمة تستخدم HTTPS القياسي على المنفذ 443.

إذا كانت خدمة mTLS تعمل على منفذ مختلف، حدده صراحةً، مثل:

8443
Enter fullscreen mode Exit fullscreen mode

يجب أن يطابق المنفذ عنوان الطلب، وإلا قد لا يجد Apidog ربط الشهادة الصحيح.

4. اختر ملفات الشهادة

يدعم Apidog تنسيقات شائعة لشهادات العميل:

  • CRT + Key: ملف شهادة وملف مفتاح خاص منفصل.
  • PFX: ملف واحد يحتوي الشهادة والمفتاح معًا.

أمثلة على ملفات قد تستلمها من الشريك:

client.crt
client.key
Enter fullscreen mode Exit fullscreen mode

أو:

client.pfx
Enter fullscreen mode Exit fullscreen mode

إذا كان المفتاح الخاص محميًا، أدخل كلمة المرور في حقل Passphrase. اتركه فارغًا إذا لم يكن المفتاح محميًا بكلمة مرور.

5. احفظ الشهادة

اختر Add لحفظ الإعداد.

بعد الحفظ، تصبح شهادة العميل مرتبطة بالمضيف:

partner-api.acmebank.com
Enter fullscreen mode Exit fullscreen mode

ولن تحتاج إلى إرفاقها يدويًا مع كل طلب.

6. أرسل طلب API

أنشئ طلب HTTPS إلى المضيف المطابق:

GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <your_oauth_token>
Enter fullscreen mode Exit fullscreen mode

عند الإرسال، يقوم Apidog بالترتيب التالي:

  1. يطابق partner-api.acmebank.com مع إعداد شهادة العميل.
  2. يرسل شهادة العميل أثناء مصافحة TLS.
  3. يكمل mTLS.
  4. يرسل طلب HTTP ورأس OAuth كالمعتاد.

قد تكون الاستجابة الناجحة مثل الآتي:

{
  "settlements": [
    {
      "id": "stl_88213",
      "amount": 41200,
      "currency": "USD",
      "status": "cleared",
      "settled_at": "2026-07-14T09:31:00Z"
    }
  ],
  "next_cursor": null
}
Enter fullscreen mode Exit fullscreen mode

إضافة شهادة مرجع مصدق (CA) للجذور الداخلية أو ذاتية التوقيع

شهادة العميل تثبت هويتك للخادم، لكن العميل يجب أن يثق أيضًا بشهادة الخادم.

إذا كانت نقطة النهاية تستخدم شهادة موقعة ذاتيًا أو CA داخليًا، قد يظهر هذا الخطأ قبل بدء mTLS:

SSL Error: Self signed certificate
Enter fullscreen mode Exit fullscreen mode

لحل المشكلة:

  1. افتح Settings ثم Certificates.
  2. فعّل CA Certificates.
  3. اختر ملف CA بتنسيق PEM.

يمكن أن يحتوي ملف PEM واحد على سلسلة كاملة من الشهادات، بما فيها الجذر والشهادات الوسيطة:

-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----
Enter fullscreen mode Exit fullscreen mode

بعد إضافة CA:

  • يثق Apidog بشهادة خادمك الداخلية.
  • تتحقق الخدمة من شهادة العميل.
  • يكتمل اختبار mTLS من البداية إلى النهاية.

نصائح عملية وأخطاء شائعة

استخدم wildcard للنطاقات الفرعية

بدل إضافة شهادة مستقلة لكل نطاق فرعي، استخدم:

*.acmebank.com
Enter fullscreen mode Exit fullscreen mode

هذا مناسب عندما يمنحك الشريك شهادة wildcard واحدة لبيئات الإنتاج والاختبار.

راجع المنافذ غير القياسية

قد تستخدم البوابات الداخلية منافذ مثل:

8443
9443
Enter fullscreen mode Exit fullscreen mode

إذا سجلت الشهادة لمنفذ 443 بينما الطلب يذهب إلى 8443، قد لا يطابق Apidog إعداد الشهادة.

أعد إضافة الشهادة لتحديثها

الشهادات غير قابلة للتحرير بعد إضافتها. لتدوير شهادة أو تصحيح اسم المضيف:

  1. احذف الشهادة الحالية.
  2. أضف الشهادة الجديدة أو المصححة.
  3. اختبر الطلب مرة أخرى.

أدر هذه العملية ضمن إجراء واضح لتدوير الشهادات في فريقك.

استخدم شهادة واحدة لكل نطاق

لا تضف شهادتي عميل لنفس المضيف. قد يسبب ذلك التباسًا حول الشهادة التي يجب إرسالها.

احتفظ بربط واحد واضح لكل مضيف أو نمط مضيف.

افصل بين mTLS والتخويل

إذا كان الشريك يطلب شهادة عميل وOAuth معًا:

  • أضف شهادة العميل من Certificates.
  • أضف رمز OAuth من Authorization.

يمكنك تطبيق التخويل على مستويات متعددة:

  • طلب واحد.
  • مجلد كامل.
  • مجموعة كاملة.

للتفاصيل، راجع دليل مصادقة بوابة API ودليل تكوين مصادقة Kerberos في Apidog.

استخدم HTTPS فقط

لن يرسل Apidog شهادة عميل مع طلب HTTP عادي:

http://example.com
Enter fullscreen mode Exit fullscreen mode

يجب أن يكون عنوان الطلب HTTPS:

https://example.com
Enter fullscreen mode Exit fullscreen mode

أتمتة اختبارات mTLS باستخدام Apidog CLI

بعد نجاح الطلبات يدويًا، يمكنك تشغيل سيناريوهات الاختبار المحفوظة دون واجهة رسومية عبر Apidog CLI.

ثبّت CLI وسجّل الدخول:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Enter fullscreen mode Exit fullscreen mode

ثم شغّل سيناريو محفوظًا مقابل بيئة محددة:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
Enter fullscreen mode Exit fullscreen mode

يمكنك تمرير إعدادات شهادة العميل مباشرةً إلى apidog run:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <scenario_id> \
  -e <env_id> \
  --ssl-client-cert ./client.pem \
  --ssl-client-key ./client.key \
  --ssl-client-passphrase "$CLIENT_KEY_PASSPHRASE" \
  --ssl-extra-ca-certs ./internal-ca.pem \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

الخيارات المهمة:

الخيار الاستخدام
--ssl-client-cert مسار شهادة العميل بتنسيق PEM
--ssl-client-key مسار المفتاح الخاص
--ssl-client-passphrase عبارة مرور المفتاح عند الحاجة
--ssl-extra-ca-certs ملف CA إضافي موثوق
--ssl-client-cert-list ملف إعداد لربط شهادات متعددة بأنماط URL
-r html,cli إنشاء تقارير HTML ومخرجات CLI

اربط الأمر في خط أنابيب CI/CD لتشغيل اختبارات mTLS مع كل عملية دفع. راجع دليل Apidog CLI في CI/CD لإعداد التنفيذ داخل مسار الأتمتة.

الأسئلة المتكررة

هل أحتاج إلى شهادة عميل وشهادة CA معًا؟

يعتمد ذلك على الخدمة:

  • تحتاج إلى شهادة العميل عندما يطلب الخادم mTLS.
  • تحتاج إلى شهادة CA عندما لا يثق جهازك أو Apidog بجهة إصدار شهادة الخادم، مثل CA داخلي أو شهادة ذاتية التوقيع.

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

لماذا لا يرسل Apidog شهادة العميل؟

تحقق من النقاط التالية:

  1. أدخلت المضيف من دون https://.
  2. المضيف في إعداد الشهادة يطابق مضيف URL تمامًا.
  3. المنفذ صحيح، خصوصًا عند استخدام 8443 أو 9443.
  4. عنوان الطلب يبدأ بـ https:// وليس http://.

أين أضع مفتاح API أو Bearer Token؟

أضفه من تبويب Authorization في الطلب أو المجلد، وليس من إعدادات الشهادات.

للمزيد، راجع دليل مخططات الأمان.

هل يمكن لشهادة واحدة تغطية عدة نطاقات فرعية؟

نعم. استخدم نمط wildcard:

*.example.com
Enter fullscreen mode Exit fullscreen mode

وسيطبق Apidog الشهادة نفسها على النطاقات الفرعية المطابقة.

كيف أحدث شهادة موجودة؟

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

الخلاصة

لاختبار API محمية بـ mTLS في Apidog:

  1. اربط شهادة العميل بالمضيف الصحيح.
  2. أضف شهادة CA إذا كانت الخدمة تستخدم جذرًا داخليًا أو شهادة ذاتية التوقيع.
  3. أرسل طلب HTTPS ودع Apidog يطابق المضيف ويرفق الشهادة تلقائيًا.
  4. اضبط OAuth أو مفاتيح API بشكل منفصل من تبويب Authorization عند الحاجة.

نزّل Apidog، أضف شهادة شريكك، ثم أرسل أول طلب mTLS مصادق عليه.

Top comments (0)