الوكلاء

اتصالات المصادقة

احفظ بيانات اعتماد basic أو bearer أو OAuth2 مرة واحدة، واربطها بالأدوات التي تحتاجها، واعرف بالضبط متى يجلب إيكونوڤا رمزاً جديداً.

اتصال المصادقة بيانات اعتماد محفوظة ومرفقة بطريقة مصادقة. الـ سر قيمة مبهمة تسمي لها header، أما الاتصال فيعرف كيف يصادق بنفسه، ويُنتج دائماً header Authorization بنفسه. احفظه مرة واحدة، ثم أرفقه بالأدوات التي تستدعي تلك واجهة API.

ما تحتاج إليه

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

الأنواع الأربعة

النوع الاسم في البوابة ما تدخله ما تستقبله واجهة API
basic أساسي اسم المستخدم، كلمة المرور Authorization: Basic <base64 of username and password>
bearer رمز Bearer الرمز Authorization: Bearer <token>
oauth2_client_credentials بيانات اعتماد عميل OAuth2 معرّف العميل، رابط الرمز، سر العميل، والنطاقات ومعلمات إضافية اختياريان Authorization: Bearer <access token>
oauth2_jwt OAuth2 JWT المُصدر، الموضوع، الجمهور، رابط الرمز، المفتاح الخاص، والخوارزمية والنطاقات اختياريان Authorization: Bearer <access token>

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

الخوارزمية تأخذ RS256 إذا تركتها فارغة. المفتاح الخاص بتنسيق PEM. النطاقات نص حر يُوحَّد قبل إرساله، فتُحوَّل الفواصل وأي تسلسل من المسافات إلى مسافة واحدة. المعلمات الإضافية موجودة في نوع client credentials فقط، وتُدخل سطراً لكل key=value، وتُلحق بجسم طلب الرمز.

الخطوات

الخطوة 1: افتح صفحة الإعدادات

انتقل إلى الإعدادات في قائمة الوكلاء، وانتقل إلى تبويب اتصالات المصادقة، تحت السطر «طرق مصادقة قابلة لإعادة الاستخدام تستخدمها الأدوات والقنوات.»

الخطوة 2: اضغط إضافة مصادقة واختر نوعاً

يفتح إضافة مصادقة قائمة بالأنواع الأربعة. اختيار نوع يفتح إضافة اتصال مصادقة بذلك النوع محدداً مسبقاً، ويعيد النموذج رسم الحقول التي يحتاجها ذلك النوع.

الخطوة 3: سمِّه

الاسم مطلوب، ويُقص منه الفراغ، ويجب أن يكون فريداً في مساحة العمل. العنصر النائب هو «مصادقة API الخاصة بي». يغطي الفحص كل اتصال في مساحة العمل، بما فيها بيانات الاعتماد المُدارة للتكاملات التي لا تعرضها هذه الصفحة، لذلك قد يتصادم الاسم مع شيء لا تراه.

الخطوة 4: املأ الحقول حسب النوع

الحقول المطلوبة تحمل نجمة حمراء. كل واحد منها يُفحص مرة أخرى عند الحفظ، والحقل المطلوب الفارغ يُرفض باسمه، مثل clientId is required.

الخطوة 5: احفظ

يختم حفظ الجزء السري ويخزّن الباقي. يظهر الصف في القائمة باسمه وشريحة تذكر النوع.

للحصول على أفضل نتيجة

الاتصال هو كل التحكم في الوصول في كل استدعاء يجريه الوكيل به، لذلك أعطه هوية خاصة به لدى واجهة API، وأعطه الوصول الذي يحتاجه الوكيل فقط.

الموصى به

Client: echonova-agent (machine user)
Scopes: orders:read shipments:read
Access: the three endpoints the imported API actually uses

الأقل فاعلية

Client: the admin API token already in use by our back office
Scopes: full access
Access: every endpoint, including the ones that refund and delete

ماذا يحدث بعد ذلك

