مرجع المصادقة

هذي الصفحة للمهندس على الطرف الآخر من الاستدعاء: أنت تملك الواجهة اللي راح يكلّمها Orki، وتحتاج تعرف بالضبط وش يوصلك، ووش يتوقعه Orki منك، وكيف يتصرف لمّا تسوء الأمور.

إذا كنت تبغى تضبط بيانات اعتماد من لوحة التحكم، ابدأ بـ المصادقة لأدوات API بدلاً من هنا.

OAuth2 Client Credentials

طلب الرمز طلبك أنت، مو طلبنا

Orki ما يبني جسم OAuth2 بشكل مثبّت في الكود. هو يخزّن طلب الرمز اللي ضبطته ويعيد إرساله. النموذج الموجّه يبني الشكل القياسي:

POST /oauth/token HTTP/1.1
Host: api.your-service.example
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<your client id>&client_secret=<your client secret>&scope=<scope>

scope يُضاف فقط لو عبّيته.
تبديل إرسال بيانات الاعتماد كـ إلى JSON يرسل نفس الحقول الأربعة ككائن application/json.
الطريقة POST.
الطلب تنتهي مهلته بعد ٣٠ ثانية. وهي غير قابلة للضبط لكل موفّر.
ما يُطبَّق أي تحويل على استجابة الرمز — مواصفات JOLT تخص الأدوات، مو بيانات الاعتماد.

مصادقة العميل بـ HTTP Basic

إذا كانت نقطة نهاية الرمز عندك تبغى Authorization: Basic base64(client_id:client_secret) بدل حقول الجسم، فهذا ممكن — مع تحفظ واحد: Orki ما يسوي ترميز Base64 نيابةً عنك.

خزّن السلسلة المرمّزة مسبقاً لـ client_id:client_secret كسر، وبعدين أضف ترويسة لطلب الرمز تحت الإعدادات المتقدمة:

Authorization: Basic {{secret.basic}}

المعاملات غير القياسية

أي شي ما تقدر تعبّر عنه الحقول الأربعة القياسية — audience أو resource أو منحة خاصة بمزوّد — يروح في جسم طلب رمز مخصص (JSON) تحت الإعدادات المتقدمة. وهو يستبدل الجسم المُولَّد بالكامل، فأعد ذكر كل شي تحتاجه:

{
  "grant_type": "client_credentials",
  "client_id": "{{secret.clientId}}",
  "client_secret": "{{secret.clientSecret}}",
  "audience": "https://api.your-service.example/"
}

إشارات {{secret.<name>}} تُستبدل في الرابط والترويسات والجسم ومعاملات الاستعلام على حد سواء. الاسم غير المعروف يُستبدل بنص فارغ بدل ما يفشل، فراجع الإملاء لو خرج الطلب فاضياً بشكل غريب.

وش يقرأ Orki من الرد

استجابة الرمز عندك لازم تكون JSON.

Orki يقرأ	من	المسار الافتراضي	لو كان مفقوداً
الرمز	Token JSONPath	`access_token`	يفشل الاستدعاء — `TokenPath 'access_token' not found in token response.`
المدة بالثواني	Expiry JSONPath	`expires_in`	يرجع بصمت لـ مدة الاحتياط (١٨٠٠ ثانية)

المسار المجرّد يُعامل كحقل في المستوى الأعلى؛ وdata.token و$.data.token كلاهما يشتغل.

token_type يُتجاهل. نوع المخطط يجي من قالب القيمة المحقونة عندك (Bearer {{token}} افتراضياً)، فإذا كانت خدمتك تصدر شيئاً غير bearer، غيّر القالب بدل الرد.

كل هذي الاستجابات تشتغل:

{ "access_token": "eyJhbGci...", "expires_in": 3600, "token_type": "Bearer" }

{ "data": { "token": "eyJhbGci...", "ttl": 900 } }

{ "access_token": "eyJhbGci..." }

الثانية تحتاج Token JSONPath بقيمة data.token وExpiry JSONPath بقيمة data.ttl. والثالثة تاخذ مدة الاحتياط — عادي لو رموزك طويلة العمر، وخطر لو ما هي كذلك.

التخزين المؤقت والتجديد

الرموز تُخزَّن مؤقتاً لكل مؤسسة ولكل موفّر، ومشفّرة أثناء التخزين.

المدة المخزّنة = max(1, expires_in − هامش الأمان)

بالقيم الافتراضية، رمز يعلن expires_in: 3600 يُخزَّن ٣٥٧٠ ثانية. ودفعة استدعاءات متزامنة كلها تفوّت المخزون المؤقت تنتج طلب رمز واحد لكل نسخة من Orki، مو طلباً لكل استدعاء.

توقّع تقريباً طلب رمز واحد لكل مدة صلاحية لكل مؤسسة — مو واحداً لكل محادثة.

