انتقل إلى المحتوى الرئيسي

إدارة مفاتيح API

توفر مفاتيح واجهة برمجة التطبيقات (API) مصادقة خدمة إلى خدمة لعمليات التكامل والبرامج النصية والأنظمة الخارجية التي تحتاج إلى التفاعل مع AuroraSOC برمجيًا.

متى يتم استخدام مفاتيح API مقابل JWT​

حالة الاستخدامالمصادقة الموصى بهاسبب
تسجيل الدخول إلى لوحة القيادةJWTتفاعلية، على أساس الجلسة
تكامل SIEMمفتاح واجهة برمجة التطبيقاتخدمة طويلة الأمد
خط أنابيب CI/CDمفتاح واجهة برمجة التطبيقاتآلية وغير تفاعلية
البرامج النصية المخصصةمفتاح واجهة برمجة التطبيقاتلا حاجة لتدفق تسجيل الدخول
تطبيق الجوالJWTجلسات خاصة بالمستخدم
استقبال ويب هوكمفتاح واجهة برمجة التطبيقاتالتحقق من عديمي الجنسية

تنسيق المفتاح​

تتبع مفاتيح API التي تم إنشاؤها هذا التنسيق:

aurora_<64_random_hex_characters>

مثال:

aurora_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4

تعمل البادئة aurora_ على تسهيل التعرف على المواد الأساسية في الماسحات الضوئية السرية ومرشحات السجل.

دورة حياة مفتاح API​

إنشاء مفتاح​

curl -X POST /api/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN_WITH_USERS_MANAGE" \
  -H "Content-Type: application/json" \
  -d '{
    "service_name": "suricata-forwarder",
    "expires_in_days": 90,
    "permissions": ["alerts:read", "iocs:write"]
  }'

إجابة:

{
  "id": "7c557b75-16cf-4d15-8f6a-f8ee5f0e19d7",
  "service_name": "suricata-forwarder",
  "api_key": "aurora_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4",
  "key_prefix": "aurora_a1b2c3d4e5",
  "permissions": ["alerts:read", "iocs:write"],
  "created_by": "admin",
  "created_at": "2026-04-05T09:21:13.442176+00:00",
  "expires_at": "2026-07-04T09:21:13.442163+00:00",
  "message": "Store this API key securely now. It will not be shown again."
}

ملحوظات:

  • expires_in_days اختياري. اضبطه على null للحصول على مفتاح غير منتهي الصلاحية.
  • permissions اختياري. إذا تم حذفه، فإن AuroraSOC يطبق مجموعة أذونات api_service الافتراضية.
  • يتم إرجاع api_key الخام مرة واحدة فقط.

مفاتيح القائمة​

curl -X GET /api/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN_WITH_USERS_MANAGE"

تعرض الاستجابة بيانات التعريف الرئيسية فقط (وليس قيمة المفتاح الكاملة أبدًا):

{
  "api_keys": [
    {
      "id": "7c557b75-16cf-4d15-8f6a-f8ee5f0e19d7",
      "service_name": "suricata-forwarder",
      "key_prefix": "aurora_a1b2c3d4e5",
      "role": "api_service",
      "permissions": ["alerts:read", "iocs:write"],
      "is_active": true,
      "created_by": "admin",
      "created_at": "2026-04-05T09:21:13.442176+00:00",
      "expires_at": "2026-07-04T09:21:13.442163+00:00",
      "last_used_at": "2026-04-05T10:41:03.107511+00:00",
      "revoked_at": null
    }
  ],
  "total": 1
}

إلغاء المفتاح​

curl -X DELETE /api/v1/auth/api-keys/7c557b75-16cf-4d15-8f6a-f8ee5f0e19d7 \
  -H "Authorization: Bearer $TOKEN_WITH_USERS_MANAGE"

يكون الإلغاء فوريًا — أي طلب يستخدم المفتاح الذي تم إبطاله سوف يتلقى 401 Unauthorized.

أمان تخزين المفاتيح​

AuroraSOC لا تقوم أبدًا بتخزين مفاتيح واجهة برمجة التطبيقات ذات النص العادي. يتم الاحتفاظ بتجزئة SHA-256 فقط. هذا يعنى:

  • إذا تم اختراق قاعدة البيانات، فلا يمكن استخراج مفاتيح API
  • لا يمكن استرداد المفاتيح المفقودة — يجب إنشاء مفتاح جديد
  • تستخدم المقارنة الرئيسية عمليات فحص التجزئة الآمنة للتوقيت

رأس المصادقة​

استخدم مفاتيح API مع رأس X-API-Key:

X-API-Key: aurora_<...>

تدعم AuroraSOC أيضًا مفتاح البيئة الثابت (API_SERVICE_KEY) لعمليات التكامل على مستوى البنية التحتية. يوصى باستخدام المفاتيح المُدارة والمدعومة بقاعدة البيانات للتدقيق وانتهاء الصلاحية والإلغاء.

الحد من المعدل​

تخضع الطلبات المصادق عليها لمفتاح واجهة برمجة التطبيقات (API) لحدود نقطة النهاية ومعدل الخدمة. عند تجاوز هذه القيمة، تقوم AuroraSOC بإرجاع 429 Too Many Requests.

أفضل الممارسات​

  1. مفتاح واحد لكل عملية تكامل — إنشاء مفاتيح منفصلة لكل خدمة
  2. مبدأ الامتياز الأقل — قم بتعيين الحد الأدنى من الأذونات المطلوبة فقط
  3. التدوير بانتظام — أنشئ مفاتيح جديدة كل ثلاثة أشهر، وألغِ المفاتيح القديمة
  4. استخدام الشاشة — تحقق من الطوابع الزمنية last_used بحثًا عن المفاتيح غير المستخدمة
  5. استخدام مديري الأسرار — قم بتخزين المفاتيح في HashiCorp Vault، أو AWS Secrets Manager، أو ما شابه ذلك
  6. لا تستخدم الكود الثابت أبدًا — استخدم متغيرات البيئة، وليس كود المصدر
  7. مسار التدقيق — يتم تسجيل كافة عمليات إنشاء مفتاح واجهة برمجة التطبيقات وعمليات الإلغاء