कस्टम SCIM ऐप्स के लिए Cato SCIM API का उपयोग करना

यह लेख Cato के SCIM API का उपयोगकर्ता और उपयोगकर्ता समूह के प्रोविजनिंग के लिए पहचान प्रदाता (IdP) के साथ कैसे उपयोग करें, इसका वर्णन करता है।

IdP किरायेदार में कस्टम SCIM ऐप्स के बारे में अधिक जानकारी के लिए, IdP के लिए एक कस्टम SCIM ऐप बनाना देखें।

कस्टम Cato SCIM ऐप

अपने Cato खाते के लिए उपयोगकर्ता और उपयोगकर्ता समूहों को प्रोवाइड करने के लिए कस्टम SCIM ऐप का उपयोग करने के लिए, Cato प्रबंधन एप्लिकेशन (CMA) में ऐप बनाएं। इसके अलावा, आपको Cato SCIM विशेषताओं को अपने IdP के विशेषताओं के लिए मैप करना होगा।

CMA में एक कस्टम SCIM ऐप बनाएं

SCIM API का उपयोग करने के लिए, आपको पहले CMA में एक कस्टम SCIM ऐप बनाना होगा। यह ऐप आपको अपने पहचान प्रदाता (IdP) को Cato प्लेटफ़ॉर्म के साथ एकीकृत करने की अनुमति देता है।

CMA में कस्टम SCIM ऐप बनाने के लिए:

1. नेविगेशन मेनू से, पहुँच > डायरेक्टरी सेवाएं चुनें।

2. SCIM टैब के अंतर्गत, New पर क्लिक करें।

3. ऐप के लिए एक नाम दर्ज करें।

4. प्रदाता के अंतर्गत,  कस्टम चुनें।

5. Generate Token पर क्लिक करें और मान प्रतिलिपि करें; यह संचित करने के बाद उपलब्ध नहीं होगा और आपको एक नया टोकन बनाना होगा। 

6. सहेजें क्लिक करें।

7. नीचे दिए गए SCIM API एन्डपॉइंट्स को कॉल करते समय, आपको प्रमाणीकरण के लिए निम्नलिखित मानों की आवश्यकता होगी:

   • SCIM Base URL: API अनुरोधों के लिए आधार पथ के रूप में उपयोग किया जाता है

   • Bearer Token: API अनुरोधों का प्रमाणीकरण करने के लिए उपयोग किया जाता है

Cato SCIM विशेषताएँ

ये Cato उपयोगकर्ताओं और उपयोगकर्ता समूहों के लिए SCIM विशेषताएँ हैं जिन्हें IdP विशेषताओं के लिए मैप करने की आवश्यकता है।

Cato SCIM API को समझना

Cato SCIM API के लिए प्रमाणीकरण

क्लाइंट RFC 6750 द्वारा परिभाषित बेयर टोकन प्रमाणीकरण का उपयोग करके SCIM API के लिए प्रमाणीकरण करते हैं। सभी API अनुरोधों में निम्नलिखित HTTP हेडर शामिल होना चाहिए:

Authorization: Bearer <access_token>
Content-Type: application/json

आप Cato प्रबंधन एप्लिकेशन से पहुंच टोकन प्राप्त कर सकते हैं।

SCIM एंडपॉइंट्स के लिए आधार पथ

सभी SCIM API एंडपॉइंट्स निम्नलिखित आधार पथ का उपयोग करते हैं:

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

पथ पैरामीटर: 

• accountId (string): आपके Cato किरायेदार खाते की अद्वितीय पहचानकर्ता

• sourceId (integer): Cato द्वारा ऐसे विशिष्ट IdP एकीकरण का अनन्य रूप से प्रतिनिधित्व करने के लिए असाइन किया गया पहचानकर्ता

ये पैरामीटर सभी अनुरोधों में आवश्यक हैं लेकिन इस लेख के व्यक्तिगत एंडपॉइंट पथ में संक्षिप्तता के लिए छोड़े गए हैं।

उपयोगकर्ताओं का प्रबंधन

यह अनुभाग Cato SCIM API का उपयोग करके SCIM उपयोगकर्ता संस्थाओं को बनाने, अपडेट करने, हटाने और पुनः प्राप्त करने का वर्णन करता है।

उपयोगकर्ता बनाएँ

HTTP विधि:POST /Users 

आवश्यक फ़ील्ड: 

• userName (string): अद्वितीय उपयोगकर्ता नाम (जैसे, ईमेल पता)

• externalId (string): IdP से बाहरी पहचानकर्ता

• active (boolean): उपयोगकर्ता को सक्रिय करने के लिए true होना चाहिए

नोट:id SCIM सेवा द्वारा लौटाया जाता है और बाद के API कॉल में उपयोग किया जाना चाहिए। externalId वैकल्पिक है और API पथों में उपयोग नहीं किया जा सकता।

प्रतिक्रिया: 

• स्थिति: 201 निर्मित

त्रुटियाँ: 

• 400 Bad Request: अमान्य स्कीमा

• 401 Unauthorized 

• 409 Conflict: डुप्लिकेट userName या externalId

उपयोगकर्ता को अपडेट करें

PUT

HTTP विधि:PUT /Users/{id} 

आवश्यक फ़ील्ड: 

• id: Cato से आंतरिक SCIM ID

प्रतिक्रिया: 