قاعدة الـ 401

إذا رجعت واجهتك 401 بالضبط لاستدعاء أداة، وكان تجديد الرمز وإعادة المحاولة مرة واحدة عند 401 مفعّلاً (وهو مفعّل افتراضياً)، فإن Orki:

يتخلص من الرمز المخزّن،
يجلب رمزاً جديداً،
يعيد الاستدعاء مرة واحدة.

الـ 401 الثاني يُرجَع كما هو. و403 ما يشغّل هذا المسار — فإذا كنت ترفض الرمز المنتهي بـ 403، ما راح يجدد Orki، والأفضل تحوّل هذا المسار لـ 401.

خطوات مسارات العمل تتصرف بنفس الطريقة تماماً؛ كل خطوة هي استدعاء أداة عادي.

كيف تصل بيانات الاعتماد لواجهتك

بالنسبة للمفاتيح الثابتة ورموز OAuth2، تُكتب القيمة الناتجة في ترويسة أو معامل استعلام مباشرةً قبل مغادرة الطلب لـ Orki:

الترتيب:  حلّ القوالب  ←  حقن بيانات الاعتماد  ←  واجهتك  ←  JOLT

نتيجتان:

بيانات الاعتماد تكتب فوق أي ترويسة بنفس الاسم أنتجها قالب الأداة. الموفّر يفوز دائماً.
JOLT يشتغل على الاستجابة، فما فيه تحويل يقدر يشوف بيانات الاعتماد أو يغيّرها.

بالنسبة للمفاتيح الثابتة، القيمة المحقونة هي القالب بعد استبدال {{secret.<name>}} — مثل {{secret.apiKey}}، أو Bearer {{secret.apiKey}} لو حددت بادئة.

WS-Security (SOAP)

WS-Security يتجاهل إعدادات الترويسة/الاستعلام تماماً ويعدّل جسم SOAP. يحلّل Orki المغلّف، وينشئ عنصر Header إذا ما كان موجوداً، ويضيف كتلة wsse:Security في أوله.

كلا إصداري SOAP مقبولان — http://schemas.xmlsoap.org/soap/envelope/ وhttp://www.w3.org/2003/05/soap-envelope. وأي شي مو مغلّف SOAP يُرفض قبل تنفيذ الاستدعاء.

PasswordText، مع طابع زمني وmustUnderstand مفعّلين:

<soapenv:Header>
  <wsse:Security
      xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"
      xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
      soapenv:mustUnderstand="1">
    <wsu:Timestamp wsu:Id="TS-3f2b...">
      <wsu:Created>2026-08-10T09:15:22.417Z</wsu:Created>
      <wsu:Expires>2026-08-10T09:20:22.417Z</wsu:Expires>
    </wsu:Timestamp>
    <wsse:UsernameToken wsu:Id="UsernameToken-9ac1...">
      <wsse:Username>administrator</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">s3cret</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soapenv:Header>

PasswordDigest يستبدل محتوى UsernameToken. عنصرا Nonce وwsu:Created يظهران فقط في هذا الوضع:

<wsse:UsernameToken wsu:Id="UsernameToken-9ac1...">
  <wsse:Username>bob</wsse:Username>
  <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordDigest">quR/EWLAV4xLf9Zqyw4pDmfV9OY=</wsse:Password>
  <wsse:Nonce EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary">WScqanjCEAC4mQoBE07sAQ==</wsse:Nonce>
  <wsu:Created>2026-08-10T09:15:22.417Z</wsu:Created>
</wsse:UsernameToken>

تفاصيل تهمّ خدمتك:

الـ digest هو Base64(SHA-1(nonce + created + password))، حسب ملف تعريف UsernameToken من OASIS، مع nonce جديد بطول ١٦ بايت لكل استدعاء.
قيمة created الداخلة في الـ digest مطابقة بايت ببايت للقيمة الظاهرة في wsu:Created.
الطوابع الزمنية بصيغة yyyy-MM-ddTHH:mm:ss.fffZ.
صلاحية الطابع الزمني محصورة بين ٣٠ و٣٦٠٠ ثانية، مهما كان المضبوط.
mustUnderstand="1" يُصدر في نطاق أسماء المغلّف نفسه.
wsse:Security يُدرج كأول عنصر ابن لـ Header، قبل أي ترويسات يضبطها قالبك.
إعلان XML في قالبك يُحافَظ عليه.

متطلبات على نقطة النهاية عندك

المتطلب	التفصيل
نطاق عام قابل للحل	عناوين IP و`localhost` مرفوضة، وكذلك المضيفات أحادية التسمية مثل `auth-internal`. `https://auth.example.com` مقبول.
استجابة رمز بصيغة JSON	استجابات XML أو form-encoded غير مدعومة.
يستجيب خلال ٣٠ ثانية	مهلة ثابتة لطلبات الرمز.
قابل للوصول من مخارج Orki	نفس قاعدة اعتماد النطاقات المطبّقة على أي أداة API — راجع إنشاء أدوات API.

