OAuth لوكلاء الذكاء الاصطناعي: العمل بأمان نيابة عن المستخدم

مصادقة OAuth المفوّضة لوكلاء الذكاء الاصطناعي: تنفيذ آمن وقابل للتدقيق

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

جرّب Apidog اليوم

الحل الصحيح هو التفويض المفوّض: يمنح المستخدم وكيلك رمزًا مميزًا محدود النطاق وقابلًا للإلغاء، ويتصرف الوكيل باسمه، بينما يحتفظ سجل التدقيق بهوية المستخدم. هذا هو الغرض من OAuth 2.0. وإذا كنت لا تزال تقارن بين النموذجين، فابدأ بدليل مفاتيح API مقابل OAuth.

اختر نموذج الهوية الصحيح

حساب الخدمة

حساب الخدمة هو هوية الوكيل، بصلاحيات مستقلة. استخدمه عندما ينفذ الوكيل عملاً نيابة عن نظامك:

• قراءة قواعد بياناتك الداخلية.
• استدعاء الخدمات الخاصة بك.
• تشغيل مهام البنية التحتية المجدولة.

طبّق أقل امتياز، ودوّر بيانات الاعتماد دوريًا، واتبع ممارسات مفاتيح API بأقل امتياز للوكلاء.

الوصول المفوّض

استخدم OAuth المفوّض عندما يتصرف الوكيل نيابةً عن مستخدم محدد أو يصل إلى بياناته. يمنحك ذلك ثلاث خصائص أساسية:

1. يمكن للمستخدم معرفة الصلاحيات التي منحها.
2. يمكنه إلغاء الوصول في أي وقت.
3. يحمل كل إجراء هوية المستخدم في سجل التدقيق.

لا تستخدم حساب خدمة على مستوى المؤسسة للتصرف «كمستخدمين». هذا يزيل الإلغاء لكل مستخدم ويجعل تسريب اعتماد واحد يعرّض الجميع للخطر.

تدفق OAuth المناسب للوكيل

تعرّف مواصفات OAuth 2.0 أنواع منح عديدة، لكن هذه هي المهمة للوكلاء:

1. رمز التفويض مع PKCE

هذا هو التدفق الافتراضي للوصول نيابة عن مستخدم:

1. يفتح المستخدم صفحة مزود الهوية.
2. يوافق على النطاقات المطلوبة.
3. تتبادل خدمتك رمز التفويض مقابل رموز الوصول والتحديث.
4. يستخدم الوكيل رمز التحديث لاحقًا في الخلفية.

يحمي PKCE تبادل رمز التفويض، وهو التوصية الافتراضية وفق أفضل ممارسات أمان OAuth 2.0. راجع دليل منحة رمز التفويض للتفاصيل.

قاعدة التصميم: نفّذ الموافقة البشرية مرة واحدة عند الاتصال، ولا تجعل الوكيل يحاول تشغيلها أثناء التنفيذ.

2. بيانات اعتماد العميل

هذا تدفق آلة-إلى-آلة بلا مستخدم. استخدمه لحسابات الخدمة، وليس للتصرف نيابة عن مستخدم.

3. منحة تفويض الجهاز

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

4. تبادل الرموز المميزة

يسمح RFC 8693 بتبديل رمز مميز أوسع برمز أضيق نطاقًا. استخدمه لمنح وكيل فرعي رمزًا خاصًا بمهمة واحدة بدل تمرير رمز المستخدم الأصلي إليه.

هذا مناسب للأنظمة متعددة الوكلاء، خصوصًا عند تسليم المهام بين الوكلاء.

صمّم النطاقات لكل وكيل

لا تطلب كل الصلاحيات التي قد تحتاجها لاحقًا. اطلب فقط ما يحتاجه الوكيل الآن.

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

راجع شرح نطاقات OAuth 2، وأضف طبقة موافقة للإجراءات الحساسة كما في حواجز حماية وكلاء الذكاء الاصطناعي.

خزّن الرموز وحدّثها بأمان

تعامل مع الرموز المميزة كبيانات اعتماد حساسة:

• شفّر رموز التحديث أثناء السكون.
• استخدم مفتاح تشفير لكل مستخدم.
• لا تسجل الرموز في السجلات أو التتبعات.
• لا تضعها في الموجهات أو مخططات الأدوات.
• لا تسمح للنموذج برؤيتها.

يمكنك تطبيق تنقيح الأسرار عند الحدود كما في تتبع استدعاءات أدوات الوكيل.

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 كأخطاء نهائية، لا كأخطاء قابلة لإعادة المحاولة.
• عند invalid_grant، أوقف الوكيل واطلب من المستخدم إعادة الاتصال.
• اذكر المستخدم والنطاق المطلوب بوضوح في رسالة الخطأ.
• لا تكرر فشل المصادقة في حلقة؛ لن يحل ذلك المشكلة وقد يفعّل حماية إساءة الاستخدام.

اتبع مبادئ تصميم أخطاء API لوكلاء الذكاء الاصطناعي.

افصل وقت الاتصال عن وقت التشغيل

الموافقة تحتاج إلى إنسان، لكن الوكلاء يعملون غالبًا بلا مراقبة. افصل المرحلتين:

