استخدام واجهة برمجة التطبيقات Cato SCIM لتطبيقات SCIM المخصصة

تصف هذه المقالة كيفية استخدام واجهة برمجة التطبيقات SCIM من Cato لتوفير المستخدمين ومجموعات المستخدمين مع مقدم الهوية (IdP).

لمزيد من المعلومات حول تطبيقات SCIM المخصصة في مستأجر IdP، انظر إنشاء تطبيق SCIM مخصص لمستأجر IdP.

تطبيق Cato SCIM المخصص

لإستخدام تطبيق SCIM مخصص لتوفير المستخدمين ومجموعات المستخدمين لحسابك في Cato، إنشاء التطبيق في تطبيق إدارة Cato (CMA). بالإضافة إلى ذلك، تحتاج إلى مطابقة سمات SCIM من Cato مع السمات لمقدم الهوية (IdP).

إنشاء تطبيق SCIM مخصص في CMA

لاستخدام واجهة برمجة التطبيقات SCIM، يجب أولاً إنشاء تطبيق SCIM مخصص في CMA. يتيح لك هذا التطبيق دمج مزود الهوية الخاص بك (IdP) مع منصة Cato.

لإنشاء تطبيق SCIM مخصص في CMA:

1. من القائمة التنقل، اختر الوصول > خدمات الدليل.

2. تحت علامة تبويب SCIM، انقر على جديد.

3. أدخل اسمًا للتطبيق.

4. تحت المزود، حدد مخصص.

5. انقر على توليد الرمز ونسخ القيمة؛ لن تكون متاحة بعد الحفظ وستحتاج إلى إنشاء رمز جديد. 

6. انقر فوق حفظ.

7. عند الاتصال بنقاط نهاية SCIM API الموضحة أدناه، ستحتاج إلى القيم التالية للمصادقة:

   • عنوان URL الأساسي لـ SCIM: يستخدم كنقطة أساس لطلبات واجهة برمجة التطبيقات

   • رمز حامل: يستخدم لمصادقة طلبات واجهة برمجة التطبيقات

سمات SCIM من Cato

هذه هي السمات SCIM لمستخدمي Cato ومجموعات المستخدمين التي تحتاج إلى مطابقتها مع السمات المقابلة لمقدم الهوية (IdP).

فهم واجهة برمجة التطبيقات Cato SCIM

مصادقة واجهة برمجة التطبيقات Cato SCIM

يقوم العملاء بالمصادقة لواجهة برمجة التطبيقات SCIM باستخدام مصادقة الرمز الحامل، كما هو معرفًا بواسطة RFC 6750. يجب أن تتضمن جميع طلبات واجهة برمجة التطبيقات رؤوس HTTP التالية:

التفويض: حامل <access_token>
نوع المحتوى: application/json

يمكنك الحصول على رمز الوصول من تطبيق إدارة Cato.

المسار الأساسي لنقاط نهاية SCIM

تستخدم جميع نقاط نهاية واجهة برمجة التطبيقات SCIM المسار الأساسي التالي:

/scim/v2/{accountId}/{sourceId}

معلمات المسار: 

• accountId (string): معرف فريد لحساب مستأجر Cato الخاص بك

• sourceId (integer): معرف مخصص من قبل Cato لتمثيل تكامل IdP محدد بشكل فريد

هذه المعلمات مطلوبة في جميع الطلبات ولكن تم حذفها من مسارات نقاط النهاية الفردية في هذه المقالة لتوفير الوقت.

إدارة المستخدمين

يتناول هذا القسم كيفية إنشاء وتحديث وحذف واسترجاع كيانات المستخدم SCIM باستخدام واجهة برمجة التطبيقات Cato SCIM.

إنشاء مستخدم

طريقة HTTP:POST /Users 

الحقول المطلوبة: 

• userName (string): اسم مستخدم فريد (مثل عنوان البريد الإلكتروني)

• externalId (string): معرف خارجي من IdP

• active (boolean): يجب أن يكون true لتفعيل المستخدم

ملحوظة:id يُرجع بواسطة خدمة SCIM ويجب استخدامه في المكالمات التالية لواجهة برمجة التطبيقات. externalId اختياري ولا يمكن استخدامه في مسارات واجهة برمجة التطبيقات.

الاستجابة: 

• الحالة: 201 تم الإنشاء

الأخطاء: 

• 400 طلب سيء: مخطط غير صالح

• 401 غير مصرح به 

• 409 تعارض: تكرار userName أو externalId

تحديث مستخدم

PUT

طريقة HTTP:PUT /Users/{id} 

