قواعد الأمان لمستهلكي واجهة برمجة التكامل
يحمي اتباع هذه القواعد بيانات استبيانات المؤسسة ويقلل من خطر الوصول غير المصرح به عبر مفاتيح التكامل المخترقة.
1. احفظ المفاتيح في أنظمة إدارة الأسرار
لا تخزّن مفتاح API أبدا في:
- الكود المصدري أو التحكم في الإصدارات (حتى المستودعات الخاصة).
- ملفات التكوين المضافة إلى مستودع التحكم في الإصدارات.
- JavaScript من جانب العميل أو ملفات ثنائية لتطبيقات الجوال أو أي كود يُشحن للمستخدمين النهائيين.
- ملفات نصية على محركات أقراص مشتركة أو wikis.
احفظ المفاتيح في:
- متغيرات البيئة المُضخَّة عند وقت النشر.
- مدير أسرار مثل Azure Key Vault أو AWS Secrets Manager أو HashiCorp Vault أو نظام معادل.
- مخازن أسرار خطوط CI/CD (وليس في ملفات YAML لخط الأنابيب نفسه).
2. امنح الحد الأدنى من النطاقات المطلوبة
اطلب فقط النطاقات التي يحتاجها التكامل فعلا. إذا كان التكامل يقرأ تقارير تجميعية فقط، اطلب ReportsRead فقط — لا تطلب UsageRead أو RawResponsesRead "احتياطا".
هذا يحد من انكشاف البيانات في حال اختراق مفتاح.
3. دوّر المفاتيح بانتظام
أنشئ جدول تدوير مناسبًا لسياسة الأمان في مؤسستك (مثلًا، كل 90 يومًا). يُجري مسؤول المؤسسة التدوير من لوحة التحكم.
نسّق نافذة انتقال قصيرة مع النظام المستهلك. يلغي التدوير المفتاح القديم فورًا ولا يكشف البديل إلا بعد إجراء التدوير، لذلك لا يوفر العقد الحالي فترة تداخل يكون فيها المفتاحان صالحين.
4. دوّر فورا بعد الاشتباه بالاختراق
إذا كان مفتاح ما قد انكشف — مثلا، سُجّل عرضا أو أُضيف إلى مستودع بالخطأ أو أُرسل عبر قناة غير آمنة — دوّره فورا. يُلغى المفتاح القديم لحظة تأكيد التدوير.
بعد التدوير، راجع سجلات النظام المستهلك للتحقق مما إذا كان المفتاح قد استُخدم من أطراف غير مصرح لها خلال فترة الانكشاف.
5. لا تشارك المفاتيح بين الأنظمة
يجب أن يمتلك كل نظام مستهلك أو تكامل عميله ومفتاحه المستقل. هذا يتيح تدوير المفاتيح الفردية أو إلغاءها دون التأثير على التكاملات الأخرى.
6. استخدم HTTPS حصرا
يجب أن تستخدم جميع طلبات واجهة برمجة التكامل HTTPS. لا ترسل مفاتيح API أبدا عبر HTTP العادي.
7. تحقق من الاستجابات على جانبك
تعيد واجهة برمجة التكامل البيانات المتعلقة بالمؤسسة التي استُخدم مفتاحها فقط. ومع ذلك، تحقق من surveyId والمعرفات الأخرى في الاستجابات مقابل سجلاتك الخاصة لاكتشاف أي بيانات غير متوقعة.
8. تعامل مع استجابات 429 بشكل صحيح
نفّذ تراجعًا أسيًا واحترم Retry-After عند وجودها بعد HTTP 429. تدعم خدمة التكامل الحالية حالتي النشاط والإلغاء، لكنها لا توثق تعليقًا تلقائيًا أو مؤقتًا للمفتاح كنتيجة لتحديد المعدل.
9. لا تسجّل قيم المفاتيح الكاملة
تأكد من أن كود التكامل وسجلات البنية التحتية وأنظمة المراقبة لا تلتقط قيمة الترويسة X-Survanta-Api-Key الكاملة. إذا كان التسجيل مطلوبا لأغراض تصحيح الأخطاء، سجّل بادئة المفتاح فقط.