يُختم الجزء السري بالطريقة نفسها التي تُختم بها أسرار مساحة العمل: يُشفَّر بـ AES-256-GCM بمفتاح تصدره AWS KMS لهذا الاتصال وحده، ومرتبط بمساحة العمل الخاصة بك. بعد الحفظ تحصل على المعرّف والاسم والنوع والإعداد غير السري والتواريخ وتلميح مُقنّع بآخر أربعة أحرف. الجزء المختوم لا يُعاد أبداً.

يصبح الاتصال قابلاً للاختيار في أي مكان تطلب فيه أداة مصادقة. ولا تُصفّي القائمة حسب النوع، لذلك يعمل أي نوع من الأربعة مع أي أداة تعرض المنتقي.

أين يمكن استخدام الاتصال

الموضع أين يُختار النطاق
أداة Webhook اتصال المصادقة في كتلة المصادقة الخاصة بالأداة الأداة كلها
أداة OpenAPI مستوردة منتقي المصادقة في نموذج الاستيراد كل عملية ترث الاتصال
عملية OpenAPI واحدة وضع المصادقة للعملية مضبوط على اتصال مسمّى تلك العملية وحدها

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

يجب أن يكون الاتصال الذي تسميه أداة موجوداً عند حفظ الأداة. الاتصال المفقود يُرفض بالرسالة Referenced credential not found، أو بالرسالة Referenced credential not found for operation "<name>" عند تجاوز خاص بعملية أثناء الاستيراد.

تحفظ القنوات بيانات اعتمادها بشكل منفصل، وتغطيها صفحات القنوات.

كيف يحصل نوعا OAuth2 على رمز

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

Client credentials. يرسل إيكونوڤا الطلب grant_type=client_credentials إلى رابط الرمز، ويصادق بـ HTTP Basic المبني من معرّف العميل وسره، ويضيف النطاقات والمعلمات الإضافية عند ضبطها.

JWT. يوقّع إيكونوڤا تأكيد JWT بمفتاحك الخاص بالخوارزمية التي اخترتها، ويضع فيه المُصدر والموضوع والجمهور اللذين أدخلتهما، ويكون صالحاً لمدة 300 ثانية، ثم يرسله إلى رابط الرمز كـgrant_type=urn:ietf:params:oauth:grant-type:jwt-bearer.

يُعاد استخدام رمز الوصول حتى قبل انتهائه بقليل. يحتفظ إيكونوڤا به لمدة العمر الذي أعلنته نقطة النهاية ناقص 60 ثانية، بحد أدنى 30 ثانية، مع تباين يصل إلى 9 ثوانٍ حتى لا تتجدد الاتصالات الكثيرة في وقت واحد. ونقطة النهاية التي لا تعلن عن عمر تُعامل كأنها 300 ثانية. والاستدعاءات التي تحتاج رمزاً في اللحظة نفسها تتشارك طلباً واحداً إلى نقطة نهاية الرموز، بدلاً من إرسال عدة طلبات.

يجلب إيكونوڤا رمزاً جديداً أيضاً عندما ترد واجهة API الخاصة بك بـ401. وتعمل إعادة المحاولة هذه مرة واحدة، ولنوعي OAuth2 فقط. أما اتصال basic أو bearer الذي يحصل على 401 فيُعرض كما هو، لأنه لا يوجد ما يمكن تجديده.

يُستدعى رابط الرمز عبر HTTPS فقط، ويجب أن يُحل إلى مضيف عام، ولا تُتبع التحويلات (redirects)، ويُلغى الطلب بعد 10 ثوانٍ.

تدوير بيانات الاعتماد

التدوير تعديل، وليس استبدالاً، لذلك تبقى الأدوات تشير إلى الاتصال نفسه، ولا تحتاج إلى إعادة توجيه.

  1. افتح قائمة الصف واضغط تعديل.
  2. اترك كل حقل سري فارغاً للإبقاء على القيمة الحالية، أو اكتب القيمة الجديدة لاستبدالها. العنصر النائب يعرض ثماني نقاط حيث توجد قيمة محفوظة.
  3. عدّل الإعداد غير السري إذا تغيّر هو أيضاً.
  4. اضغط حفظ.