• स्थिति: 200 OK

त्रुटियाँ: 

• 401 Unauthorized 

• 404 Not Found 

• 409 Conflict: डुप्लिकेट userName या externalId

PATCH

HTTP विधि:PATCH /Users/{id} 

प्रतिक्रिया: 

• स्थिति: 200 OK

त्रुटियाँ: 

• 400 खराब अनुरोध: अमान्य स्कीमा या पैच सिंटैक्स

• 401 Unauthorized 

• 404 Not Found 

• 409 Conflict: डुप्लिकेट पहचानकर्ता

उपयोगकर्ता को हटाएं

HTTP विधि:DELETE /Users/{id}

प्रतिक्रिया:

• स्थिति: 204 कोई सामग्री नहीं

यह एक सॉफ़्ट डिलीट है। उपयोगकर्ता सिस्टम में रहता है लेकिन खोजों में लौटाया नहीं जाता।

ID द्वारा उपयोगकर्ता प्राप्त करें

HTTP विधि:GET /Users/{id}

प्रतिक्रिया:

• स्थिति: 200 OK

त्रुटियाँ:

• 401 Unauthorized

• 404 Not Found

उपयोगकर्ताओं को खोजें

HTTP विधि:GET /Users

क्वेरी मापदंड:

• filter: उपयोगकर्ताओं को फ़िल्टर करने के लिए प्रश्न (जैसे, userName eq "user@domain.com")

• count (वैकल्पिक)

• startIndex (वैकल्पिक)

समर्थित फ़िल्टर:

• केवल eq समर्थित है

• समर्थित विशेषताएँ: userName, email, givenName, familyName

• सम्मिलित फ़िल्टर केवल इस प्रारूप में समर्थित हैं:

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

प्रतिक्रिया:

• स्थिति: 200 OK

त्रुटियाँ:

• 401 Unauthorized

समूह प्रबंधन

यह अनुभाग बताता है कि आपके Cato वातावरण में समूह संस्थाओं को बनाने, अद्यतन करने, हटाने और प्राप्त करने के लिए SCIM API का उपयोग कैसे करें।

एक समूह बनाएं

HTTP विधि:POST /Groups

प्रतिक्रिया:

• स्थिति: 201 निर्मित

त्रुटियाँ:

• 401 Unauthorized

• 409 संघर्ष: डुप्लिकेट displayName या ऑब्जेक्ट आईडी

एक समूह अपडेट करें

PUT

HTTP विधि:PUT /Groups/{id}

प्रतिक्रिया:

• स्थिति: 200 OK

त्रुटियाँ:

• 401 Unauthorized

• 404 Not Found

• 409 संघर्ष

PATCH

HTTP विधि:PATCH /Groups/{id}

समर्थित पैच पथ:

• displayName

• सदस्य

प्रतिक्रिया:

• स्थिति: 200 OK

त्रुटियाँ:

• 400 खराब अनुरोध: अमान्य स्कीमा या पैच सिंटैक्स

• 401 Unauthorized

• 404 Not Found

• 409 संघर्ष

एक समूह हटाएं

HTTP विधि:DELETE /Groups/{id}

प्रतिक्रिया:

• स्थिति: 204 कोई सामग्री नहीं

महत्वपूर्ण:

यह एक हार्ड डिलीट है। समूह स्थायी रूप से हटा दिया गया है।

आईडी द्वारा एक समूह प्राप्त करें

HTTP विधि:GET /Groups/{id}

विकल्प क्वेरी मापदंड:

• exludeAttributes (उदा., सदस्य)

प्रतिक्रिया:

• स्थिति: 200 OK

त्रुटियाँ:

• 401 Unauthorized

• 404 Not Found

समूह खोजें

HTTP विधि:GET /Groups

क्वेरी मापदंड:

• filter: केवल displayName eq "Group Name" समर्थित है

• count (वैकल्पिक)

• startIndex (वैकल्पिक)

संयुक्त फिल्टर या असमर्थित ऑपरेटर बिना फिल्टरिंग के सभी समूह लौटाते हैं।

प्रतिक्रिया:

• स्थिति: 200 OK

त्रुटियाँ:

• 401 Unauthorized

नोट्स

सृजन पर आईडी फ़ील्ड का व्यवहार

• उपयोगकर्ता और समूह निर्माण अनुरोधों में आईडी फ़ील्ड वैकल्पिक है।

• यदि छोड़ा गया है, तो SCIM सेवा एक अद्वितीय आईडी उत्पन्न करती है।

• समी API कॉल में हमेशा लौटाई गई आईडी मान का उपयोग करें।

महत्वपूर्ण:

आवश्यक न हो, तो क्लाइंट-जनित ID का प्रयोग न करें। SCIM आईडी अधिकारिक पहचानकर्ता है।

हटाए जाने का व्यवहार

• उपयोगकर्ता हटाना DELETE /Users/{id} के माध्यम से मृदु हटाना करता है, सक्रिय फ़ील्ड को गलत पर सेट करता है। GET /Users/{id} के माध्यम से उपयोगकर्ता पुनः प्राप्त किया जा सकता है लेकिन GET /Users परिणामों से बाहर रखा गया है।

• समूह हटाना DELETE /Groups/{id} के माध्यम से कठोर हटाना करता है। समूह स्थायी रूप से हटा दिया गया है।