دلالات الفشل

هذي الحقيقة اللي تستاهل تعرفها قبل أي تصحيح آخر: لمّا تفشل تهيئة بيانات الاعتماد — سر عميل خاطئ، نقطة نهاية غير قابلة للوصول، مسار رمز ما يطابق — يفشل استدعاء الأداة كـ خطأ خادم عام من وجهة نظر الوكيل. السبب المقروء ما يظهر في المحادثة.

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

رسائل ممكن تقابلها:

الرسالة	المعنى
`Token endpoint returned HTTP 401: …`	نقطة النهاية عندك رفضت بيانات اعتماد العميل. أول ٢٠٠ حرف من جسم ردّك مضمّنة.
`Token endpoint returned an empty response body.`	استجابة 2xx بدون جسم.
`Token endpoint response is not valid JSON.`	تعذّر تحليل المحتوى كـ JSON.
`TokenPath '<path>' not found in token response.`	المسار المضبوط ما يطابق الـ JSON عندك.
`Auth provider not found`	حُذف الموفّر وهو ما زال مرفقاً بأداة.
`WS-Security requires a SOAP XML request body, but the tool has no body.`	WS-Security مرفق بأداة بدون جسم طلب.
`WS-Security requires a SOAP envelope request body (soapenv:Envelope in the SOAP 1.1 or 1.2 namespace).`	الجسم مو مغلّف SOAP.

انتهاء مهلة طلب الرمز يُبلَّغ عنه بنفس الطريقة مثل أي فشل مصادقة — مو كانتهاء مهلة أداة.

أخطاء العمل شي ثاني: إذا نجحت المصادقة ورجعت واجهتك بـ 4xx، تُمرَّر تلك الاستجابة للوكيل عشان يتعامل معها. فقط إخفاقات تهيئة بيانات الاعتماد هي اللي توقف المسار.

ليش ما ينحفظ الموفّر

التحقق يشتغل على الخادم ويتوقف عند أول مشكلة.

الرمز	المعنى
`missing_title` / `invalid_title`	الاسم مطلوب، ولازم يبدأ بحرف أو شرطة سفلية، ويحتوي فقط على حروف وأرقام و`_` و`-`.
`reserved_title`	الأسماء اللي تبدأ بـ `Internal` محجوزة.
`duplicate_title`	فيه موفّر ثاني بنفس الاسم في هذي المؤسسة.
`missing_token_request` / `missing_token_request_base_url`	OAuth2 بدون رابط رمز.
`invalid_token_request_base_url`	رابط الرمز عنوان IP أو `localhost` أو نطاق عام غير صالح.
`missing_token_path`	OAuth2 بدون مسار JSONPath للرمز.
`missing_secrets`	مفتاح ثابت بدون سر.
`invalid_injection_value_template`	قالب مفتاح ثابت ما يشير لأي `{{secret.<name>}}`.
`missing_ws_security_secrets`	WS-Security بدون اسم مستخدم وكلمة مرور معاً.
`invalid_ws_security_ttl`	صلاحية الطابع الزمني خارج ٣٠–٣٦٠٠ ثانية.
`invalid_ttl_fallback` / `invalid_ttl_margin`	مدة احتياط أقل من ٣٠ ثانية، أو هامش أمان سالب.

سلوكان تنتبه لهما لو تعاملت مع هذا برمجياً بدل النموذج:

تحديث الأسرار يستبدل المجموعة كاملة. المفاتيح اللي ما ترسلها تُحذف، ما تُحفظ. أرسل ******** لمفتاح عشان تبقي قيمته المخزّنة.
نقطة نهاية الاختبار ترد دائماً بـ 200. النجاح والفشل كلاهما يجي في الجسم على شكل { ok, expiresAt, error } — لا تبني منطقك على رمز الحالة.

الخطوات التالية

المصادقة لأدوات API — ضبط بيانات الاعتماد من لوحة التحكم
إنشاء أدوات API — الأدوات اللي توثّقها بيانات الاعتماد هذي
بناء مسارات العمل — الخطوات ترث بيانات اعتماد أداتها

OAuth2 Client Credentials​

طلب الرمز طلبك أنت، مو طلبنا​

مصادقة العميل بـ HTTP Basic​

المعاملات غير القياسية​

وش يقرأ Orki من الرد​

التخزين المؤقت والتجديد​

قاعدة الـ 401​

كيف تصل بيانات الاعتماد لواجهتك​

WS-Security (SOAP)​

متطلبات على نقطة النهاية عندك​

دلالات الفشل​

ليش ما ينحفظ الموفّر​

الخطوات التالية​