لا يمكن تغيير النوع. الاختيار مقفل على اتصال موجود، والنموذج يقول «لا يمكن تغيير نوع الاتصال بعد الإنشاء.» بيانات اعتماد تنتقل من bearer إلى OAuth2 هي اتصال جديد وإعادة توجيه.

إدخال سر جديد يعيد فحص مجموعة الحقول كلها لذلك النوع، فالتدوير الذي يترك حقل إعداد مطلوباً صار مطلوباً تُرفض العملية بدلاً من أن تُطبَّق نصف تطبيق. وعند النجاح يستخدم الاستدعاء التالي بيانات الاعتماد الجديدة، ولا يوجد انتظار.

تبقى بيانات الاعتماد المفتوحة في الذاكرة خمس دقائق على الأكثر، ولا تُكتب في أي مكان. وتعديل الاتصال يجعل القيمة الأقدم غير قابلة للوصول فوراً.

حذف اتصال

حذف في قائمة الصف يطلب التأكيد، ويذكر اسم الاتصال ويحذّر من أن «الأدوات أو القنوات التي تشير إليه ستتوقف عن العمل.»

قبل إزالة الاتصال يتحقق إيكونوڤا مما إذا كانت أي أداة في مساحة العمل ما زالت تشير إليه، سواء كاتصال لأداة Webhook أو كاتصال لأداة OpenAPI مستوردة. وإذا كان هناك مرجع، يُرفض الحذف برمز 409 ورسالة Auth connection is in use by a tool، وتعرضها البوابة كـ«مستخدم بواسطة أداة أو قناة. أزل المرجع أولاً.»

بيانات اعتماد تديرها إيكونوڤا لك

ربط Slack أو Meta أو Google Calendar أو Zoho يحفظ رمز ذلك التكامل بجوار هذه الاتصالات، ويُعلَّم بأنه مُدار. بيانات الاعتماد المُدارة تُستبعد من القائمة في هذه الصفحة، ولا يمكن تعديلها هنا، وتُعفى من فحص المرجع، لأن فصل التكامل يزيل أدواته الخاصة.

وهذه هي البيانات الوحيدة التي تحمل رمز تحديث، ويجدد إيكونوڤا رموزها لك. إذا فشل التجديد، مثلاً لأن المزوّد سحب رمز التحديث، تستمر الاستدعاءات بالرمز المحفوظ، ويرفضها المزوّد. أعد ربط التكامل لإصلاح ذلك. تدوير اتصال في هذه الصفحة لا يصلح الأمر، لأن بيانات الاعتماد المُدارة ليست من هذه الاتصالات.

الحدود

الحد القيمة ينطبق على
الأنواع basic، bearer، oauth2_client_credentials، oauth2_jwt الإنشاء
الاسم مطلوب، بعد حذف المسافات، فريد في مساحة العمل الإنشاء
النوع بعد الإنشاء لا يمكن تغييره التعديل
قراءة بيانات الاعتماد مرة أخرى لا تُعاد في أي مكان عمر الاتصال كله
عمر تأكيد JWT 300 ثانية نوعا OAuth2
إعادة استخدام رمز الوصول العمر المعلن ناقص 60 ثانية، بحد أدنى 30 ثانية، مع تباين حتى 9 ثوانٍ نوعا OAuth2
العمر المفترض عندما لا تعلن نقطة النهاية عنه 300 ثانية نوعا OAuth2
مهلة طلب الرمز 10000 مللي ثانية نوعا OAuth2
رابط الرمز HTTPS فقط، ومضيفات عامة فقط، ولا تُتبع التحويلات نوعا OAuth2
إعادة المحاولة عند 401 مرة واحدة، لنوعي OAuth2 فقط استدعاءات الأدوات
بيانات الاعتماد المفتوحة في الذاكرة 5 دقائق، و2000 قيمة استدعاءات الأدوات
الصلاحية عضوية في مساحة العمل، ولا شيء بعدها كل عناصر التحكم في الاتصالات

