Waafir
هذه الصفحة ترجمة آلية في انتظار المراجعة البشرية. قد تحتوي على أخطاء.

المصادقة

كل طلب /v1 تجري مصادقته. ومن أنظمتك الخاصة، صادِق باستخدام رمز وصول شخصي (PAT) يُرسَل بوصفه رمز bearer:

Authorization: Bearer waafir_pat_…

أصدر الرموز وقيّدها وألغها ضمن الإضافات ← الإعدادات. ويتناول دليل رموز الوصول الشخصية الإصدار، وانتهاء الصلاحية (90 يومًا افتراضيًا، و365 يومًا كحد أقصى)، والكشف لمرة واحدة، والإلغاء. وهذه القواعد هي نفسها بالنسبة إلى واجهة API للمنصة. وتتناول هذه الصفحة ما يمكن للرمز فعله بمجرد حصولك عليه.

يعمل رمز الوصول الشخصي بصفة الشخص الذي أصدره، داخل مؤسسة ذلك الشخص. ولا يوجد معامل للمؤسسة في أي عنوان URL أو جسم طلب، لأن الرمز يثبّتها مسبقًا.

فحوص الرمز الثلاثة

يجب أن يجتاز الطلب المُصادَق عليه برمز هذه الفحوص الثلاثة، من بين فحوص أخرى. ويمكن أيضًا لسياسة الأمان في المؤسسة وللفحوص الخاصة بنقطة النهاية رفضه (راجع أدناه). ولاثنين من الثلاثة رمز خاص بكلٍّ منهما. أما رفض الدور فقد يُجيب بـ FORBIDDEN، الذي تشترك فيه حالات رفض أخرى، لذا اقرأ الرمز مقرونًا بمتطلبات نقطة النهاية.

الفحصالسؤالالرفض
نطاق الرمزهل يغطي نطاق الرمز ما تفعله نقطة النهاية هذه؟PAT_SCOPE_INSUFFICIENT 403
الدورهل يحمل المستدعي الدور الذي تتطلبه نقطة النهاية هذه؟FORBIDDEN 403، أو PAT_ROLE_CEILING 403
غرفة البياناتبالنسبة إلى رمز مقيّد بغرف بيانات، هل غرفة البيانات هذه ضمن قائمته؟PAT_DATAROOM_SCOPE 403

نطاقات الرموز

يحمل الرمز نطاقًا واحدًا: read أو write أو admin، بترتيب تصاعدي للصلاحية. ويشمل النطاق الأعلى كل ما دونه.

يتبع النطاق الذي تحتاجه نقطة النهاية طريقةَ HTTP الخاصة بها افتراضيًا:

  • تحتاج GET وHEAD وOPTIONS إلى read.
  • تحتاج كل طريقة أخرى (POST، PATCH، PUT، DELETE) إلى write.

تعلن بعض نقاط النهاية نطاقًا مختلفًا. والحالة المعتادة هي POST لا يُنفّذ سوى استعلام، فلا يحتاج إلا إلى read. ويعرض مرجع نقاط النهاية النطاق الذي تتطلبه كل نقطة نهاية فعليًا، لذا تحقّق منه هناك بدلًا من استنتاجه من الطريقة.

الدور المطلوب وسقف الدور

يحدّد النطاق ما يجوز للرمز فعله. ويحدّد الدور المطلوب لنقطة النهاية من يجب أن يكون الشخص. تتطلب كثير من نقاط نهاية /v1 فريق الصفقة (مالك المؤسسة، أو مسؤول، أو عضو). وتتطلب التغييرات على الفريق وعلى منح الوصول، من بين أمور أخرى، مالكًا أو مسؤولًا. ولا يحمل المستثمرون والضيوف الآخرون أي دور في فريق الصفقة، لذا ترفضهم نقاط النهاية الخاصة بفريق الصفقة. وتعلن نقاط نهاية أخرى عدم وجود قيد دور في طبقة المصادقة وتتحقق من الوصول داخل نقطة النهاية بدلًا من ذلك. فعلى سبيل المثال، تتحقق مسارات مراقبة المحافظ من إضافة المراقبة ومن وصول المستدعي إلى المراقبة. ويعرض مرجع نقاط النهاية قيد الدور لكل نقطة نهاية. وحيث لا يُعلَن أي قيد، توقّع أن نقطة النهاية نفسها قد ترفض الطلب مع ذلك.

يسجّل الرمز أيضًا دور مُصدِره لحظة إصداره، بوصفه سقفًا. والدور الذي تطبّقه Waafir هو الأدنى بين الدور الحالي للمُصدِر وذلك السقف. فالعضو الذي يُرقّى لاحقًا إلى مسؤول يظل يعمل بصفة عضو عبر رمز صدر سابقًا؛ أصدر رمزًا جديدًا لاستخدام الدور الجديد. أما الشخص الذي يُخفَّض دوره فيفقد الصلاحية فورًا، أيًّا كان ما سجّله الرمز. ويُرفض أيٌّ من هذين القصورين بـ 403، بوصفه FORBIDDEN أو PAT_ROLE_CEILING.

الرموز المقيّدة بغرف بيانات

الرمز الذي يُصدَر مع تحديد غرف بيانات معيّنة، بدلًا من جميع غرف البيانات، لا يصل إلا إلى تلك الغرف. ويُرفض أي طلب يذكر غرفة بيانات أخرى بـ PAT_DATAROOM_SCOPE. وترفض بعض نقاط النهاية على مستوى المؤسسة الرمزَ المقيّد رفضًا قاطعًا، بالرمز نفسه، لأن إجابتها تمتد عبر غرف بيانات لا يستطيع الرمز رؤيتها. استخدم رمزًا غير مقيّد لتلك النقاط. ويقبل GET /api/v1/session كلا النوعين.

حالات رفض أخرى قد تواجهها

  • 401 UNAUTHORIZED: لا توجد ترويسة Authorization، أو الرمز غير معروف أو منتهي الصلاحية أو ملغى.
  • 404 لمورد يخص مؤسسة أخرى. يُعامَل المعرّف الذي ينتمي إلى مؤسسة أخرى على أنه غير موجود، فلا يُؤكَّد وجوده.
  • لا تجاوز للمالك/المسؤول على الملفات المقيّدة. في التطبيق، يرى مالك المؤسسة أو مسؤولها كل ملف مقيّد. أما الرمز فلا: إذ لا يصل إلى ملف مقيّد إلا إذا كان مالكه هو من أنشأه أو كان يحمل منحة وصول عليه. والطلب الذي يذكر ملفًا لا يستطيع قراءته يتلقى الإجابة نفسها التي يتلقاها ملف غير موجود (بالنسبة إلى /api/v1/grants، رمز 400 يذكر الملف، أو 404 لمنحة الوصول)، مع رسالة تقول إنه "not found, or not readable by this credential"، فلا تؤكد الإجابة أبدًا وجود الملف.
  • سياسة الأمان في المؤسسة. إذا كانت لدى مؤسستك قائمة عناوين IP مسموح بها، فإن الطلب الوارد من خارجها يُجاب بـ IP_BLOCKED. وقد يُجيب فرض المصادقة الثنائية بـ MFA_SETUP_REQUIRED أو MFA_CHALLENGE_REQUIRED.
  • 429 RATE_LIMITED. تعلن بعض نقاط النهاية سقفًا في الدقيقة لكل هوية، معروضًا على نقطة النهاية. وتستخدم البقية الإعداد الافتراضي للمنصة. تمهّل ثم أعد المحاولة.

تسرد صفحة رموز الأخطاء الرموز المعروفة مع معانيها.