• وقت الاتصال: يوافق المستخدم مرة واحدة في المتصفح، ثم تخزّن رمز التحديث.
• وقت التشغيل: يستخدم الوكيل المنحة المخزنة في الخلفية.

خطط لحالتين:

1. منحة منتهية الصلاحية: أوقف التشغيل وأبلغ المستخدم بدل الفشل الصامت كل ليلة.
2. نطاق غير ممنوح: اطلب موافقة جديدة؛ لا تسمح للوكيل بالتصعيد من تلقاء نفسه.

بالنسبة للإجراءات عالية المخاطر، أضف بوابة موافقة ثانية عند التنفيذ. الرمز يثبت أن الوكيل يستطيع التصرف؛ بوابة الموافقة تقرر إن كان ينبغي أن يتصرف.

اختبر خمس حالات قبل الإنتاج

اختبر التدفق كاملًا باستخدام نماذج وهمية، لا حسابات حقيقية:

1. المسار السعيد: رمز وصول صالح واستدعاء ناجح.
2. رمز وصول منتهي: يعود 401، فيحدّث المدير الرمز ويعيد المحاولة مرة واحدة بنجاح.
3. رمز تحديث مُلغى: يعود invalid_grant، فيتوقف الوكيل ويبلغ المستخدم.
4. نطاق غير كافٍ: يعود 403، ولا يعيد الوكيل المحاولة ويذكر النطاق المفقود.
5. تحديث متزامن: استدعاءان للمستخدم نفسه، لكن تحديث واحد فقط يحدث.

في Apidog، عرّف نقطة نهاية للرموز وأخرى محمية، ثم حاكِ استجابات النجاح والفشل ونصوص الأخطاء. راجع تشغيل الوكلاء مقابل النماذج الوهمية بدل الإنتاج ودليل اختبار OAuth 2 API.

أمثلة عملية

مساعد تقويم

يقرأ التوافر ويحجز اجتماعات لمستخدم واحد.

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

وكيل دعم لصندوق بريد مشترك

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

وكيل عمليات داخلي

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

• لا توجد بيانات مستخدم.
• لا تحتاج إلى تفويض.
• استخدم حساب خدمة محدود النطاق وركز على التدوير وتقليل نطاق التأثير.

خط الفصل بسيط: إذا كانت البيانات تخص شخصًا قد يرغب في إلغاء وصولك، استخدم OAuth المفوّض. إذا كانت تخص نظامك، استخدم حساب خدمة.

حافظ على الإسناد البشري

OAuth يجيب عن سؤال: نيابة عن من تصرف الوكيل؟ لكنه لا يجيب عن سؤال: من طلب تشغيله؟

سجّل الهويتين بجانب العملية:

• معرف المستخدم الذي يملك التفويض.
• اسم الوكيل.
• النطاق المستخدم.
• معرف الرمز المميز، وليس الرمز نفسه.
• الشخص أو النظام الذي طلب التشغيل.

يمكن لطبقة إدارة العمل، مثل Sharkly وتوثيق Sharkly، حفظ المسؤول البشري بجانب الوكيل أو الفريق المنفذ.

لا تدع النموذج يرى بيانات الاعتماد

هذه قاعدة معمارية تمنع معظم حوادث المصادقة:

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

لذلك:

• لا تضف حقل token إلى مخطط الأداة.
• لا تضع بيانات الاعتماد في الموجه.
• لا تعرض رأس Authorization في نتائج الأداة.
• لا تسمح للنموذج بتحديد المستخدم الذي سيتصرف الوكيل باسمه.

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

قائمة مرجعية

• استخدم الوصول المفوّض لبيانات المستخدمين، وحسابات الخدمة لمواردك فقط.
• استخدم رمز التفويض مع PKCE عند الاتصال، ومنحة الجهاز للبيئات بلا واجهة رسومية.
• اطلب أقل نطاق لكل وكيل، وصعّده تدريجيًا.
• امنح الوكلاء الفرعيين رموزًا متبادلة وأضيق نطاقًا.
• شفّر رموز التحديث ولا تضعها في الموجهات أو السجلات أو التتبعات.
• اجعل مدير الرموز مسؤولًا عن التحديث والتدوير والتسلسل لكل مستخدم.
• تعامل مع 401 و403 كأخطاء نهائية.
• اكتشف المنح المنتهية وأبلغ المستخدم بدل إعادة المحاولة ليلًا.
• أضف موافقة مستقلة للإجراءات عالية المخاطر.
• اختبر حالات المصادقة الخمس على نماذج وهمية في CI.

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

الأسئلة المتكررة

هل يستطيع الوكيل إكمال موافقة OAuth بنفسه؟

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

هل يحتاج كل وكيل إلى عميل OAuth خاص؟

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

ماذا لو فاتني رمز التحديث الجديد بعد التدوير؟

سيُحظر المستخدم ويحتاج إلى إعادة الاتصال. احفظ الرمز الجديد في المعاملة نفسها التي تستهلك الرمز القديم، وسلسل التحديثات لكل مستخدم.

هل من الآمن أن يرى النموذج رمز الوصول؟

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

كيف أراجع ما فعله كل وكيل؟

سجّل معرف المستخدم، واسم الوكيل، والنطاق، ومعرف الرمز المميز في كل استدعاء، ولا تسجل الرمز نفسه أبدًا.

ماذا لو لم يدعم المزود تبادل الرموز؟

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