حل المشكلات

"Duplicate value for name"

يوجد اتصال آخر في مساحة العمل هذه يستخدم الاسم نفسه. اختر اسماً آخر. يغطي الفحص كل اتصال في مساحة العمل، بما فيها بيانات الاعتماد المُدارة للتكاملات التي لا تعرضها هذه الصفحة، لذلك قد لا يكون التصادم مرئياً لك دائماً.

"OAuth token request failed"

نقطة نهاية الرموز لديك لم يمكن الوصول إليها، أو انتهت مهلة الطلب بعد 10 ثوانٍ. تحقق من أن رابط الرمز يمكن الوصول إليه من الإنترنت العام، وأنه يجيب خلال تلك المدة.

"OAuth token request rejected"

نقطة نهاية الرموز أجابت، لكن ليس بحالة نجاح. الأسباب المعتادة سر عميل خاطئ، أو مفتاح توقيع منتهٍ، أو نطاق لا يحق للعميل طلبه، أو تأكيد JWT لا يطابق المُصدر أو الموضوع أو الجمهور الذي تتوقعه نقطة النهاية.

"OAuth token endpoint returned no access_token"

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

"Target URL must use https"

رابط الرمز ليس HTTPS. يُفحص عند جلب الرمز لا عند الحفظ، لذلك يظهر هذا في أول استدعاء للأداة، لا في النافذة.

"Target URL must be a public host"

رابط الرمز يشير إلى localhost أو إلى نطاق خاص أو إلى عنوان link-local. لا تُستدعى إلا المضيفات العامة.

"Connection is not an OAuth2 type"

طلب شيء ما رمز وصول من اتصال basic أو bearer. تحقق من النوع في الاتصال الذي تستخدمه الأداة.

واجهة API ترد بـ 401 في كل استدعاء

تأكد من أن الأداة تشير إلى الاتصال الذي تظن أنها تشير إليه، ثم تحقق من بيانات الاعتماد نفسها بتدويرها. وتذكر أن الاتصال المحذوف لا ينتج أي header Authorization بدلاً من خطأ، لذلك الطلب غير المصادَق الذي يصل إلى واجهة API غالباً ما يعني أن المرجع معلّق.

الأسئلة الشائعة

هل أستطيع رؤية بيانات الاعتماد مرة أخرى بعد حفظها؟

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

هل أحتاج إلى إعادة التفويض لاتصال OAuth2 عندما ينتهي رمزه؟

لا. لا يستخدم أي من نوعي OAuth2 رمز تحديث أو مطالبة بالتفويض. يُنشأ رمز وصول جديد من بيانات الاعتماد المحفوظة كلما انتهى الحالي.

هل يستطيع اتصال واحد أن يخدم عدة أدوات؟

نعم. الاتصال يملكه مساحة العمل، ويستطيع أي عدد من الأدوات أن يشير إليه. وهذا هو سبب وجوده أصلاً.

هل تستطيع أداة Webhook استخدام اتصال OAuth2؟

نعم. كل نوع ينتج header Authorization، ولا يُصفّي أي منتقي حسب النوع.

ماذا يغلب إذا ضبطت الأداة header آخر بالاسم نفسه؟

الاتصال. يُكتب الـ auth في الآخر في مسار Webhook ومسار واجهة API المستوردة على حد سواء، فيحل header Authorization الخاص به محل أي header بالاسم نفسه أو قيمة ثابتة استخدمته.

أين ذهب بيانات الاعتماد الخاصة بـ Slack أو Google؟

حُفظت كبيانات اعتماد مُدارة، ولا تظهر في هذه الصفحة. أدِرها من التكامل الذي أنشأها.