يواجه كل فريق واجهة برمجة تطبيقات (API) نفس الجدار. تعمل نقاط النهاية بشكل منعزل، ثم يقوم شخص ما بتشغيل OAuth 2.0 ويبدأ نصف مجموعة الاختبار في إرجاع أخطاء 401. فجأة، تجد نفسك تتعامل مع خوادم التخويل، ورموز الوصول قصيرة الأجل، والنطاقات، ويصبح نسخ الرموز يدويًا من استجابة `curl` إلى حقل الرأس أمرًا قديمًا بعد التشغيل الثالث.
الحل ليس تخطي المصادقة في اختباراتك. إنه جعل معالجة الرموز جزءًا من إعداد الاختبار بحيث تتوقف عن أن تكون عملاً يدويًا. يغطي هذا الدليل التدفقين اللذين ستجدهما في كل خطة اختبار تقريبًا: تدفق رمز تخويل OAuth (مع PKCE) لواجهات برمجة التطبيقات التي تعمل نيابة عن مستخدم، وتدفق بيانات اعتماد العميل للمكالمات من جهاز إلى جهاز. إذا كنت تريد الخريطة الكاملة للمنح أولاً، فإن نظرة عامة على تدفقات OAuth 2.0 الخاصة بنا تستعرضها جميعًا.
ثم ننتقل إلى التطبيق العملي: تهيئة مصادقة OAuth 2.0 في Apidog، وجلب رمز مرة واحدة وإعادة استخدامه عبر الطلبات، والسماح للرموز المنتهية الصلاحية بالتحديث تلقائيًا، ووراثة المصادقة على مستوى المجلد، واختبار مسارات الفشل التي ستطلبها مراجعة الأمان الخاصة بك.
التدفقان المهمان لاختبار واجهة برمجة التطبيقات
يحدد OAuth 2.0 عدة أنواع من المنح، ولكن لاختبار واجهة برمجة التطبيقات اليومي، ستقضي معظم وقتك مع اثنين منها. اختر بناءً على سؤال واحد: هل تعمل واجهة برمجة التطبيقات نيابة عن مستخدم، أم نيابة عن خدمة؟
تدفق رمز التخويل، مع PKCE
تدفق رمز التخويل هو الطريقة القياسية للحصول على رمز مرتبط بمستخدم. يرسل العميل المستخدم إلى خادم التخويل، يقوم المستخدم بتسجيل الدخول والموافقة، يعيد الخادم التوجيه برمز لمرة واحدة، ويقوم العميل بتبديل الرمز برمز وصول عند نقطة نهاية الرمز. يحدد RFC 6749 العملية بأكملها في القسم 4.1.
يعزز PKCE (مفتاح الإثبات لتبادل الرموز، RFC 7636) عملية التبادل. ينشئ العميل مدققًا عشوائيًا، ويرسل تحديًا مشفرًا مع طلب التخويل، ثم يثبت أنه يحمل المدقق الأصلي عند استرداد الرمز. لا يمكن للمهاجم الذي يعترض الرمز استخدامه. بدأ PKCE كتصحيح لتطبيقات الأجهزة المحمولة، ولكن الإرشادات الحالية من oauth.net توصي به لكل تبادل لرمز التخويل، بما في ذلك العملاء السريين.
اختبر باستخدام هذا التدفق كلما كان سلوك نقطة النهاية يعتمد على هوية المستخدم: `GET /orders` الذي يعيد فقط طلبات المتصل، أو نقاط نهاية الإدارة المقيدة بالأدوار، أو حدود المعدل لكل مستخدم.
تدفق بيانات اعتماد العميل
تتخطى منحة OAuth 2.0 لبيانات اعتماد العميل المستخدم تمامًا. يصادق العميل بمعرف وكلمة مرور خاصة به ويتلقى رمزًا يمثل التطبيق نفسه. طلب POST واحد إلى نقطة نهاية الرمز، بدون متصفح، بدون إعادة توجيه:
curl -X POST https://auth.example.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=orders_service \
-d client_secret=s3cr3t_value \
-d scope="orders:read orders:write"
هذا هو التدفق لواجهات برمجة التطبيقات من جهاز إلى جهاز: الخدمات المصغرة الداخلية، مهام cron، خطوط أنابيب CI التي تستدعي واجهة برمجة تطبيقات النشر. وهو أيضًا أساس العمل للاختبار الآلي، لأنه لا يحتاج إلى تدخل بشري. إذا سمحت لك بيئة الاختبار الخاصة بك بتوفير عميل اختبار، فاستخدم بيانات اعتماد العميل لكل شيء باستثناء الحالات التي تكون فيها هوية المستخدم هي الشيء الذي يتم اختباره.
تهيئة مصادقة OAuth 2.0 في Apidog
يعتبر Apidog OAuth 2.0 نوعًا أساسيًا من المصادقة. تقوم بتهيئته مرة واحدة، في علامة تبويب المصادقة لطلب أو مجلد، وتتعامل المنصة مع جلب الرموز وإرفاقها وتحديثها. تشمل أنواع المنح المدعومة رمز التخويل، رمز التخويل (مع PKCE)، بيانات اعتماد العميل، بيانات اعتماد كلمة المرور، وImplicit.
إليك الإعداد للتدفقين المذكورين أعلاه، باستخدام واجهة برمجة تطبيقات وهمية لإدارة الطلبات.
إعداد بيانات اعتماد العميل
افتح الطلب (أو الأفضل، المجلد؛ المزيد عن هذا أدناه)، قم بتبديل نوع المصادقة إلى OAuth 2.0، واختر بيانات اعتماد العميل كنوع المنحة. املأ الحقول التالية:
- عنوان URL لرمز الوصول (Access Token URL):
https://auth.example.com/oauth/token - معرف العميل (Client ID):
orders_service - سر العميل (Client Secret): سرك المخصص
- النطاق (Scope):
orders:read orders:write(يتم تعيينه ضمن الخيارات المتقدمة)
يمنحك Apidog طريقتين لتسليم بيانات الاعتماد: كرأس Basic Auth أو في نص الطلب. طابق ما يتوقعه خادم التخويل الخاص بك؛ يقبل Auth0 و Okta كلاهما، لكن بعض الخوادم الداخلية تقوم فقط بتحليل النص.
انقر على احصل على الرمز (Get Token). يستدعي Apidog نقطة نهاية الرمز، ويخزن النتيجة، ويعرض الرمز جنبًا إلى جنب مع فترة صلاحيته. بعد ذلك، يرفق كل إرسال الرمز برأس `Authorization` مع البادئة `Bearer`. لا يوجد نسخ ولصق، ولا توجد أسلاك لمتغير `{{token}}`.
إعداد رمز التخويل مع PKCE
لاختبار سياق المستخدم، اختر رمز التخويل (مع PKCE) كنوع المنحة. PKCE هو خيار منح خاص به في Apidog، وليس مربع اختيار. ستحتاج إلى المزيد من الحقول:
- عنوان URL للمصادقة (Auth URL):
https://auth.example.com/oauth/authorize - عنوان URL لرمز الوصول (Access Token URL):
https://auth.example.com/oauth/token - عنوان URL لرد الاتصال (Callback URL): عنوان URI لإعادة التوجيه المسجل لدى مزود الخدمة الخاص بك
- معرف العميل (Client ID) و سر العميل (Client Secret): من تسجيل تطبيق OAuth الخاص بك
انقر على احصل على الرمز (Get Token) ويفتح Apidog نافذة متصفح تشير إلى صفحة تسجيل الدخول. قم بتسجيل الدخول كمستخدم الاختبار الخاص بك، وافق على شاشة الموافقة، ويعود الرمز ويهبط في نفس الفتحة المدارة كما كان من قبل. إذا أعاد مزود الخدمة رمز تعريف OpenID Connect جنبًا إلى جنب مع رمز الوصول، فإن خيار "نوع الرمز المستخدم" (Token Type Used) يتيح لك التبديل بين الرمز الذي يتم إرفاقه؛ وهو مفيد عندما تتحقق واجهة برمجة التطبيقات التي يتم اختبارها من رموز التعريف.
نصيحة عملية واحدة: احتفظ بمستخدم اختبار مخصص لكل دور تحتاج إلى تغطيته (مشتري، مسؤول، مدقق للقراءة فقط). إن جلب رمز ككل مستخدم وإعادة تشغيل نفس السيناريو هو أسرع طريقة للتحقق من قواعد الوصول المستندة إلى الدور.
إعادة استخدام الرمز والتحديث التلقائي
تنتهي صلاحية رموز الوصول، عادة في غضون ساعة. قبل أن يتعامل Apidog مع هذا، كان الرمز المنتهي الصلاحية يعني فشل التشغيل وإعادة جلب يدوي، وهو بالضبط نوع الفشل المتقطع الذي تتعلم الفرق تجاهله.
الآن يقوم Apidog بتحديث رموز OAuth 2.0 تلقائيًا عندما يصدر خادم التخويل رمز تحديث، وهي قدرة تم شحنها في تحديث يونيو. عندما تنتهي صلاحية رمز الوصول المخزن، يستخدم Apidog رمز التحديث للحصول على رمز جديد ويبادله قبل الإرسال. يمكنك أيضًا توجيهه إلى عنوان URL مخصص لرمز التحديث في الإعدادات المتقدمة إذا كان مزود الخدمة الخاص بك يفصل بين نقطتي النهاية.
بالنسبة لبيانات اعتماد العميل، تتخطى العديد من الخوادم رموز التحديث تمامًا (تسمح المواصفات بذلك، حيث يمكن للعميل إعادة المصادقة في أي وقت). في الممارسة العملية، هذا لا يضر: إعادة الجلب باستخدام احصل على الرمز (Get Token) هو بنقرة واحدة، ويمكن للتشغيلات المجدولة أو CI أن تطلب رمزًا جديدًا في بداية كل تشغيل.
وراثة المصادقة على مستوى المجلد
تهيئة OAuth على كل طلب هو مستوى خاطئ. يتيح لك Apidog تعيين المصادقة على مجلد، وترث الطلبات بداخله التهيئة من المجلد الأم. قم بتعيين OAuth 2.0 مرة واحدة على مجلد "Orders API" الخاص بك، وكل طلب تحته، بما في ذلك الطلبات الجديدة التي يضيفها زملاؤك في السباق القادم، يرسل نفس الرمز المدار.
هذا يهم بشكل خاص في سيناريوهات الاختبار متعددة الخطوات. قد يقوم سيناريو الدفع بسلسلة `POST /carts` و `POST /carts/{id}/items` و `POST /orders`. مع المصادقة على مستوى المجلد، تشارك جميع الخطوات الثلاث رمزًا واحدًا وتهيئة واحدة. عندما تنتهي صلاحية الرمز في منتصف السيناريو، يغطيها التحديث التلقائي. وعندما يقوم فريق الأمان بتدوير سر العميل، تقوم بتحديث مجلد واحد بدلاً من أربعين طلبًا.
تحتفظ الطلبات بخيار تجاوز المجلد الأم، وهو بالضبط ما تريده للاختبارات السلبية. المزيد عن هذه الآن.
اختبار مسارات الفشل
تثبت اختبارات OAuth ذات المسار السعيد أن عملية الرمز الخاصة بك تعمل. تثبت اختبارات مسار الفشل أن واجهة برمجة التطبيقات الخاصة بك تفرض المصادقة. تخطها وستعتمد على الإعدادات الافتراضية للإطار. إليك الحالات الثلاث التي تستحق الأتمتة؛ لتذكيرك بما يجب أن يعنيه كل رمز حالة، راجع مقارنتنا بين مفاتيح API ورموز الحامل.
رمز منتهي الصلاحية أو مفقود: توقع 401
كرر طلبًا واحدًا في السيناريو الخاص بك وتجاوز المصادقة الموروثة إما بعدم وجود مصادقة أو برمز حامل ثابت ومنتهي الصلاحية منذ فترة طويلة مثل `Bearer expired_token_do_not_rotate`. تحقق من:
- رمز الحالة يساوي
401 - رأس الاستجابة
WWW-Authenticateموجود (يتوقعه RFC 6750، الرفيق لـ RFC 6749) - الرسالة لا تسرب تتبعات المكدس أو أسماء المضيف الداخلية
الاستجابة 200 هنا هي خطأ حرج. الاستجابة 403 هي رائحة تصميم تستحق تذكرة: يجب أن يميز الخادم بين "أنا لا أعرف من أنت" و "أنا أعرفك، ولكن لا يسمح لك".
نطاق خاطئ: توقع 403
وفر عميل اختبار ثانيًا مقيدًا بـ `orders:read`، واجلب رمزه، واستدعِ نقطة نهاية الكتابة مثل `POST /orders`. تأكد من أن الحالة هي `403`، وإذا كانت واجهة برمجة التطبيقات الخاصة بك تتبع RFC 6750، فإن رأس `WWW-Authenticate` يتضمن `error="insufficient_scope"`. يلتقط هذا الاختبار التكوين الخاطئ الكلاسيكي حيث يتم التحقق من النطاقات عند البوابة لبعض المسارات وتُنسى في مسارات أخرى. إذا كانت النطاقات جديدة لفريقك، فإن شرح نطاقات OAuth 2.0 يغطي كيفية تقسيمها.
عميل غير صالح: توقع خطأ نظيفًا في نقطة نهاية الرمز
وجه طلبًا مباشرة إلى https://auth.example.com/oauth/token بـ client_secret مزيف. وفقًا للقسم 5.2 من RFC 6749، يجب أن يعيد الخادم 400 (أو 401 لمصادقة العميل الفاشلة) مع نص JSON يحتوي على "error": "invalid_client". تأكد من كليهما. خوادم التخويل هي واجهات برمجة تطبيقات أيضًا، وعقد الأخطاء الخاص بها هو جزء من سطحك.
التأكيد على استجابات الرمز في سيناريوهات الاختبار
تستحق نقطة نهاية الرمز تغطية خاصة بها تتجاوز حالة العميل غير الصالح. أضف خطوة في سيناريو الاختبار الخاص بك تستدعي نقطة نهاية الرمز مباشرة، ثم أرفق تأكيدات على الاستجابة:
access_tokenموجود وغير فارغtoken_typeيساويbearer(لا يراعي حالة الأحرف حسب المواصفات)expires_inأكبر من 0 وضمن سياستك، على سبيل المثال لا يزيد عن 3600scopeيطابق ما تم طلبه، ويلتقط الخوادم التي تضيق المنح بصمت
تتيح لك سيناريوهات اختبار Apidog إضافة هذه التأكيدات المرئية على استجابة JSON، دون الحاجة إلى برمجة نصية، ويمكنك استخراج access_token إلى متغير لخطوة متابعة عندما تريد اختبار المصافحة الخام بدلاً من استخدام المصادقة المدارة. قم بربط السيناريو بتشغيل CI الخاص بك، وعندها سيتسبب خادم تخويل سيء السلوك في فشل البناء بدلاً من الظهور كخطأ 401 غامض في الإنتاج.
تبدو الحلقة الكاملة هكذا: تهيئة OAuth 2.0 على مستوى المجلد للمسار السعيد، وتجاوزات لكل طلب لحالات 401 و 403، وسيناريو واحد يضرب عقد نقطة نهاية الرمز. يغطي هذا واجهات برمجة التطبيقات ذات السياق المستخدم من خلال رمز التخويل مع PKCE وواجهات برمجة التطبيقات من خدمة إلى خدمة من خلال بيانات اعتماد العميل، مع معالجة تحديث الرمز لك. قم بتنزيل Apidog وجربه مجانًا؛ يعمل نوع مصادقة OAuth 2.0 على الخطة المجانية، بحيث يمكنك توجيهه إلى نقطة نهاية الرمز الخاصة بك في بضع دقائق.
الأسئلة الشائعة
ما هو تدفق OAuth الذي يجب أن أستخدمه لاختبار واجهة برمجة التطبيقات؟
استخدم بيانات اعتماد العميل لأي شيء من جهاز إلى جهاز ولمعظم مجموعات الاختبار الآلية، لأنه لا يحتاج إلى تفاعل المتصفح. استخدم تدفق رمز التخويل مع PKCE عندما يعتمد الاختبار على هوية المستخدم: عزل البيانات لكل مستخدم، أو التحقق من الأدوار، أو سلوك الموافقة. تجنب منح Implicit و password في خطط الاختبار الجديدة؛ كلاهما غير محبذ في إرشادات OAuth الحالية.
كيف أقوم بتحديث رمز منتهي الصلاحية تلقائيًا في Apidog؟
قم بتهيئة OAuth 2.0 في علامة تبويب المصادقة واجلب رمزًا باستخدام "احصل على الرمز" (Get Token). عندما يعيد خادم التخويل رمز تحديث، يقوم Apidog بتحديث رمز الوصول عند انتهاء صلاحيته دون إعادة المصادقة منك، ويمكنك تعيين عنوان URL منفصل لرمز التحديث في الإعدادات المتقدمة إذا كان مزود الخدمة الخاص بك يستخدم واحدًا. بالنسبة لإعدادات بيانات اعتماد العميل بدون رموز تحديث، فإن إعادة تشغيل "احصل على الرمز" (Get Token) تصدر رمزًا جديدًا.
هل يمكن لكل طلب في سيناريو مشاركة رمز OAuth واحد؟
نعم. قم بتعيين تهيئة OAuth 2.0 على المجلد الأصل وترث الطلبات الموجودة بداخله التهيئة، بحيث يتم تشغيل سيناريو متعدد الخطوات تحت رمز مدار واحد. لا يزال بإمكان الطلبات الفردية تجاوز تهيئة المجلد، وهي الطريقة التي تضع بها الاختبارات السلبية (رمز منتهي الصلاحية، نطاق خاطئ) في نفس السيناريو.
ماذا يجب أن تعني الاستجابة 401 مقابل 403 في واجهات برمجة التطبيقات المحمية بـ OAuth؟
أعد 401 عندما تفشل المصادقة: الرمز مفقود، أو منتهي الصلاحية، أو مشوه. أعد 403 عندما يكون الرمز صالحًا ولكنه يفتقر إلى الإذن، مثل نطاق مفقود. الخلط بينهما يفسد منطق إعادة محاولة العميل، لأن 401 يخبر العميل بإعادة المصادقة بينما 403 يخبره بالتوقف. يتناول دليلنا حول اختبار مصادقة JWT التحقق من صحة الرمز نفسه.