يحتاج وكيلك إلى قراءة تقويم العميل، أو إرسال رسالة من حسابه، أو تقديم تذكرة باسمه. النسخة السريعة هي الاحتفاظ بحساب خدمة واحد ذي وصول واسع والعمل من خلاله. يظهر كل إجراء على أنه "التكامل"، ولا يمكن لأحد معرفة أي مستخدم قام بتشغيل ماذا، وبيانات اعتماد واحدة مخترقة تعرض كل حساب تتعامل معه.
الإصدار الصحيح هو التفويض المفوّض: يمنح المستخدم وكيلك رمزًا مميزًا محدود النطاق وقابل للإلغاء، ويتصرف الوكيل كمستخدم، ويقوم سجل التدقيق بتسميتهم. هذا هو ما بني OAuth 2.0 من أجله. ما يجعل الأمر محرجًا للوكلاء هو أن OAuth يفترض وجود متصفح وشخص حاضر للنقر على "سماح"، بينما تعمل الوكلاء في الخلفية في الساعة الثالثة صباحًا.
يغطي هذا الدليل تدفق OAuth المناسب للوكيل، وكيفية تحديد نطاق الرموز المميزة وتخزينها، وماذا تفعل بشأن التحديث والإلغاء، وكيفية اختبار المسار بالكامل دون حساب حقيقي. إذا كنت لا تزال تختار بين المصادقة المستندة إلى المفتاح والمفوضة، فإن مقارنتنا بين مفاتيح API و OAuth هي المكان المناسب للبدء.
Apidog يساعد في الجزء الذي تقلل الفرق من تقديره: ممارسة كل فرع من فروع التدفق، بما في ذلك انتهاء الصلاحية والإلغاء، قبل أن يلتقيها الوكيل في الإنتاج.
حساب الخدمة أم الوصول المفوّض
اختر بعناية، لأن النموذجين يفشلان بطرق مختلفة.
**حساب الخدمة** هو هوية وكيلك الخاصة، مع صلاحياته الخاصة. يناسب العمل الذي يقوم به الوكيل نيابة عنك: قراءة قاعدة بياناتك الخاصة، استدعاء خدماتك الداخلية، تشغيل مهام مجدولة ضد بنيتك التحتية. حدد نطاقه بإحكام، كما في منشورنا حول مفاتيح API بأقل امتياز للوكلاء، وقم بتدويره.
**الوصول المفوّض** هو أن يتصرف الوكيل كمستخدم معين، بصلاحيات هذا المستخدم وليس أكثر. وهو مطلوب كلما كانت البيانات تخص شخصًا آخر. ثلاث خصائص تجعله يستحق الجهد الإضافي: يمكن للمستخدم رؤية ما تم منحه، ويمكن للمستخدم إلغاؤه، ويحمل كل إجراء هويتهم في السجل.
نمط الفشل الذي يجب تجنبه هو حساب خدمة ذو وصول على مستوى المؤسسة يُستخدم للتصرف "كمستخدمين". إنه يعمل، ويعني أن بيانات اعتماد واحدة مسربة تعرض الجميع، بدون إلغاء لكل مستخدم وبدون سجل تدقيق أمين.
أي تدفق يناسب الوكيل
يحدد OAuth 2.0 عدة أنواع للمنح، وقليل منها فقط منطقي هنا. يحتوي مواصفات OAuth 2.0 على المجموعة الكاملة؛ هذه هي التي ستستخدمها.
**رمز التفويض مع PKCE.** التدفق القياسي للتصرف كمستخدم. يتم إعادة توجيه المستخدم إلى المزود، يوافق على النطاقات، ويقوم خدمتك بتبادل الرمز مقابل الرموز المميزة. يحمي PKCE التبادل وهو الآن التوصية الافتراضية لكل نوع عميل، وفقًا لـ أفضل ممارسات أمان OAuth 2.0 الحالية. يغطي دليلنا التفصيلي حول منحة رمز التفويض الآليات خطوة بخطوة.
النقطة الخاصة بالوكيل: هذا التدفق يعمل مرة واحدة، بوجود الإنسان، في وقت الاتصال. لا يقوم الوكيل بتشغيله أبدًا. يستخدم رمز التحديث الذي أنتجه التدفق. افصل هاتين اللحظتين في تصميمك وسيختفي معظم الإحراج.
**بيانات اعتماد العميل.** من آلة إلى آلة، لا يوجد مستخدم مشارك. صحيح لحسابات الخدمة وخطأ للتصرف كمستخدم، لأنه لا يوجد مستخدم للموافقة.
**منحة تفويض الجهاز.** للوكلاء على الأجهزة التي لا تحتوي على متصفح. يحصل المستخدم على رمز ويوافق عليه عبر هاتفه. مفيد لوكلاء سطر الأوامر (CLI) والبيئات بلا واجهة رسومية.
**تبادل الرموز المميزة.** RFC 8693 يسمح للخدمة بتبديل رمز مميز بآخر أضيق نطاقًا. هذه هي الطريقة التي تمنح بها وكيلًا فرعيًا رمزًا مميزًا مقتصرًا على نطاق واحد لمهمة واحدة، مشتقًا من منحة المستخدم الأوسع، دون تسليمه الرمز الأصلي. إذا كنت تدير أنظمة متعددة الوكلاء، فهذه هي الآلية التي تجعل بيانات الاعتماد لكل وكيل عملية، وتناسب قواعد الحدود في منشورنا حول تسليم المهام بين الوكلاء المتعددين.
تحديد النطاق بدقة، ولكل وكيل
النطاقات هي حيث يثبت الوصول المفوّض جدواه، وحيث تصبح معظم التطبيقات كسولة من خلال طلب كل ما قد يحتاجه التطبيق.
اطلب فقط ما يفعله هذا الوكيل. وكيل الجدولة يحتاج إلى صلاحية الكتابة في التقويم ولا شيء آخر. ليس البريد، وليس جهات الاتصال، وليس الملفات. يقرأ المستخدمون شاشة الموافقة، والقائمة الطويلة هي مشكلة ثقة ومشكلة نطاق تأثير. يغطي شرحنا حول نطاقات OAuth 2 كيف يقوم المزودون بنمذجتها.
اطلب بشكل تدريجي. اطلب الحد الأدنى في وقت الاتصال، ثم اطلب المزيد عندما يطلب المستخدم ميزة تحتاج إليها. الموافقة المرتبطة بطلب ملموس أسهل في المنح وأسهل في التبرير.
امنح كل وكيل رمزًا مميزًا خاصًا به. إذا كان وكيل بحث ووكيل فواتير يعملان لنفس المستخدم، فاشتق رمزين مميزين بنطاقات مختلفة بدلاً من مشاركة رمز واحد. عندئذٍ، لا يمكن لوكيل بحث مخترق إصدار استرداد للمبالغ، ويخبرك السجل أي وكيل قام بالإجراء.
فضل نطاقات القراءة افتراضيًا وتطلب تصعيدًا صريحًا للكتابة. اجمع هذا مع بوابة موافقة على الاستدعاءات المدمرة، كما في منشورنا حول حواجز حماية وكلاء الذكاء الاصطناعي، بحيث لا يكون الرمز المميز الذي يمكنه الكتابة هو الشيء الوحيد الذي يقف بين الوكيل والخطأ.
التخزين والتحديث والإلغاء
الرموز المميزة هي بيانات اعتماد، لذا تعامل معها كبيانات اعتماد.
**التخزين.** قم بتشفير رموز التحديث أثناء السكون، مفتاح لكل مستخدم. لا تكتبها أبدًا في السجلات، ولا تضعها أبدًا في الموجهات، ولا تدع أي نموذج يراها أبدًا. الرمز المميز في السياق هو رمز مميز في متجر التتبع الخاص بك، وسجلات مزودك، وربما ملخص. يغطي منشورنا حول تتبع استدعاءات أدوات الوكيل التنقيح عند الحدود بدلاً من وقت القراءة.
**التحديث.** رموز الوصول قصيرة الأجل بطبيعتها. لا ينبغي للوكيل أن يدير هذا بنفسه أبدًا؛ يقوم مدير الرموز المميزة أمام عميل HTTP بالتحديث عندما يقترب انتهاء الصلاحية ويعيد المحاولة مرة واحدة عند حدوث `401`.
class TokenManager:
def __init__(self, store, provider):
self.store, self.provider = store, provider
def access_token(self, user_id, agent_scope):
rec = self.store.get(user_id, agent_scope)
if rec.expires_in() > 60:
return rec.access_token
fresh = self.provider.refresh(rec.refresh_token, scope=agent_scope)
self.store.save(user_id, agent_scope, fresh) # rotation: store the new refresh token
return fresh.access_token
نقطتان مهمتان. يقوم المزودون بشكل متزايد بتدوير رموز التحديث، بإصدار رمز جديد عند كل تحديث وإبطال الرمز القديم، لذا احتفظ بالرمز الجديد على الفور وإلا ستحرم المستخدم من الوصول. وقم بترتيب التحديثات لكل مستخدم، حيث أن تحديثين متزامنين مع مزود يقوم بالتدوير سيتنافسان وسيفقد أحدهما.
**الإلغاء.** يقوم المستخدمون بإلغاء الوصول، تنتهي صلاحية الرموز المميزة، ويزيل المسؤولون الحسابات. يجب على الوكيل التعامل مع `401` و `403` كأخطاء نهائية بدلاً من قابلة لإعادة المحاولة. إعادة محاولة فشل المصادقة لا يساعد أبدًا ويمكن أن يؤدي إلى تفعيل حماية إساءة الاستخدام. أرجع رسالة واضحة تحدد المستخدم والنطاق حتى يتمكن الإنسان من التصرف، باتباع أنماط الأخطاء في منشورنا حول تصميم أخطاء API لوكلاء الذكاء الاصطناعي.
مشكلة الموافقة
الجزء المحرج في الوكلاء و OAuth: الموافقة تحتاج إلى إنسان، والوكلاء يعملون دون مراقبة.
افصل وقت الاتصال عن وقت التشغيل ويصبح الأمر قابلاً للإدارة. في وقت الاتصال، يقوم شخص واحد بالترخيص مرة واحدة، باستخدام متصفح، وتقوم بتخزين رمز تحديث. في وقت التشغيل، يستخدم الوكيل هذا الترخيص دون تدخل بشري. هذا يعمل مع الوكلاء المجدولين والذين يعملون في الخلفية، وهم معظمهم.
حدان يجب التخطيط لهما. تنتهي صلاحية المنح، أحيانًا بعد أشهر من عدم الاستخدام، وأحيانًا بموجب سياسة. اكتشف المنحة منتهية الصلاحية، أوقف التشغيل، وأبلغ المستخدم، بدلاً من الفشل بصمت كل ليلة. وللموافقة سقف نطاق: الوكيل الذي يحتاج إلى نطاق لم يمنحه المستخدم أبدًا يجب أن يطلب ذلك بدلاً من التصعيد بمفرده.
لأي شيء ذي مخاطر عالية، أضف بوابة ثانية في وقت الإجراء. يثبت الرمز المميز أن الوكيل قد يتصرف؛ تقرر بوابة الموافقة ما إذا كان يجب عليه ذلك. هذه أسئلة مختلفة وكلاهما يستحق إجابة.
اختبر التدفق قبل أن يواجهه الوكيل
مسارات رمز المصادقة هي الجزء الأقل اختبارًا في معظم التكاملات، لأن ممارستها يدويًا تعني النقر عبر شاشات المزود.
قم ببناء هذه الحالات الخمسة:
- **المسار السعيد.** رمز وصول صالح، استدعاء ناجح. الأساس.
- **رمز وصول منتهي الصلاحية.** يعيد المزود `401`، يقوم المدير بالتحديث، تتم إعادة محاولة الاستدعاء مرة واحدة وتنجح. هذا هو المسار الحقيقي الأكثر شيوعًا وغالبًا ما يكون الأقل اختبارًا.
- **رمز تحديث ملغى.** يعيد التحديث `invalid_grant`. يجب على الوكيل التوقف والإبلاغ، لا التكرار في حلقة.
- **نطاق غير كافٍ.** `403` مع خطأ في النطاق. يجب على الوكيل ألا يعيد المحاولة، ويجب أن يذكر النطاق المفقود.
- **تحديث متزامن.** استدعاءان لنفس المستخدم في وقت واحد. يجب أن يحدث تحديث واحد فقط.
قم بتشغيلها مقابل نماذج وهمية. في Apidog يمكنك تعريف نقطة نهاية الرمز المميز ونقاط النهاية المحمية، ثم محاكاة كل استجابة بما في ذلك نصوص الأخطاء، بحيث تعمل المصفوفة بأكملها دون لمس مزود حقيقي. يغطي منشورنا حول تشغيل الوكلاء مقابل النماذج الوهمية بدلاً من الإنتاج العادة الأوسع، ويغطي دليل اختبار API لـ OAuth 2 التفاصيل على مستوى الطلب.
ثلاثة تكاملات وما تحتاج إليه
**مساعد تقويم.** يقرأ التوافر ويحجز الاجتماعات لمستخدم واحد. وصول مفوّض، نطاقان، موافقة في وقت الاتصال عبر المتصفح، وتشغيل في الخلفية لاحقًا. الفشل المثير للاهتمام هو الإلغاء: يقطع المستخدم التكامل ويجب أن يلاحظ التشغيل الليلي ذلك ويتوقف بدلاً من إعادة محاولة منحة ميتة لمدة أسبوع.
**وكيل دعم داخل صندوق بريد مشترك.** يتصرف بشأن التذاكر التي تخص فريقًا. هنا يصبح سؤال الهوية أكثر حدة. التصرف كحساب الفريق المشترك أمر يمكن الدفاع عنه، حيث أن المورد يخص الفريق بالفعل، ولكن كل رد يبدو متطابقًا في سجل التدقيق. الأفضل هو هوية روبوت ذات نطاقات خاصة بها بالإضافة إلى سجل يوضح من قام بتشغيل العملية، مما يحافظ على الإسناد سليمًا دون التظاهر بأن الوكيل شخص.
**وكيل عمليات داخلي.** يعيد تشغيل الخدمات ويقرأ لوحات المعلومات في بنيتك التحتية. لا توجد بيانات مستخدم، ولا تفويض. حساب الخدمة ذو النطاقات الضيقة هو الإجابة الصحيحة، ويركز العمل على التدوير ونطاق التأثير بدلاً من الموافقة.
خط الفصل هو الملكية. إذا كانت البيانات تخص شخصًا قد يرغب بشكل معقول في إلغاء وصولك، فاستخدم المصادقة المفوّضة. إذا كانت تخصك، فاستخدم حساب خدمة وابذل الجهد في تحديد النطاق.
حافظ على العنصر البشري في الإسناد
المصادقة المفوّضة تجيب على "بالنيابة عن من". لا تجيب على "بطلب من من"، وفي عمل الوكيل تريد كليهما. يثبت الرمز المميز أن الوكيل قد يتصرف كمستخدم؛ لكنه لا يسجل من طلب التشغيل.
احتفظ بتلك الهوية الثانية بجانب العمل. حيث يقوم الوكلاء بتنفيذ المهام الموكلة، فإن طبقة إدارة العمل هي المكان الطبيعي: تسجل مهمة Sharkly الشخص المسؤول عن العمل جنبًا إلى جنب مع الوكيل أو الفريق المكلف بتنفيذها، مما يحافظ على المساءلة البشرية وتنفيذ الوكيل كحقيقتين منفصلتين ومرئيتين. يصف توثيق Sharkly هذا الفصل بالتفصيل. بغض النظر عن كيفية تخزينها، فإن سؤال التدقيق بعد حادثة عادة ما يكون "من طلب هذا"، والرمز المميز وحده لا يمكنه الإجابة عليه.
لا تدع النموذج يحتفظ ببيانات الاعتماد
تمنع قاعدة معمارية واحدة معظم حوادث المصادقة في أنظمة الوكلاء: النموذج لا يرى الرمز المميز أبدًا.
يتم حقن الرموز المميزة بواسطة المنفذ في طبقة HTTP، بعد أن يختار النموذج أداة وينتج الوسائط. لا يحتوي مخطط الأداة على معلمة `token`، ولا يحتوي الموجه على بيانات اعتماد، والاستجابة التي يقرأها النموذج تم تجريد رأس `Authorization` منها.
هذا الأمر مهم أكثر للوكلاء منه للعملاء العاديين بسبب كيفية انتقال مدخلات النموذج. يمكن تلخيص أي شيء في السياق في تسليم، أو كتابته في تتبع، أو تكراره في رسالة خطأ، أو إعادته إلى مستخدم طلب من الوكيل شرح نفسه. لا شيء من هذه المسارات عدائي؛ إنها كلها ميزات عادية تتحول إلى تسريبات لحظة وجود بيانات الاعتماد في النطاق.
تنطبق نفس القاعدة على هوية المستخدم. يعرف المنفذ المستخدم الذي يعمل هذا التشغيل لصالحه، ويختار الرمز المميز من ذلك. السماح للنموذج بتسمية المستخدم هو قرار تفويض يتخذه المكون الأقل قابلية للتنبؤ في النظام.
قائمة مرجعية
- وصول مفوّض أينما كانت البيانات تخص مستخدمًا، وحسابات خدمة لمواردك الخاصة فقط.
- رمز التفويض مع PKCE في وقت الاتصال، ومنحة الجهاز للآلات التي لا تحتوي على واجهة رسومية.
- النطاقات المطلوبة لكل وكيل، بحد أدنى، يتم تصعيدها تدريجياً.
- يحصل الوكلاء الفرعيون على رموز مميزة مبادلة، وليست نسخًا من منحة المستخدم.
- رموز التحديث مشفرة في حالة السكون ولا توجد أبدًا في الموجهات أو السجلات أو التتبعات.
- يتم التعامل مع التحديث بواسطة مدير الرموز المميزة، ويتم تسلسلها لكل مستخدم، ويتم الاحتفاظ بالتدوير.
- يتم التعامل مع `401` و `403` كأخطاء نهائية، مع رسالة تحدد المستخدم والنطاق.
- يتم اكتشاف المنح منتهية الصلاحية وإبلاغ المستخدم بها، ولا تتم إعادة محاولتها ليلاً.
- الإجراءات عالية المخاطر مقيدة بالموافقة بالإضافة إلى الرمز المميز.
- تم اختبار جميع سيناريوهات المصادقة الخمسة مقابل النماذج الوهمية في CI.
المصادقة المفوّضة تتطلب جهدًا أكبر من المفتاح المشترك، وهي تمنحك شيئين تحتاجهما عندما يتصرف الوكيل نيابة عن الآخرين: يمكن للمستخدم استرجاعها، ويقول السجل من فعل ماذا. قم بتنزيل Apidog لبناء تدفق الرموز المميزة وحالات فشلها قبل أن يقوم الوكيل بتشغيلها دون مراقبة.
الأسئلة المتكررة
**هل يمكن للوكيل إكمال تدفق موافقة OAuth بنفسه؟** لا، ولا ينبغي له المحاولة. الموافقة تتطلب شخصًا يقرر ما سيمنحه. اجعل إنسانًا يوافق مرة واحدة من خلال تدفق متصفح عادي، ثم دع الوكيل يستخدم المنحة الناتجة.
**هل يجب أن يكون لكل وكيل عميل OAuth خاص به؟** عملاء منفصلون لكل تكامل منتج، ورموز مميزة منفصلة لكل وكيل داخله، عادةً عبر تبادل الرموز المميزة. تساعد العملاء المميزون عندما يطبق المزودون حدود معدل لكل عميل أو عندما تريد إلغاءً مستقلاً.
**ماذا يحدث إذا تم تدوير رمز التحديث وفاتني الرمز الجديد؟** يتم حظر المستخدم ويجب عليه إعادة الاتصال. احتفظ برمز التحديث الجديد في نفس المعاملة التي تستهلك الرمز القديم، وقم بترتيب التحديثات لكل مستخدم حتى لا يتنافس عاملان.
**هل من الآمن السماح للنموذج برؤية رمز الوصول؟** لا. الرموز المميزة مكانها في طبقة HTTP، يتم حقنها بواسطة المنفذ الخاص بك. أي شيء يراه النموذج يمكن أن ينتهي به المطاف في تتبع أو ملخص أو استجابة، كما هو موضح في منشورنا حول مفاتيح API بأقل امتياز للوكلاء.
**كيف أراجع أي وكيل فعل ماذا؟** سجل معرف المستخدم، اسم الوكيل، النطاق المستخدم، ومعرف الرمز المميز في كل استدعاء، وليس الرمز المميز نفسه أبدًا. يغطي منشورنا حول تتبع استدعاءات أدوات الوكيل شكل السجل.
**ماذا لو لم يدعم المزود تبادل الرموز المميزة؟** قم بتخزين منح منفصلة لكل وكيل حيث يسمح المزود بعدة منح، أو قم بفرض تضييق النطاق في بوابة الوصول الخاصة بك بحيث يتم تصفية استدعاءات كل وكيل إلى عملياته المسموح بها قبل أن تغادر شبكتك.