تصل إلى واجهة برمجة تطبيقات شريك (API)، وترسل طلبًا سليم التكوين مع رمز مميز صالح، ومع ذلك تواجه فشلًا في مصافحة TLS. نقطة النهاية لا تطلب مفتاح API الخاص بك. إنها تطلب من عميلك إثبات هويته بشهادة، قبل حتى أن يغادر أي طلب HTTP جهازك. هذا هو TLS المتبادل (mTLS)، وإذا لم تقم بتكوينه من قبل في أداة اختبار، فقد يؤدي ذلك إلى توقف التكامل ليوم كامل.
يستعرض هذا الدليل إعداد شهادات العميل وشهادات المرجع المصدق (CA) في Apidog حتى تتمكن من اختبار واجهة برمجة تطبيقات محمية بتقنية mTLS دون مواجهة مشكلات المصافحة. ستقوم بإضافة شهادة عميل ومفتاح لمضيف معين، وإرفاق شهادة مرجع مصدق (CA) بحيث تتوقف الجذور ذاتية التوقيع عن إلقاء الأخطاء، وإرسال طلب مصادق عليه يوقعه Apidog تلقائيًا. إذا كانت أخطاء الشهادة مجالًا جديدًا بالنسبة لك، فإن المقدمة حول التحقق من شهادة SSL تستحق القراءة جنبًا إلى جنب مع هذا الدليل. أما بالنسبة للبروتوكول نفسه، فإن مرجع MDN TLS هو شرح قوي ومحايد للمورد.
ما هو TLS المتبادل (mTLS) ولماذا تتطلبه بعض واجهات برمجة التطبيقات
HTTPS العادي هو ثقة أحادية الاتجاه. يقدم الخادم شهادة، يتحقق عميلك منها، ويتم تشفير الاتصال. لا يمتلك الخادم دليلًا تشفيريًا على هويتك؛ فهو يعتمد على رمز مميز أو مفتاح API داخل الطلب لذلك.
TLS المتبادل يجعل الثقة ثنائية الاتجاه. لا يزال الخادم يقدم شهادته، لكنه يطلب أيضًا من العميل تقديم واحدة. إذا لم تكن شهادتك موقعة من قبل سلطة إصدار الشهادات يثق بها الخادم، تفشل المصافحة ولا يُفتح الاتصال أبدًا. لا يوجد جسم طلب، ولا رؤوس، لا شيء يمر.
ستصادف مصادقة TLS المتبادل (mTLS) في الأماكن التي لا يكون فيها تسرب رمز حامل (bearer token) نمط فشل مقبولًا:
- الخدمات المصرفية والمدفوعات. غالبًا ما تتطلب واجهات برمجة تطبيقات الخدمات المصرفية المفتوحة ومعالجات البطاقات شهادة عميل صادرة لمؤسستك بالإضافة إلى OAuth. تصف وثائق Stripe هذا النوع من نموذج الاعتماد متعدد الطبقات لنقاط النهاية المالية الحساسة.
- حركة المرور الداخلية ومن خدمة إلى خدمة. تقوم الشركات التي تدير شبكة بدون ثقة بجعل الخدمات تثبت هويتها بالشهادات بدلاً من الثقة بمحيط الشبكة.
- واجهات برمجة تطبيقات الشركاء بين الشركات (B2B). قد يصدر لك الشريك شهادة عميل أثناء الإعداد حتى تتمكن الأجهزة المسجلة الخاصة بك فقط من الوصول إلى نقاط نهايته.
إذا كان OAuth قيد التشغيل أيضًا، فإنهما يتحدان بسلاسة؛ RFC 8705 يضفي الطابع الرسمي على كيفية ربط TLS المتبادل لرمز OAuth المميز بشهادة عميل. الشهادة هي بيانات اعتماد على طبقة الشبكة، منفصلة عن مصادقة طبقة التطبيق في طلبك. هذا التمييز مهم في Apidog، وهو ما يقع الناس في حيرة منه غالبًا. تتعامل الشهادات مع mTLS. يتعامل تبويب التخويل (Authorization) مع مفاتيح API، ورموز الحامل المميزة، وOAuth، والمصادقة الأساسية. غالبًا ما تحتاج إلى كليهما في وقت واحد، ولكنك تقوم بتكوينهما في أماكن مختلفة.
كيف يحدد Apidog نطاق الشهادات حسب المضيف
يتعامل Apidog مع كل من شهادات المرجع المصدق (CA) وشهادات العميل، ويقوم بتكوينها عالميًا بدلاً من كل طلب على حدة. تقوم بإعداد الشهادة مرة واحدة، وتربطها بمضيف، ويقوم Apidog بإرفاقها تلقائيًا بكل طلب HTTPS يتطابق مع هذا المضيف. لا يوجد تبديل لكل طلب لتتذكره ولا رأس لتقوم بلصقه.
نوعان من الشهادات يقومان بوظيفتين مختلفتين:
- **شهادة العميل** هي ما تقدمه لإثبات هويتك لمصادقة TLS المتبادل. إنها الاعتماد الذي تطلبه واجهة برمجة تطبيقات الشريك.
- **شهادة المرجع المصدق (CA)** تخبر Apidog بالوثوق في سلطة إصدار شهادات لا يعرفها بالفعل. وجهها إلى الجذر المصدق الداخلي الخاص بك وستختفي رسالة
SSL Error: Self signed certificateالمخيفة، لأن Apidog يثق الآن بنقاط النهاية الموقعة من قبل تلك السلطة.
مفتاح النطاق هو المضيف. كل شهادة عميل مرتبطة بنطاق، ويطابق Apidog مضيف الطلب الصادر مع هذا الربط. إذا قمت بتعيين المضيف بشكل صحيح، فكل شيء آخر يكون تلقائيًا. إذا أخطأت، يرسل Apidog لا شيء بصمت، لأنه لم يعثر على تطابق أبدًا.
إعداد شهادة عميل لواجهة برمجة تطبيقات mTLS
هذا هو السيناريو. أصدر شريك مدفوعات، partner-api.acmebank.com، لك شهادة عميل ومفتاحًا خاصًا أثناء الإعداد. واجهة برمجة التطبيقات الخاصة بهم تعمل عبر HTTPS فقط وترفض أي عميل لا يمكنه تقديم تلك الشهادة. تريد استدعاء GET /v1/settlements وفحص الاستجابة.
الخطوة 1: افتح إعدادات الشهادات
افتح إعدادات Apidog باستخدام أيقونة الإعدادات في أعلى اليمين، ثم انتقل إلى تبويب الشهادات. هنا توجد أنواع الشهادات. لا يرتبط أي شيء هنا بطلب واحد؛ بل ينطبق على جميع طلباتك بناءً على مطابقة المضيف.
الخطوة 2: إضافة شهادة العميل
ضمن شهادات العميل، حدد إضافة شهادة. سيتم فتح نموذج لربط المضيف وملفات الشهادة.
املأ حقل المضيف (Host) بالنطاق فقط، بدون بروتوكول:
partner-api.acmebank.com
اترك https://. يقبل الحقل نطاقًا مجردًا. إذا كنت بحاجة إلى شهادة واحدة لتغطية عدة نطاقات فرعية، فإن حقل المضيف يدعم مطابقة الأنماط. يؤدي إدخال *.acmebank.com إلى استخدام نفس شهادة العميل لكل نطاق فرعي ضمن acmebank.com، وهو أمر مفيد عندما يقوم الشريك بتشغيل partner-api و sandbox-api و settlements-api من نفس الشهادة الصادرة.
المنفذ المخصص اختياري. اتركه فارغًا وسيستخدم Apidog المنفذ الافتراضي 443، وهو منفذ HTTPS القياسي. لا تقم بتعيين منفذ إلا إذا كانت نقطة نهاية mTLS تستمع في مكان آخر، على سبيل المثال 8443.
الخطوة 3: حدد ملفات الشهادة
يقبل Apidog تنسيقين للملفات لشهادة العميل. اختر أيًا منهما قدمه لك شريكك:
- **ملفات CRT + المفتاح.** ملف شهادة منفصل وملف مفتاح خاص. حدد كل واحد في حقله.
- **ملفات PFX.** ملف واحد مجمع يجمع الشهادة والمفتاح معًا.
إذا تم إنشاء الشهادة باستخدام عبارة مرور، أدخلها في حقل عبارة المرور (passphrase). إنه اختياري، لذا اتركه فارغًا إذا لم يكن مفتاحك محميًا بكلمة مرور. عادةً ما يتم شحن حزمة إعداد من بنك كزوج من ملفات .crt و .key، وأحيانًا مع عبارة مرور على المفتاح.
الخطوة 4: احفظه
حدد إضافة (Add) لحفظ شهادة العميل. ستظهر الآن في قائمتك، مرتبطة بـ partner-api.acmebank.com. من هذه النقطة فصاعدًا، لن تحتاج إلى لمسها مرة أخرى لكل طلب.
الخطوة 5: أرسل الطلب المصادق عليه
قم بإنشاء طلب إلى المضيف وأرسله:
GET https://partner-api.acmebank.com/v1/settlements
Authorization: Bearer <your_oauth_token>
يطابق Apidog المضيف، ويرفق شهادة العميل الخاصة بك أثناء مصافحة TLS، ويكمل مصادقة TLS المتبادل قبل إرسال الطلب. إذا كان الشريك يتطلب OAuth أيضًا، فإن رمز الحامل هذا يتم إرساله في الطلب كالمعتاد. تثبت الشهادة الجهاز؛ ويثبت الرمز المميز المتصل. قد تبدو الاستجابة الناجحة كما يلي:
{
"settlements": [
{
"id": "stl_88213",
"amount": 41200,
"currency": "USD",
"status": "cleared",
"settled_at": "2026-07-14T09:31:00Z"
}
],
"next_cursor": null
}
لم تحدث أي خطوة يدوية لكل طلب ذلك. بل مطابقة المضيف هي التي قامت بذلك.
إضافة شهادة مرجع مصدق (CA) للجذور الداخلية أو ذاتية التوقيع
شهادات العميل هي نصف القصة. يظهر النصف الآخر عندما تكون شهادة الخادم نفسها موقعة من قبل سلطة لا يثق بها جهازك، وهو أمر شائع في الخدمات الداخلية وبيئات الاختبار التي تستخدم مرجعًا مصدقًا جذريًا خاصًا.
عندما يحدث ذلك، يفشل الطلب برسالة مثل SSL Error: Self signed certificate قبل أن تتاح لـ mTLS أي فرصة. الحل هو تزويد Apidog بالمرجع المصدق (CA) حتى يثق بهذا الجذر.
في نفس تبويب الشهادات، قم بتشغيل المفتاح بجوار شهادات المرجع المصدق (CA Certificates)، ثم حدد ملف PEM الخاص بك. تستخدم شهادات المرجع المصدق (CA) تنسيق PEM، ويمكن لملف PEM واحد أن يحتوي على عدة شهادات مرجع مصدق (CA)، بحيث يمكنك تجميع سلسلة كاملة من الجذور الداخلية والوسطاء في ملف واحد:
-----BEGIN CERTIFICATE-----
MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQG...
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
MIIEFTCCAv2gAwIBAgIQeM8V5x8B3QksZ4 b2VqkJTANBgkqhkiG9w0BAQ...
-----END CERTIFICATE-----
بمجرد الوثوق بالمرجع المصدق (CA)، يتوقف Apidog عن رفض نقاط النهاية الموقعة بواسطته. قم بإقران مرجع مصدق موثوق به بشهادة عميل، ويمكنك اختبار خدمة mTLS داخلية تستخدم جذرًا خاصًا من البداية إلى النهاية: يسمح لك المرجع المصدق (CA) بالوثوق بخادمهم، وتسمح لهم شهادة العميل بالوثوق بك.
نصائح متقدمة واختلافات شائعة
بعض الأمور توفر الوقت بمجرد تجاوز الإعداد الأساسي.
- **تغطية النطاقات الفرعية بشهادة واحدة.** إذا أصدر شريك شهادة بنطاق عام (wildcard)، قم بتعيين المضيف إلى
*.acmebank.comمرة واحدة بدلاً من تسجيلpartner-api،sandbox-api، والباقي بشكل منفصل. ربط واحد، لكل نطاق فرعي. - **المنافذ غير القياسية.** تفضل بوابات mTLS الداخلية منافذ مثل
8443أو9443. الافتراضي هو443، لذا حدد المنفذ المخصص عندما تستمع نقطة النهاية في مكان آخر، وإلا فلن يتطابق المضيف ولن يتم إرسال أي شهادة. - **الشهادات غير قابلة للتحرير بعد إضافتها.** لا يوجد إجراء تعديل. لتدوير شهادة مجددة أو إصلاح خطأ إملائي في المضيف، قم بإزالة الشهادة الحالية باستخدام أيقونة الحذف وأضفها مرة أخرى. قم ببناء ذلك ضمن دليل تشغيل تدوير الشهادات الخاص بك حتى لا يبحث أحد عن زر تعديل غير موجود.
- **شهادة واحدة لكل نطاق.** لا تسجل شهادتين عميل لنفس النطاق. كل ربط خاص بالنطاق، ويخلق التكرار غموضًا حول أي شهادة يجب أن يقدمها Apidog. حافظ على شهادة واحدة لكل مضيف.
- **حافظ على فصل الشهادات والتخويل في ذهنك.** هذا هو أكبر مصدر للارتباك. يعيش mTLS في تبويب الشهادات. تعيش مفاتيح API، ورموز الحامل المميزة، وOAuth، والمصادقة الأساسية في تبويب التخويل (Authorization) لطلب أو مجلد، وترث الطلبات التخويل من مجلدها الأصلي. ينطبق التخويل على ثلاثة مستويات: الطلبات الفردية، وجميع الطلبات في مجلد، وجميع الطلبات في مجموعة. إذا احتاج شريك إلى شهادة عميل وOAuth معًا، فإنك تقوم بتعيين الشهادة في الشهادات والرمز المميز في التخويل. لا يتداخلان. للحصول على نظرة أعمق حول ربط المصادقة القائمة على الرموز المميزة، يغطي دليل مصادقة بوابة API جانب الطلب، وإذا كنت تتعامل مع نظام تشغيل يعتمد على Windows بشكل كبير، فإن تكوين مصادقة Kerberos في Apidog هو دليل مصاحب يستحق الإشارة إليه.
- **HTTPS فقط، دائمًا.** لن يرفق Apidog شهادة عميل بطلب HTTP عادي. إذا كان هدف الاختبار
http://، فلن يتم إرسال الشهادة أبدًا ولن يتم تشغيل منطق المصافحة أبدًا. يجب أن تكون نقطة النهاية HTTPS لكي ينطبق أي من هذا.
أتمتة سير العمل باستخدام سطر أوامر Apidog (CLI)
بمجرد أن تتم طلبات mTLS يدويًا، قم بدمجها في سيناريوهات اختبار محفوظة وتشغيلها بدون واجهة مستخدم رسومية (headless) باستخدام سطر أوامر Apidog (CLI). قم بتثبيته والمصادقة:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
ثم قم بتشغيل سيناريو محفوظ مقابل بيئة:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
يدعم أمر apidog run تكوين شهادة العميل مباشرةً، لذلك يبقى mTLS ساريًا عند الانتقال من واجهة المستخدم الرسومية (GUI) إلى مسار الأتمتة (pipeline). بالنسبة لشهادة واحدة، قم بتمرير --ssl-client-cert (شهادة PEM)، و--ssl-client-key (المفتاح الخاص)، و--ssl-client-passphrase إذا كان المفتاح يحتوي على واحدة. وجه --ssl-extra-ca-certs إلى سلطات إصدار الشهادات الموثوقة الإضافية، أو استخدم --ssl-client-cert-list مع ملف تكوين عندما تطابق الشهادات بالمضيفين بواسطة نمط URL. يتم تعيين التقارير باستخدام -r (جرب -r html,cli). قم بربط هذا الأمر بوظيفة ويتم اختبار واجهة برمجة التطبيقات المحمية بشهادتك مع كل عملية دفع. يغطي دليل Apidog CLI في CI/CD تشغيله داخل مسار الأتمتة.
الأسئلة المتكررة
هل أحتاج إلى شهادة عميل وشهادة مرجع مصدق (CA)، أم واحدة فقط؟
يعتمد ذلك على نقطة النهاية. تثبت شهادة العميل هويتك، لذا فأنت بحاجة إليها كلما طلب الخادم TLS المتبادل. لا تلزم شهادة المرجع المصدق (CA) إلا عندما تكون شهادة الخادم نفسه موقعة من قبل سلطة لا يثق بها جهازك بالفعل، مثل مرجع مصدق جذري داخلي. واجهة برمجة تطبيقات شريك عامة على مرجع مصدق عام موثوق به تحتاج فقط إلى شهادة العميل؛ خدمة mTLS داخلية على جذر خاص عادة ما تحتاج إلى كليهما.
لماذا لا يرسل Apidog شهادة العميل الخاصة بي؟
دائمًا تقريبًا يكون السبب هو عدم تطابق المضيف أو هدف HTTP عادي. تحقق من أن حقل المضيف (Host) يحتوي على النطاق الدقيق بدون بادئة https://، وأن المنفذ يتطابق (الافتراضي 443، لذا قم بتعيين منفذ مخصص إذا كانت نقطة النهاية تستمع في مكان آخر)، وأن عنوان URL للطلب هو HTTPS. لا يرفق Apidog شهادة بطلب HTTP أبدًا.
أين تذهب مفاتيح API ورموز الحامل المميزة إذا لم تكن في الشهادات؟
في تبويب التخويل (Authorization) للطلب أو المجلد، وهو منفصل عن إعداد الشهادة. تتعامل الشهادات مع هوية طبقة TLS؛ يتعامل التخويل (Authorization) مع مفتاح API، ورمز الحامل المميز، وOAuth، والمصادقة الأساسية على طبقة الطلب. يمكنك العثور على التفاصيل الكاملة لأنواع المصادقة في دليل مخططات الأمان، ويمكنك تعيين المصادقة مرة واحدة على مستوى المجلد أو المجموعة بحيث يرثها كل طلب.
هل يمكن لشهادة واحدة تغطية نطاقات فرعية متعددة؟
نعم. يدعم حقل المضيف مطابقة الأنماط. أدخل *.example.com وستنطبق نفس شهادة العميل على كل نطاق فرعي من example.com. هذه هي الطريقة النظيفة لإعادة استخدام شهادة بنطاق عام (wildcard) أصدرها شريك لعدة نطاقات فرعية لواجهات برمجة التطبيقات الخاصة بهم.
كيف أقوم بتحديث شهادة بعد إضافتها؟
الشهادات غير قابلة للتحرير في مكانها. قم بإزالة الشهادة الموجودة باستخدام أيقونة الحذف، ثم أضف الإصدار المصحح أو المجدد. ضع ذلك في اعتبارك لتدوير الشهادات، وبينما تقوم بتنظيم إعدادات الاختبار، فإن تعيين المعلمات العالمية في Apidog يتناسب جيدًا للحفاظ على قيم البيئة مرتبة عبر الطلبات.
الخلاصة
يعتمد اختبار واجهة برمجة تطبيقات محمية بتقنية mTLS على ثلاث خطوات في Apidog: ربط شهادة العميل بالمضيف الصحيح، إرفاق شهادة مرجع مصدق (CA) إذا كان الخادم يستخدم جذرًا خاصًا، وترك مطابقة المضيف توقع كل طلب HTTPS تلقائيًا. حافظ على الشهادات والتخويل في مساراتهما المنفصلة وستتوقف المصافحة عن أن تكون لغزًا.
قم بتنزيل Apidog للمتابعة، وإضافة شهادة شريكك، وإرسال هذا الطلب المصادق عليه الأول. جربه مجانًا، لا يلزم وجود بطاقة ائتمان.