كيفية اختبار OAuth 2.0 APIs في Apidog: تدفق رمز التخويل، بيانات اعتماد العميل، تحديث التوكن

اختبار مصادقة OAuth 2.0 في واجهات برمجة التطبيقات باستخدام Apidog

يواجه كل فريق واجهة برمجة تطبيقات (API) المشكلة نفسها: تعمل نقاط النهاية بشكل مستقل، ثم تُضاف مصادقة OAuth 2.0 وتبدأ نصف اختباراتك بإرجاع أخطاء 401. بعدها تجد نفسك تتعامل مع خوادم التخويل، ورموز الوصول قصيرة الأجل، والنطاقات، ونسخ الرموز يدويًا من استجابة curl إلى حقل الرأس.

جرّب Apidog اليوم

الحل ليس تجاوز المصادقة، بل جعل إدارة الرموز جزءًا من إعداد الاختبار. يشرح هذا الدليل تدفقين شائعين:

• رمز التخويل مع PKCE لواجهات برمجة التطبيقات التي تعمل نيابةً عن مستخدم.
• بيانات اعتماد العميل للاتصالات من جهاز إلى جهاز.

للاطلاع على جميع المنح أولًا، راجع نظرة عامة على تدفقات OAuth 2.0.

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

التدفقان المهمان لاختبار واجهة برمجة التطبيقات

يحدد OAuth 2.0 عدة أنواع من المنح، لكنك ستستخدم غالبًا نوعين في الاختبارات اليومية. يعتمد الاختيار على سؤال واحد:

هل تعمل واجهة برمجة التطبيقات نيابةً عن مستخدم أم نيابةً عن خدمة؟

تدفق رمز التخويل مع PKCE

تدفق رمز التخويل هو الطريقة القياسية للحصول على رمز مرتبط بمستخدم:

1. يرسل العميل المستخدم إلى خادم التخويل.
2. يسجّل المستخدم الدخول ويوافق على الصلاحيات.
3. يعيد خادم التخويل التوجيه برمز تخويل مؤقت.
4. يستبدل العميل الرمز برمز وصول عند نقطة نهاية الرموز.

يحدد 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 [REDACTED CREDENTIAL] \
  -d scope="orders:read orders:write"

استخدمه مع:

• الخدمات المصغرة الداخلية.
• مهام cron.
• خطوط أنابيب CI التي تستدعي واجهة برمجة تطبيقات النشر.
• الاختبارات الآلية التي لا تتطلب تفاعلًا بشريًا.

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

تهيئة OAuth 2.0 في Apidog

يقدم Apidog OAuth 2.0 كنوع مصادقة أساسي. تهيّئه مرة واحدة في علامة تبويب المصادقة لطلب أو مجلد، ثم تتولى المنصة جلب الرموز وإرفاقها وتحديثها.

تشمل أنواع المنح المدعومة:

• رمز التخويل.
• رمز التخويل مع PKCE.
• بيانات اعتماد العميل.
• بيانات اعتماد كلمة المرور.
• Implicit.

إعداد بيانات اعتماد العميل

افتح الطلب، أو المجلد ويفضل استخدامه كما سنوضح لاحقًا، ثم:

1. غيّر نوع المصادقة إلى OAuth 2.0.
2. اختر Client Credentials.
3. أدخل القيم التالية:

• عنوان URL لرمز الوصول (Access Token URL): https://auth.example.com/oauth/token
• معرف العميل (Client ID): orders_service
• سر العميل (Client Secret): السر المخصص لك
• النطاق (Scope): orders:read orders:write ضمن الخيارات المتقدمة

يمكنك إرسال بيانات الاعتماد بطريقتين:

• كرأس Basic Auth.
• داخل نص الطلب.

اختر الطريقة التي يتوقعها خادم التخويل. يدعم كل من Auth0 وOkta الطريقتين، بينما قد تحلل بعض الخوادم الداخلية نص الطلب فقط.

اضغط احصل على الرمز (Get Token). يستدعي Apidog نقطة نهاية الرموز، ويخزن النتيجة، ويعرض الرمز وفترة صلاحيته. بعد ذلك يرفق الرمز تلقائيًا بكل طلب داخل رأس:

[REDACTED CREDENTIAL] <access_token>

لا حاجة إلى نسخ الرمز ولصقه أو إنشاء متغير مثل {{token}}.

إعداد رمز التخويل مع PKCE

لاختبار سياق المستخدم:

1. اختر Authorization Code (with PKCE).
2. أدخل الحقول التالية:

• عنوان 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

في Apidog، PKCE نوع من أنواع المنح، وليس مربع اختيار منفصلًا.

اضغط احصل على الرمز (Get Token) لفتح نافذة متصفح إلى صفحة تسجيل الدخول. سجّل الدخول باستخدام مستخدم الاختبار، ووافق على الصلاحيات، ثم يعود الرمز إلى Apidog ويُحفظ في نفس المساحة المُدارة.

إذا أعاد مزود الخدمة رمز تعريف OpenID Connect إلى جانب رمز الوصول، يتيح لك خيار نوع الرمز المستخدم (Token Type Used) تحديد الرمز الذي سيُرفق بالطلب. يفيد ذلك عند اختبار واجهات برمجة التطبيقات التي تتحقق من رموز التعريف.

استخدم مستخدم اختبار مستقلًا لكل دور تحتاج إلى تغطيته، مثل:

• المشتري.
• المسؤول.
• المدقق للقراءة فقط.

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

إعادة استخدام الرمز والتحديث التلقائي

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

يحدّث Apidog رموز OAuth 2.0 تلقائيًا عندما يعيد خادم التخويل رمز تحديث. أُضيفت هذه القدرة في تحديث يونيو.

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