الحقل المطلوب: 

• id: معرف SCIM الداخلي من Cato

الاستجابة: 

• الحالة: 200 تم

الأخطاء: 

• 401 غير مصرح به 

• 404 لم يتم العثور على 

• 409 تعارض: تكرار userName أو externalId

PATCH

طريقة HTTP:PATCH /Users/{id} 

الاستجابة: 

• الحالة: 200 تم

الأخطاء: 

• 400 طلب غير صالح: بنية غير صالحة أو خطأ في التصحيح

• 401 غير مصرح به 

• 404 لم يتم العثور على 

• 409 تعارض: معرفات مكررة

حذف مستخدم

طريقة HTTP:DELETE /Users/{id}

استجابة:

• الحالة: 204 لا يوجد محتوى

هذه عملية حذف ناعمة. يبقى المستخدم في النظام ولكن لا يتم إعادته في عمليات البحث.

الحصول على مستخدم بواسطة الرمز

طريقة HTTP:GET /Users/{id}

استجابة:

• الحالة: 200 تم

الأخطاء:

• 401 غير مصرح

• 404 غير موجود

بحث المستخدمين

طريقة HTTP:GET /Users

معايير الاستعلام:

• filter: استعلام لتصفية المستخدمين (مثل، userName eq "user@domain.com")

• count (اختياري)

• startIndex (اختياري)

المرشحات المدعمة:

• فقط eq مدعوم

• السمات المدعومة: userName, email, givenName, familyName

• تُدعم المرشحات المركبة فقط بهذا الشكل:

  filter=emails[type eq "work"] و email eq "bob@cato.com"

استجابة:

• الحالة: 200 تم

الأخطاء:

• 401 غير مصرح

إدارة المجموعات

يشرح هذا القسم كيفية استخدام SCIM API لإنشاء، تحديث، حذف، واسترجاع الكيانات الجماعية في بيئة Cato الخاصة بك.

إنشاء مجموعة

طريقة HTTP:POST /Groups

استجابة:

• الحالة: 201 تم الإنشاء

الأخطاء:

• 401 غير مصرح

• 409 تعارض: تكرار displayName أو معرف الكائن

تحديث مجموعة

PUT

طريقة HTTP:PUT /Groups/{id}

استجابة:

• الحالة: 200 تم

الأخطاء:

• 401 غير مصرح

• 404 غير موجود

• 409 تعارض

PATCH

طريقة HTTP:PATCH /Groups/{id}

مسارات التصحيح المدعومة:

• displayName

• members

استجابة:

• الحالة: 200 تم

الأخطاء:

• 400 طلب غير صالح: بنية غير صالحة أو خطأ في التصحيح

• 401 غير مصرح

• 404 غير موجود

• 409 تعارض

حذف مجموعة

طريقة HTTP:DELETE /Groups/{id}

استجابة:

• الحالة: 204 لا يوجد محتوى

مهم:

هذه عملية حذف نهائية. يتم إزالة المجموعة بشكل دائم.

الحصول على مجموعة حسب المعرف

طريقة HTTP:GET /Groups/{id}

معايير استعلام اختيارية:

• excludeAttributes (مثال: members)

استجابة:

• الحالة: 200 تم

الأخطاء:

• 401 غير مصرح

• 404 غير موجود

البحث في المجموعات

طريقة HTTP:GET /Groups

معايير الاستعلام:

• filter: فقط displayName eq "اسم المجموعة" مدعوم

• count (اختياري)

• startIndex (اختياري)

مرشحات مركبة أو مشغلات غير مدعومة تُرجع جميع المجموعات بدون تصفية.

استجابة:

• الحالة: 200 تم

الأخطاء:

• 401 غير مصرح

الملاحظات

سلوك حقل المعرف عند الإنشاء

• حقل id اختياري في طلبات إنشاء المستخدم والمجموعة.

• إذا تم حذفه، يقوم SCIM بإنشاء معرف id فريد.

• يجب دائمًا استخدام القيمة id المرجعة في مكالمات API اللاحقة.

مهم:

تجنب استخدام معرفات العميل إلا إذا كان ذلك مطلوبًا. معرف SCIM هو المعرف الرسمي.

سلوك الحذف

• حذف المستخدم عبر DELETE /Users/{id} يقوم بأداء حذف ناعم بتعيين حقل active إلى false. يمكن استرجاع المستخدم عبر GET /Users/{id} ولكنه مستبعد من نتائج GET /Users.

• حذف المجموعة عبر DELETE /Groups/{id} يقوم بأداء حذف نهائي. يتم إزالة المجموعة بشكل دائم.