أما مع بيانات اعتماد العميل، فتتجاهل خوادم كثيرة رموز التحديث؛ تسمح المواصفات بذلك لأن العميل يستطيع إعادة المصادقة في أي وقت. عمليًا، يكفي الضغط على احصل على الرمز (Get Token) مرة أخرى. كما يمكن للتشغيلات المجدولة أو CI طلب رمز جديد في بداية كل تشغيل.

وراثة المصادقة على مستوى المجلد

تهيئة OAuth لكل طلب على حدة تكرار غير ضروري. بدلًا من ذلك، عيّن المصادقة على مجلد، وستَرث الطلبات الموجودة داخله الإعداد من المجلد الأم.

مثلًا، عيّن OAuth 2.0 مرة واحدة على مجلد Orders API. بعد ذلك تستخدم كل الطلبات الحالية والجديدة تحته الرمز المُدار نفسه.

يفيد ذلك خصوصًا في السيناريوهات متعددة الخطوات، مثل:

POST /carts
POST /carts/{id}/items
POST /orders

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

يمكن لأي طلب تجاوز إعداد المجلد الأم، وهو ما تحتاج إليه عند بناء اختبارات المسار السلبي.

اختبار مسارات الفشل

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

راجع مقارنة مفاتيح API ورموز الحامل لتفسير رموز الحالة ذات الصلة.

رمز مفقود أو منتهي الصلاحية: توقع 401

كرّر طلبًا في السيناريو، وتجاوز المصادقة الموروثة باستخدام أحد الخيارين:

• عدم إرسال مصادقة.
• إرسال رمز ثابت ومنتهٍ منذ فترة طويلة:

Bearer [REDACTED]

تحقق من الآتي:

• رمز الحالة يساوي 401.
• وجود رأس الاستجابة WWW-Authenticate.
• عدم تسريب تتبع المكدس أو أسماء المضيف الداخلية في الرسالة.

إذا أعادت الواجهة 200 فهذه مشكلة حرجة. أما إعادة 403 بدلًا من 401 فهي مؤشر على تصميم غير دقيق؛ يجب أن يميز الخادم بين:

• «لا أعرف من أنت».
• «أعرفك، لكن لا أسمح لك».

نطاق غير صحيح: توقع 403

أنشئ عميل اختبار ثانيًا يملك النطاق orders:read فقط. اجلب رمزه، ثم استدعِ نقطة كتابة مثل:

POST /orders

تحقق من:

• رمز الحالة 403.
• احتواء رأس WWW-Authenticate على error="insufficient_scope" إذا كانت الواجهة تتبع RFC 6750.

يكشف هذا الاختبار أخطاء التكوين التي تؤدي إلى التحقق من النطاقات لبعض المسارات ونسيانها في مسارات أخرى. لمعرفة كيفية تقسيم النطاقات، راجع شرح نطاقات OAuth 2.0.

عميل غير صالح: توقع خطأ واضح من نقطة نهاية الرموز

أرسل طلبًا مباشرًا إلى:

https://auth.example.com/oauth/token

مع قيمة مزيفة لـ client_secret.

وفقًا للقسم 5.2 من RFC 6749، يجب أن يعيد الخادم 400، أو 401 عند فشل مصادقة العميل، مع نص JSON يتضمن:

{
  "error": "invalid_client"
}

تحقق من رمز الحالة ومن محتوى JSON. خادم التخويل هو واجهة برمجة تطبيقات أيضًا، وعقد الأخطاء الخاص به جزء من سطح الاختبار.

تأكيد استجابات نقطة نهاية الرموز

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

• access_token موجود وغير فارغ.
• token_type يساوي bearer، مع تجاهل حالة الأحرف وفقًا للمواصفات.
• expires_in أكبر من 0 وضمن سياستك، مثل ألا يتجاوز 3600.
• scope يطابق النطاق المطلوب، لكشف الخوادم التي تضيق المنح بصمت.

تتيح لك سيناريوهات اختبار Apidog إضافة هذه التأكيدات إلى استجابة JSON دون كتابة نصوص برمجية. ويمكنك أيضًا استخراج access_token إلى متغير لخطوة لاحقة عندما تريد اختبار المصافحة الخام بدلًا من المصادقة المُدارة.

اربط السيناريو بتشغيل CI، بحيث يؤدي خادم التخويل غير المتوافق إلى فشل البناء بدلًا من الظهور لاحقًا كخطأ 401 غامض في الإنتاج.

إعداد اختبار عملي كامل

يبدو الإعداد الكامل كالتالي:

1. تهيئة OAuth 2.0 على مستوى المجلد للمسار السعيد.
2. إضافة تجاوزات على مستوى الطلب لاختبارات 401 و403.
3. إضافة سيناريو مستقل للتحقق من عقد نقطة نهاية الرموز.
4. استخدام رمز التخويل مع PKCE لواجهات برمجة التطبيقات ذات سياق المستخدم.
5. استخدام بيانات اعتماد العميل للاتصالات من خدمة إلى خدمة.
6. تفعيل تحديث الرموز عند توفر رمز تحديث.

قم بتنزيل 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؟

أعد 401 عند فشل المصادقة، مثل:

• رمز مفقود.
• رمز منتهي الصلاحية.
• رمز مشوه أو غير صالح.

وأعد 403 عندما يكون الرمز صالحًا، لكنه لا يملك الإذن المطلوب، مثل غياب نطاق معين.

الخلط بين الحالتين يفسد منطق إعادة محاولة العميل: تخبر 401 العميل بإعادة المصادقة، بينما تخبره 403 بالتوقف. لمزيد من التفاصيل حول التحقق من صحة الرمز، راجع دليل اختبار مصادقة JWT.